Configuring Applications and OAuth Clients

Overview

Learn how to create, configure, and manage applications in the SSO Portal, including OAuth client setup and secret management.

Creating an Application

Step 1: Access Application Management

1. Log in as Administrator
2. Navigate to Admin > Applications
3. Click Add Application

Step 2: Basic Information

Fill in required fields:

Name

• Display name shown to users
• Example: "Company Intranet"

Description

• Brief description of the application
• Helps users understand the app's purpose

Redirect URI

• OAuth callback URL
• Where users return after authentication
• Example: https://myapp.com/auth/callback
• Important: Must match exactly (including trailing slash)

Logout URI (Optional)

• Where to redirect after logout
• Example: https://myapp.com/logout

Step 3: Review Generated Credentials

After creating the application, you'll receive:

Client ID

• Public identifier: app_1a2b3c4d5e
• Safe to share with developers
• Used in OAuth authorization requests

App Secret

• Secret key for token validation
• CRITICAL: Shown only once, store securely!
• Used to validate JWT tokens in your application

JWT Secret

• Used by SSO Portal to sign tokens
• Not typically needed by your application
• Shown for reference

Step 4: Save Credentials Securely

1. Click Export Integration Config to download JSON
2. Store in password manager or secure vault
3. Share securely with developers (not via email)

Managing Existing Applications

Viewing Applications

1. Admin > Applications
2. View all configured applications
3. See basic info without exposing secrets

Editing Applications

1. Click Edit on an application
2. Modify:
   • Name
   • Description
   • Redirect URI
   • Logout URI
3. Click Save Changes

Note: Client ID and secrets cannot be changed, only regenerated

Integration Modal

Click View on any application to see:

• Full configuration details
• OAuth endpoints
• Integration guide
• Export configuration option

Secret Management

Regenerating App Secret

When to regenerate:

• Secret compromised
• Regular rotation (recommended yearly)
• Changing development team
• Security audit requirement

How to regenerate:

1. Open application in edit mode
2. Click Regenerate Secret
3. Confirm the action
4. Immediately update your application with new secret
5. Old secret is invalidated instantly

Critical Steps:

• Update application code before regenerating
• Test in staging first
• Have rollback plan ready
• Communicate to development team
• Update documentation

Security Best Practices

• Never commit secrets to version control
• Store in environment variables
• Use secret management tools (Vault, AWS Secrets Manager)
• Rotate secrets regularly
• Limit access to secrets
• Audit secret usage
• Revoke unused secrets

OAuth Configuration

Authorization Endpoint

https://sso.platformaxion.com/oauth/authorize

Parameters:

• client_id: Your application's client ID
• response_type: code for authorization code flow
• redirect_uri: Registered callback URL
• scope: openid profile email
• state: CSRF protection token

Token Endpoint

https://sso.platformaxion.com/oauth/token

Grant Types Supported:

• authorization_code: Standard OAuth flow
• refresh_token: Refresh expired tokens

UserInfo Endpoint

https://sso.platformaxion.com/oauth/userinfo

Returns user profile data when authenticated.

Advanced Configuration

PKCE Support

PKCE (Proof Key for Code Exchange) is recommended for:

• Mobile applications
• Single-page applications
• Public clients

Implementation:

1. Generate code verifier (random string)
2. Create code challenge (SHA256 hash)
3. Include in authorization request
4. Provide verifier in token exchange

Refresh Tokens

Enable long-lived sessions:

1. Request offline_access scope
2. Receive refresh token with access token
3. Use refresh token to get new access tokens
4. Refresh tokens valid for 30 days

Custom Scopes

Define what data your app can access:

• openid: Required for OpenID Connect
• profile: User's name and profile info
• email: User's email address

Integration Testing

Test Checklist

• [ ] Authorization flow works
• [ ] Token exchange succeeds
• [ ] User info retrieval works
• [ ] Token validation correct
• [ ] Logout redirects properly
• [ ] Refresh token works
• [ ] Error handling in place

Testing Tools

Manual Testing:

1. Click "Launch" from dashboard
2. Verify redirect to your app
3. Check user logged in
4. Verify user data received

Automated Testing: Use tools like Postman:

1. Test authorization endpoint
2. Test token exchange
3. Test userinfo endpoint
4. Validate token signatures

Monitoring Applications

Application Analytics

1. Admin > Applications
2. View application
3. See usage statistics:
   • Total authentications
   • Active users
   • Failed attempts
   • Last used

Audit Logs

Track application-specific events:

1. Admin > Audit
2. Filter by application
3. Review:
   • Who accessed the app
   • When they accessed it
   • Authentication failures
   • Configuration changes

Deleting Applications

Warning: This permanently removes the application

1. Admin > Applications
2. Click Delete on application
3. Confirm deletion
4. All OAuth clients invalidated immediately
5. Users can no longer launch app

Before Deleting:

• Export configuration for records
• Notify application owners
• Remove from user dashboards
• Update documentation

Troubleshooting

"Invalid redirect_uri" Error

• Verify URI matches exactly
• Check for trailing slashes
• Ensure protocol (http/https) matches
• Check for typos

"Invalid client credentials" Error

• Verify Client ID is correct
• Check App Secret (regenerate if lost)
• Ensure no extra spaces
• Verify not using JWT Secret instead of App Secret

Token Validation Fails

• Use App Secret (not JWT Secret)
• Check algorithm is HS256
• Verify token hasn't expired
• Check clock sync

Users Don't See Application

• Verify application is active
• Check user has access permissions
• Ensure user's role permits access
• Review application assignment

Best Practices

Development

• Test in development environment first
• Use different apps for dev/staging/prod
• Implement proper error handling
• Log authentication failures
• Monitor token expiration

Security

• Always use HTTPS
• Validate redirect URIs strictly
• Implement CSRF protection
• Use state parameter
• Rotate secrets regularly
• Monitor for unusual activity

Production

• Export and backup configurations
• Document integration details
• Monitor application health
• Have rollback procedures
• Keep audit logs
• Regular security reviews