Overview
The admin UI provides a comprehensive interface for managing SSO authentication providers. You can add, edit, disable, and remove providers without requiring server restarts or configuration file changes.Prerequisites
AUTH_PROVIDERS_SOURCE=databaseenvironment variable configured- Admin access to the application
- Identity provider credentials (client ID, client secret, etc.)
Accessing the admin UI
Navigate to the SSO providers management page in your admin dashboard:Managing providers
Adding a new provider
1
Click Add Provider
Select the “Add Provider” button in the admin UI
2
Choose provider type
Select the authentication protocol:
- OIDC (OpenID Connect)
- OAuth2
- SAML 2.0
3
Configure basic settings
Enter the provider details:
- Provider name: Display name for the login button
- Provider ID: Unique identifier (lowercase, no spaces)
- Enabled: Toggle to enable/disable the provider
4
Enter credentials
Add your identity provider credentials:
- Client ID
- Client secret (for OIDC/OAuth2)
- Certificate (for SAML)
5
Configure endpoints
Specify the authentication endpoints:
- Authorization URL
- Token URL
- User info URL (OIDC/OAuth2)
- SSO URL (SAML)
6
Set up role mapping
Configure just-in-time provisioning:
- Default roles for new users
- Group-to-role mappings
- Attribute mappings
7
Save and test
Save the provider configuration and test the login flow
Editing an existing provider
1
Select the provider
Click on the provider you want to edit from the list
2
Update settings
Modify any configuration fields as needed
3
Save changes
Click “Save” to apply the updates immediately
Changes to provider configuration take effect immediately without requiring a server restart.
Disabling a provider
You can temporarily disable a provider without deleting its configuration:- Navigate to the provider settings
- Toggle the “Enabled” switch to off
- Save the changes
Deleting a provider
To delete a provider:- Select the provider from the list
- Click the “Delete” button
- Confirm the deletion
Provider configuration fields
Common fields (all providers)
| Field | Description | Required |
|---|---|---|
| Provider name | Display name shown on login button | Yes |
| Provider ID | Unique identifier (alphanumeric, lowercase) | Yes |
| Enabled | Whether the provider is active | Yes |
| Icon URL | Custom icon for the login button | No |
| Button color | Custom color for the login button | No |
OIDC-specific fields
| Field | Description | Required |
|---|---|---|
| Issuer URL | OIDC issuer/discovery endpoint | Yes |
| Client ID | OAuth2 client identifier | Yes |
| Client secret | OAuth2 client secret | Yes |
| Scopes | Space-separated list of scopes | No (default: openid profile email) |
OAuth2-specific fields
| Field | Description | Required |
|---|---|---|
| Authorization URL | OAuth2 authorization endpoint | Yes |
| Token URL | OAuth2 token endpoint | Yes |
| User info URL | Endpoint to fetch user profile | Yes |
| Client ID | OAuth2 client identifier | Yes |
| Client secret | OAuth2 client secret | Yes |
| Scopes | Space-separated list of scopes | No |
SAML-specific fields
| Field | Description | Required |
|---|---|---|
| SSO URL | SAML single sign-on endpoint | Yes |
| Entity ID | SAML entity identifier | Yes |
| Certificate | X.509 certificate for signature validation | Yes |
| Sign requests | Whether to sign SAML requests | No |
| Private key | Private key for signing requests | Conditional |
Testing provider configuration
After configuring a provider, test the integration:1
Open test login
Click the “Test Login” button in the provider settings
2
Authenticate
Complete the authentication flow with your identity provider
3
Verify user data
Check that user attributes are correctly mapped
4
Confirm role assignment
Verify that roles are assigned based on your mapping configuration
Best practices
Use descriptive provider names
Use descriptive provider names
Choose clear names like “Google Workspace” or “Okta Corporate” instead of generic names like “OIDC Provider 1”
Test before enabling
Test before enabling
Always test a provider configuration before enabling it for all users
Keep credentials secure
Keep credentials secure
Store client secrets and private keys securely. The admin UI encrypts sensitive fields in the database.
Monitor audit logs
Monitor audit logs
Regularly review SSO audit logs to detect authentication issues or security concerns
Document custom mappings
Document custom mappings
Keep documentation of your group-to-role mappings for future reference
Troubleshooting
Provider not appearing on login page
- Verify the provider is enabled
- Check that
AUTH_PROVIDERS_SOURCE=databaseis set - Restart the application if you recently changed the environment variable
Authentication fails
- Verify all endpoints are correct and accessible
- Check that client ID and secret match your identity provider
- Review audit logs for specific error messages
- Ensure redirect URIs are configured in your identity provider
Users not getting correct roles
- Review your role mapping configuration
- Check the group claims sent by your identity provider
- Verify attribute mappings are correct
- Test with a known user account