authentikate/docs/guide/applications.md

Managing Applications

Learn how to create and manage OAuth applications in AuthentiKate.

Creating Applications

Via Web Interface

1. Navigate to Applications in the admin panel
2. Click "Create Application"
3. Fill in the application details:
   • Name: Display name for your application
   • Redirect URI: OAuth callback URL
   • Icon: Optional icon URL for the application
4. Save the application

Application Details

Each application gets:

• Unique Client ID: Public identifier for your application
• Client Secret: Private key for token exchange
• Redirect URI: Where users return after authentication

::: warning Keep your Client Secret secure! It should never be exposed in client-side code. :::

Application Templates

AuthentiKate includes templates for popular applications:

Available Templates

• Grafana: Analytics and monitoring
• Nextcloud: File sharing and collaboration
• Proxmox: Virtualization management
• Portainer: Docker container management
• GitLab: Git repository hosting

Templates automatically configure:

• Correct redirect URI patterns
• Appropriate application icons
• Common configuration settings

OAuth Configuration

Client Credentials

Client ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
Client Secret: 40-character-random-string

Endpoints

Your applications will use these endpoints:

• Authorization: /oauth/authorize
• Token: /oauth/token
• User Info: /oauth/userinfo
• JWKS: /.well-known/jwks.json

Supported Features

• Authorization Code Flow: Standard OAuth2 flow
• PKCE: Enhanced security for public clients
• JWT Tokens: Signed with RSA256
• Refresh Tokens: Long-lived token renewal

Security Best Practices

Redirect URI Validation

• Use exact URI matching
• Always use HTTPS in production
• Avoid wildcard redirects

Client Secret Management

• Store secrets securely
• Rotate secrets regularly
• Use different secrets per environment

Token Handling

• Validate token signatures
• Respect token expiration
• Implement proper logout

Common Integration Patterns

Server-Side Applications

Best for applications that can securely store client secrets:

// Example: Node.js application
const config = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  authorizationURL: 'https://auth.yourdomain.com/oauth/authorize',
  tokenURL: 'https://auth.yourdomain.com/oauth/token',
  callbackURL: 'https://yourapp.com/auth/callback'
};

Single Page Applications (SPA)

For client-side applications using PKCE:

// Example: React application with PKCE
const config = {
  clientId: 'your-client-id',
  // No client secret for public clients
  authorizationURL: 'https://auth.yourdomain.com/oauth/authorize',
  tokenURL: 'https://auth.yourdomain.com/oauth/token',
  redirectUri: 'https://yourapp.com/callback',
  usePKCE: true
};

Mobile Applications

Similar to SPAs, always use PKCE:

// Example: iOS Swift
let config = OIDServiceConfiguration(
    authorizationEndpoint: URL(string: "https://auth.yourdomain.com/oauth/authorize")!,
    tokenEndpoint: URL(string: "https://auth.yourdomain.com/oauth/token")!
)

Testing Applications

Manual Testing

1. Start OAuth flow from your application
2. Verify redirect to AuthentiKate
3. Complete authentication
4. Confirm successful return to your app
5. Check user data is populated correctly

Automated Testing

# Test authorization endpoint
curl "https://auth.yourdomain.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=openid"

# Test token exchange (after getting auth code)
curl -X POST https://auth.yourdomain.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI"

Troubleshooting

Invalid Redirect URI

Error: The redirect URI is invalid

Solutions:

• Verify exact URL match in application settings
• Check for trailing slashes
• Ensure HTTPS is used

Invalid Client

Error: Client authentication failed

Solutions:

• Verify Client ID and Secret
• Check that application exists and is active
• Ensure secrets haven't been regenerated

Token Validation Issues

Error: Invalid token signature

Solutions:

• Use JWKS endpoint for signature validation
• Verify token hasn't expired
• Check token issuer matches AuthentiKate URL

Application Management

Updating Applications

• Edit application details anytime
• Regenerate client secrets if compromised
• Update redirect URIs for new environments

Deactivating Applications

• Disable applications to prevent new logins
• Existing tokens remain valid until expiration
• Re-enable anytime to restore access

Monitoring Usage

View application usage in the admin panel:

• Active tokens per application
• Recent authentications
• User access patterns

Your applications are now ready for OAuth integration with AuthentiKate!