JWT Configuration

Configure JWT authentication settings in the Authonomy admin dashboard

JWT Configuration Guide

Configure JWT authentication settings through the Authonomy admin dashboard to enable programmatic user authentication for your applications.

Overview

The JWT Configuration interface allows administrators to:

  • Set up JWT token validation rules
  • Configure supported signing algorithms
  • Define required claims and permissions
  • Manage security policies
  • Test JWT token validation

Accessing JWT Configuration

  1. Log into Admin Dashboard

    • Navigate to your Authonomy admin dashboard
    • Ensure you have administrative privileges

  2. Access JWT Settings

    • Click Settings in the main navigation
    • Select Authentication from the settings menu
    • Choose JWT Configuration from the authentication options

  3. Tenant Context

    • Verify you’re in the correct tenant context
    • JWT configurations are tenant-specific

Creating JWT Configurations

Basic Information

Configuration Details

  • Name: Descriptive name for this JWT configuration

    • Example: “Main Application JWT”, “API Authentication”
    • Used for identification in logs and admin interface

  • Description: Optional detailed description

    • Document the purpose and intended use
    • Include any special requirements or notes

  • Enabled: Toggle to activate/deactivate this configuration

    • Disabled configurations reject all token validation attempts
    • Use for maintenance or emergency shutoffs

JWT Validation Settings

Issuer Configuration

  • Issuer (Required): The expected JWT issuer claim (iss)

    • Must exactly match the iss claim in your JWT tokens
    • Example: https://your-application.com
    • Case-sensitive and must include protocol

  • Audience (Optional): Expected audience claim (aud)

    • Validates the JWT aud claim if specified
    • Leave blank to skip audience validation
    • Example: authonomy or your-app-users

Algorithm Selection

Choose the signing algorithm for token validation:

  • JWKS URL: URL to your JSON Web Key Set
    • Example: https://your-app.com/.well-known/jwks.json
    • Must be publicly accessible
    • Should serve valid JWKS JSON format
    • Cached for performance (1-hour TTL)

JWKS Requirements:

  • Accessible via HTTPS
  • Returns valid JSON Web Key Set format
  • Contains public keys with kid (Key ID) headers
  • Keys must match those used to sign JWT tokens
HS256 (Simple for Development)
  • Secret Key: Shared secret for HMAC validation
    • Store securely and rotate regularly
    • Minimum 32 characters recommended
    • Never expose in client-side code or logs

Security Warning: HS256 requires the same secret key on all systems. Use RS256 for distributed applications.

Session Configuration

Session Type

Configure what type of session to create upon successful JWT validation:

  • Admin: Creates administrative sessions

    • Full access to admin dashboard
    • Administrative permissions
    • Use for internal tools and admin users

  • User: Creates standard user sessions

    • Regular application access
    • Standard user permissions
    • Most common choice for application users

  • Temporary: Creates limited-time sessions

    • Restricted permissions
    • Shorter session duration
    • Useful for temporary access or specific workflows

Security Policies

Token Age Limits
  • Max Token Age (Seconds): Maximum accepted token age
    • Default: 3600 seconds (1 hour)
    • Range: 60 - 86400 seconds (1 minute to 24 hours)
    • Measured from JWT iat (issued at) claim
    • Helps prevent old token reuse
One-Time Use Enforcement
  • Enforce One-Time Use: Prevent token replay attacks
    • Enabled: Each token can only be used once
    • Requires JWT jti (JWT ID) claim for uniqueness
    • Maintains used token database until expiration
    • Recommended for high-security environments

Implementation Note: One-time enforcement requires your JWT tokens to include a unique jti claim.

Claims Validation

Required Claims

Specify which JWT claims must be present for validation:

Default Required Claims:

  • email - User email address
  • tenant_id - Tenant identifier

Common Additional Claims:

  • sub - Subject (user ID)
  • name - User full name
  • roles - User roles array
  • permissions - Specific permissions array

Custom Claims:

  • Add any application-specific claims
  • Claims are validated for presence, not content
  • Empty string values are considered missing

Claim Format

Enter required claims as a comma-separated list:

email, tenant_id, sub, roles

Redirect Configuration

Allowed Return Domains

Configure domains permitted for post-authentication redirects:

  • Security Purpose: Prevents open redirect vulnerabilities
  • Format: Domain names without protocol
  • Examples:
    • your-app.com
    • app.your-domain.com
    • localhost:3000 (for development)

Wildcard Support: Use *.your-domain.com for subdomain matching

Default Return URL

  • Fallback URL: Where to redirect if no redirect URL specified
  • Format: Full URL with protocol
  • Example: https://your-app.com/dashboard
  • Validation: Must use HTTPS in production

Priority Order:

  1. JWT redirect_url claim (if domain allowed)
  2. Query parameter return_to (if domain allowed)
  3. Default Return URL
  4. Tenant default dashboard

Managing Configurations

Configuration List

The JWT Configuration list shows:

  • Configuration name and status
  • Associated issuer
  • Algorithm type
  • Last modified date
  • Enable/disable toggle

Actions Available

Edit Configuration

  • Click the Edit button next to any configuration
  • Modify any settings except the configuration ID
  • Changes take effect immediately
  • No service restart required

Delete Configuration

  • Click the Delete button to remove a configuration
  • Warning: This immediately stops accepting tokens from that issuer
  • Confirm deletion in the popup dialog
  • Action cannot be undone

Test Configuration

  • Use the Test button to validate sample tokens
  • Enter a JWT token to test against the configuration
  • Shows validation results and extracted claims
  • Useful for troubleshooting integration issues

Configuration Status

Active Configurations

  • Green indicator shows enabled configurations
  • Actively validating JWT tokens
  • Cached for performance

Disabled Configurations

  • Gray indicator shows disabled configurations
  • All tokens rejected immediately
  • Configuration preserved for re-enabling

Testing JWT Setup

Built-in Token Tester

  1. Access Token Tester

    • Click Test next to any configuration
    • Or use the Test Token button in the configuration editor

  2. Enter JWT Token

    • Paste a complete JWT token
    • Must be signed with the correct key/secret
    • Should include all required claims

  3. View Results

    • Valid: Shows extracted claims and validation success
    • Invalid: Shows specific validation errors
    • Claims Display: All JWT claims in readable format

Test Token Creation

For testing purposes, create a minimal valid token:

{
  "iss": "https://your-app.com",
  "sub": "test-user-123", 
  "aud": "authonomy",
  "email": "test@example.com",
  "tenant_id": "your-tenant-id",
  "exp": 1640995200,
  "iat": 1640991600
}

Common Configuration Patterns

Development Setup

Name: Development JWT
Algorithm: HS256
Secret Key: development-secret-key-32chars
Session Type: user
Max Token Age: 86400 (24 hours)
Enforce One-Time: false
Required Claims: email, tenant_id

Production Setup

Name: Production API JWT  
Algorithm: RS256
JWKS URL: https://your-app.com/.well-known/jwks.json
Session Type: user
Max Token Age: 3600 (1 hour)
Enforce One-Time: true
Required Claims: email, tenant_id, sub, jti
Allowed Domains: your-app.com, api.your-app.com

Admin Authentication

Name: Admin Portal JWT
Algorithm: RS256
JWKS URL: https://admin.your-app.com/.well-known/jwks.json  
Session Type: admin
Max Token Age: 1800 (30 minutes)
Enforce One-Time: true
Required Claims: email, tenant_id, roles

Troubleshooting

Common Configuration Issues

JWKS URL Not Accessible

Symptoms: “Failed to fetch JWKS” errors Solutions:

  • Verify URL is publicly accessible
  • Check HTTPS certificate validity
  • Confirm JWKS format is correct
  • Test URL in browser or curl

Issuer Mismatch

Symptoms: “Configuration not found for issuer” errors Solutions:

  • Verify JWT iss claim matches configuration exactly
  • Check for trailing slashes or case differences
  • Confirm protocol (http vs https) matches

Missing Required Claims

Symptoms: “Required claims validation failed” errors Solutions:

  • Review JWT payload includes all required claims
  • Check claim names are spelled correctly
  • Ensure claims have non-empty values
  • Verify claim data types match expectations

Clock Skew Issues

Symptoms: “Token expired” or “Token not valid yet” errors Solutions:

  • Synchronize server clocks (use NTP)
  • Allow for reasonable clock skew in token timing
  • Check iat, exp, and nbf claim values
  • Consider time zone differences

Debug Information

Enable debug logging to troubleshoot:

  • Configuration validation shows detailed error messages
  • Token test results include full validation steps
  • Server logs contain JWT processing details
  • Use test functionality to validate before deployment

Support Resources

For additional assistance:

  • Check the JWT Authentication Guide for implementation details
  • Review API Documentation for programmatic configuration
  • Contact Authonomy support with configuration exports
  • Use Health Check to verify overall system status

Security Considerations

Secret Management

  • Store HS256 secrets securely
  • Rotate secrets regularly
  • Never commit secrets to version control
  • Use environment variables or secret management systems

Key Management

  • Generate strong RSA key pairs (2048-bit minimum)
  • Protect private keys with appropriate file permissions
  • Implement key rotation procedures
  • Monitor key expiration dates

Configuration Security

  • Restrict admin dashboard access
  • Audit configuration changes
  • Use principle of least privilege
  • Enable multi-factor authentication for administrators

Monitoring and Alerting

  • Monitor JWT validation failure rates
  • Alert on configuration changes
  • Track unusual authentication patterns
  • Log all administrative actions

JWT configuration provides secure, flexible authentication for your applications. Proper setup ensures reliable token validation while maintaining security best practices.