Authentication

This guide covers Armor’s comprehensive authentication system, including local users, OIDC integration, and API key management.

Authentication Overview
Local User Authentication
OIDC Authentication
API Key Authentication
Swagger UI Authentication
1. Existing API Keys
2. Temporary Keys
JWT Token Management
1. Token Structure
2. Token Validation
Security Best Practices
1. Production Deployment
2. Network Security
Troubleshooting
Related Documentation

Authentication Overview

Armor provides three authentication methods for maximum compatibility:

Local User Authentication - Username/password accounts
OIDC Authentication - Google, Microsoft, etc.
API Key Authentication - Bearer tokens for automation

Local User Authentication

User Configuration

Edit your config.yaml to define local users:

authentication:
  jwt_secret: "your-jwt-secret-key-change-this"
  jwt_expiration: "24h"
  local:
    users:
      - username: admin
        password: admin123
        role: admin
        id: 1
      - username: user
        password: user123
        role: user
        id: 2

User Roles

Admin Role (role: admin)

File operations: Upload, download, delete, rename
Folder management: Create and manage directories
API key creation: Generate keys with any permissions
System access: All file operations and management features

User Role (role: user)

File access: Download files only
Browse directories: Navigate file structure
API key creation: Generate download-only keys
Limited access: Cannot upload, delete, or modify files

Navigate to your Armor server
Click “Login” button
Enter username and password
Access granted based on user role

The /login page accepts query parameters that control which authentication options are displayed. These are useful for deep-linking to a specific sign-in flow (for example, from a marketing page or partner portal):

Parameter	Effect
(none)	Default view. Shows basic auth (unless `basic_auth_hidden: true`) and all enabled, non-hidden OIDC providers.
`?oidc_provider=<name>`	Auto-initiates the OIDC flow for the named provider. If the user has an active session with that IdP, they land back in Armor authenticated without any clicks. If not, the IdP’s own login page is shown. The provider may be marked `hidden: true` in config — the parameter overrides that and the provider’s button would be shown only as a fallback if auto-redirect is suppressed (see guards below).
`?auth_method=basic`	Forces basic auth to render even when `basic_auth_hidden: true`. Note: when combined with `?oidc_provider=<name>`, the OIDC auto-redirect fires first and the basic auth form only appears if the user is bounced back with an error.
`?return=<url>`	URL-encoded path to redirect to after successful login. Preserved across the OIDC flow.

Example: https://downloads.example.com/login?oidc_provider=prominic immediately initiates the Prominic.NET OIDC flow. Users with an existing Prominic session land on the app with zero clicks.

Auto-redirect guards

The auto-initiation is suppressed when any of the following URL parameters are present, to avoid redirect loops after a failed or just-completed flow:

?error=<code> (set automatically by the OIDC callback on failure)
?logout=success (set after RP-initiated logout)
?session=expired (set after backchannel-logout revocation)

A 10-second sessionStorage brake also prevents rapid re-redirects if an IdP bounces back without completing the flow. In these cases the provider’s sign-in button is rendered instead, and the user can click to retry manually.

Escape hatch: to bypass auto-redirect for any reason (e.g., to switch accounts at the IdP or use basic auth with an already-configured OIDC link), visit /login without the oidc_provider query parameter.

HTTP Basic Authentication

For CLI tools and automation:

# wget style (recommended for file downloads)
wget --no-check-certificate "https://admin:admin123@your-server/file.txt"

# curl style
curl -k -u admin:admin123 https://your-server/file.txt

# API operations
curl -k -u admin:admin123 \
  -H "Accept: application/json" \
  https://your-server/uploads/

OIDC Authentication

Google Integration

Configure Google OAuth for web authentication:

authentication:
  oidc_providers:
    google:
      enabled: true
      client_id: "your-google-client-id.googleusercontent.com"
      client_secret: "your-google-client-secret"
      display_name: "Sign in with Google"
      issuer: "https://accounts.google.com"
      scope: "openid email profile"

Setting Up Google OAuth

Google Cloud Console:
- Create new project or select existing
- Configure the OAuth consent screen (set app info, scopes, and test users as needed)
- Create OAuth 2.0 credentials

Configure Redirect URI:

https://your-domain.com/auth/oidc/callback

Add Credentials to Config:

authentication:
  oidc_providers:
    google:
      enabled: true
      client_id: "your-app-id.googleusercontent.com"
      client_secret: "your-client-secret"

OIDC User Permissions

OIDC users get permissions based on:

Domain mapping: Configure permissions by email domain
Manual assignment: Assign permissions via configuration
Default permissions: Usually full admin access

authentication:
  permission_strategy: "domain_based"
  domain_mappings:
    downloads: ["*"]                    # All domains get downloads
    uploads: ["company.com"]            # Only company.com gets uploads
    delete: ["company.com"]             # Only company.com gets delete

OIDC Logout (RP-Initiated Logout)

Armor supports RP-initiated logout for OIDC providers that implement the OpenID Connect Session Management specification.

How It Works

When an OIDC-authenticated user logs out:

Local Session Cleared: JWT token is removed from browser
Provider Logout: User is redirected to OIDC provider’s logout endpoint
Provider Session Cleared: OIDC provider terminates the user’s session
Return to Application: User is redirected back to login page with success message

Configuration Requirements

OIDC Provider Setup (Required):

Configure post-logout redirect URI in your OIDC provider
URI format: https://your-domain.com/login?logout=success
For port 443: https://your-domain.com/login?logout=success
For other ports: https://your-domain.com:8443/login?logout=success

Application Configuration (Automatic):

No additional configuration needed in config.yaml
Redirect URI is built dynamically from server domain and port
Logout flow activates automatically for OIDC users

Provider-Specific Notes

Google OAuth:

Supports RP-initiated logout
Configure redirect URI in Google Cloud Console OAuth settings

Microsoft Azure AD:

Supports RP-initiated logout
Configure redirect URI in Azure App Registration

Domino OIDC Provider:

Logout endpoint: /auth/protocol/oidc/logout
Configure in “Post logout redirect URI(s)” field
Cannot be used with Multi-Server SSO (LTPA) configurations

Testing Logout Flow

Login via OIDC: Use “Sign in with [Provider]” button
Access Protected Resource: Verify authentication works
Logout: Click logout button or navigate to /logout
Verify Provider Logout: Should redirect to provider logout page
Return to Application: Should show “You have been successfully logged out”
Test Session Cleared: Accessing protected resources should require re-authentication

Troubleshooting

Logout Redirects to Login Without Provider Interaction:

Provider may not support end_session_endpoint
Check provider’s OpenID Connect discovery document
Verify provider configuration supports logout

“Invalid Redirect URI” Error:

Ensure exact URI match in provider configuration
Check domain and port match your server configuration
Verify HTTPS is used (required for OIDC)

Logout Fails Silently:

Check application logs for error messages
Verify id_token is present in JWT payload
Ensure provider accepts logout parameters

API Key Authentication

Creating API Keys

Via Web Interface

Navigate to /api-keys
Click “Generate New API Key”
Configure:
- Name: Descriptive name for the key
- Permissions: downloads, uploads, delete (based on your role)
- Expiration: 7 days to 1 year

Via API

# Create API key
curl -k -X POST -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "permissions": ["downloads", "uploads"],
    "expires_at": "2025-12-31T23:59:59.000Z"
  }' \
  https://your-server/api/api-keys

API Key Permissions

Choose appropriate permissions for your use case:

Downloads Only (Safe for CI/CD)

{
  "permissions": ["downloads"]
}

Upload Access (Admin Only)

{
  "permissions": ["downloads", "uploads"]
}

Full Access (Admin Only)

{
  "permissions": ["downloads", "uploads", "delete"]
}

Using API Keys

# File operations
curl -k -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-server/uploads/file.txt

# Directory listing
curl -k -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  https://your-server/uploads/

# Upload file
curl -k -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./local-file.txt" \
  https://your-server/uploads/

Swagger UI Authentication

Existing API Keys

If you have API keys, the Swagger UI will show them in the authorization modal:

Click “Authorize” in Swagger UI
See your existing API keys listed
Click “Fill Auth Field” to use an existing key

Temporary Keys

For testing in Swagger UI:

Click “Authorize” in Swagger UI
Click “Generate Temp Key”
Temporary key automatically fills the auth field
Key expires after configured time (default 1 hour)

JWT Token Management

Token Structure

{
  "aud": "file-server-users",
  "iss": "file-server", 
  "userId": 1,
  "email": "user@example.com",
  "permissions": ["downloads", "uploads", "delete"],
  "role": "admin",
  "exp": 1640995200,
  "iat": 1640908800
}

Token Validation

Armor validates:

Signature: Uses configured JWT secret
Expiration: Tokens expire after configured time
Issuer/Audience: Validates token source
Permissions: Checks required permissions for operations

Security Best Practices

Production Deployment

Strong JWT Secret:

# Generate secure secret
openssl rand -hex 32

Secure Passwords:

authentication:
  local:
    users:
      - username: admin
        password: "$(openssl rand -base64 32)"  # Strong random password

Limited API Key Permissions:
- Only grant necessary permissions
- Set reasonable expiration dates
- Rotate keys regularly

HTTPS Only:

ssl:
  generate_ssl: false
  key_file: "/etc/letsencrypt/live/domain.com/privkey.pem"
  cert_file: "/etc/letsencrypt/live/domain.com/fullchain.pem"

Network Security

Firewall: Restrict access to port 443
VPN: Consider VPN access for admin operations
Monitoring: Log and monitor authentication attempts
Rate Limiting: Configure appropriate limits

Troubleshooting

Authentication Issues

Login Failed

# Test basic auth
curl -k -u admin:admin123 https://your-server/

# Check user config
sudo cat /etc/armor/config.yaml | grep -A 10 users:

# Check logs
sudo journalctl -u armor -f

JWT Token Issues

Verify JWT secret is configured
Check token hasn’t expired
Ensure proper Authorization header format

API Key Problems

Verify key hasn’t expired
Check permissions match required operation
Test key: curl -k -H "Authorization: Bearer KEY" https://server/api/api-keys

OIDC Issues

Google Login Failed

Verify client ID and secret
Check redirect URI matches exactly
Ensure OAuth consent screen is configured and published
Verify OAuth 2.0 client credentials are correctly set up in Google Cloud Console
Test OIDC discovery: curl https://accounts.google.com/.well-known/openid_configuration

Permission Denied After OIDC Login

Check domain_mappings configuration
Verify user’s email domain
Check permission_strategy setting

Common Fixes

Reset User Password

# Edit config.yaml
authentication:
  local:
    users:
      - username: admin
        password: newpassword123  # Update password
        role: admin
        id: 1

Generate New JWT Secret

# Generate secure secret
openssl rand -hex 32

# Update config
sudo nano /etc/armor/config.yaml
sudo systemctl restart armor

Regenerate SSL Certificates

# Remove existing certificates
sudo rm -rf /etc/armor/ssl/*

# Restart service to regenerate
sudo systemctl restart armor

Configuration Reference - Complete authentication config options
API Reference - Authentication endpoints and examples
Installation Guide - Production deployment setup

Need help? Check our Support Documentation or open an issue.

Authentication

Table of contents

Authentication Overview

Local User Authentication

User Configuration

User Roles

Admin Role (role: admin)

User Role (role: user)

Web Login

Login Page URL Parameters

Auto-redirect guards

HTTP Basic Authentication

OIDC Authentication

Google Integration

Setting Up Google OAuth

OIDC User Permissions

OIDC Logout (RP-Initiated Logout)

How It Works

Configuration Requirements

Provider-Specific Notes

Testing Logout Flow

Troubleshooting

API Key Authentication

Creating API Keys

Via Web Interface

Via API

API Key Permissions

Downloads Only (Safe for CI/CD)

Upload Access (Admin Only)

Full Access (Admin Only)

Using API Keys

Swagger UI Authentication

Existing API Keys

Temporary Keys

JWT Token Management

Token Structure

Token Validation

Security Best Practices

Production Deployment

Network Security

Troubleshooting

Authentication Issues

OIDC Issues

Common Fixes

Related Documentation