Skip to main content

​
Overview

OpenID Connect (OIDC) is the recommended authentication protocol for modern identity providers. It provides standardized user profile information, built-in token validation, and automatic discovery of provider endpoints.

​
Supported providers

OIDC works with any compliant identity provider, including:
  • Google Workspace
  • Microsoft Entra ID (Azure AD)
  • Okta
  • Auth0
  • Keycloak
  • GitLab
  • GitHub (via OIDC)

​
Configuration via admin UI

1

Navigate to SSO providers

Go to Admin → SSO Providers in your dashboard
2

Add OIDC provider

Click “Add Provider” and select “OIDC” as the provider type
3

Enter basic information

Provider name: Google Workspace
Provider ID: google
Enabled: Yes
4

Configure OIDC settings

Issuer URL: https://accounts.google.com
Client ID: your-client-id.apps.googleusercontent.com
Client secret: your-client-secret
Scopes: openid profile email
5

Set up role mapping

Configure default roles and group mappings (optional)
6

Save and test

Save the configuration and test the login flow

​
Provider-specific guides

​
Google Workspace

1

Create OAuth2 credentials

  1. Go to Google Cloud Console
  2. Select your project or create a new one
  3. Navigate to APIs & Services → Credentials
  4. Click “Create Credentials” → “OAuth client ID”
  5. Select “Web application” as the application type
2

Configure redirect URIs

Add your callback URL:
https://your-domain.com/auth/callback/google
3

Copy credentials

Save the Client ID and Client secret
4

Configure in admin UI

Issuer URL: https://accounts.google.com
Client ID: [your-client-id].apps.googleusercontent.com
Client secret: [your-client-secret]
Scopes: openid profile email

​
Microsoft Entra ID (Azure AD)

1

Register application

  1. Go to Azure Portal
  2. Navigate to Microsoft Entra ID → App registrations
  3. Click “New registration”
  4. Enter a name and select supported account types
2

Configure redirect URI

Add a web redirect URI:
https://your-domain.com/auth/callback/azure
3

Create client secret

  1. Go to Certificates & secrets
  2. Click “New client secret”
  3. Save the secret value (shown only once)
4

Configure in admin UI

Issuer URL: https://login.microsoftonline.com/[tenant-id]/v2.0
Client ID: [application-id]
Client secret: [client-secret-value]
Scopes: openid profile email
Replace [tenant-id] with your Azure AD tenant ID or use common for multi-tenant applications.

​
Okta

1

Create OIDC application

  1. Log in to your Okta admin console
  2. Go to Applications → Applications
  3. Click “Create App Integration”
  4. Select “OIDC - OpenID Connect”
  5. Choose “Web Application”
2

Configure application

Sign-in redirect URIs: https://your-domain.com/auth/callback/okta
Sign-out redirect URIs: https://your-domain.com/logout
3

Save credentials

Copy the Client ID and Client secret
4

Configure in admin UI

Issuer URL: https://[your-domain].okta.com
Client ID: [client-id]
Client secret: [client-secret]
Scopes: openid profile email groups

​
Auth0

1

Create application

  1. Go to Auth0 Dashboard
  2. Navigate to Applications → Applications
  3. Click “Create Application”
  4. Select “Regular Web Applications”
2

Configure callbacks

In the application settings:
Allowed Callback URLs: https://your-domain.com/auth/callback/auth0
Allowed Logout URLs: https://your-domain.com/logout
3

Get credentials

Find your Domain, Client ID, and Client Secret in the application settings
4

Configure in admin UI

Issuer URL: https://[your-domain].auth0.com
Client ID: [client-id]
Client secret: [client-secret]
Scopes: openid profile email

​
Configuration fields

FieldDescriptionRequiredExample
Issuer URLOIDC discovery endpointYeshttps://accounts.google.com
Client IDOAuth2 client identifierYesabc123.apps.googleusercontent.com
Client secretOAuth2 client secretYesGOCSPX-...
ScopesSpace-separated OAuth2 scopesNoopenid profile email groups

​
Common scopes

ScopeDescription
openidRequired for OIDC authentication
profileAccess to user’s profile information (name, picture)
emailAccess to user’s email address
groupsAccess to user’s group memberships (provider-dependent)
offline_accessRequest refresh tokens for long-lived sessions

​
Redirect URI format

The redirect URI (callback URL) follows this pattern: 
https://[your-domain]/auth/callback/[provider-id]
Examples:
  • https://app.example.com/auth/callback/google
  • https://app.example.com/auth/callback/okta
  • https://app.example.com/auth/callback/azure
The redirect URI must exactly match what you configure in your identity provider. Include the protocol (https://) and ensure there are no trailing slashes.

​
User attribute mapping

OIDC providers return user information in the ID token and userinfo endpoint. Common claims include:
OIDC ClaimApplication FieldDescription
subUser IDUnique identifier for the user
emailEmailUser’s email address
nameFull nameUser’s display name
given_nameFirst nameUser’s first name
family_nameLast nameUser’s last name
pictureAvatar URLUser’s profile picture
groupsGroupsUser’s group memberships

​
Advanced configuration

​
Custom scopes

Request additional scopes for provider-specific claims: 
openid profile email groups roles department

​
Discovery endpoint

OIDC providers expose a discovery document at: 
[issuer-url]/.well-known/openid-configuration
This document contains all endpoint URLs and supported features. The application automatically fetches this during authentication.

​
Token validation

The application automatically validates:
  • Token signature using provider’s public keys
  • Token expiration (exp claim)
  • Token audience (aud claim matches client ID)
  • Token issuer (iss claim matches issuer URL)

​
Troubleshooting

​
Invalid redirect URI error

Problem: Identity provider rejects the redirect URI Solution:
  • Verify the redirect URI exactly matches in both systems
  • Check for trailing slashes or protocol mismatches
  • Ensure the provider ID in the URL matches your configuration

​
User info not populated

Problem: User profile fields are empty after login Solution:
  • Verify you’re requesting the correct scopes (profile, email)
  • Check that your identity provider includes claims in the ID token
  • Review the userinfo endpoint response in audit logs

​
Groups not syncing

Problem: User groups from identity provider aren’t mapped to roles Solution:
  • Add groups scope to your configuration
  • Verify your identity provider includes groups in the token
  • Check your group-to-role mapping configuration
  • Some providers require additional configuration to include groups

​
Token expired errors

Problem: Users are logged out frequently Solution:
  • Check token expiration times in your identity provider
  • Request offline_access scope for refresh tokens
  • Configure session timeout settings in your application

​
Security best practices

Always use HTTPS for your redirect URIs. Most providers reject HTTP callbacks in production.
Regularly rotate your client secrets and update them in the admin UI.
Only request the scopes you need. Avoid requesting excessive permissions.
Ensure the issuer URL matches your identity provider to prevent token substitution attacks.
Regularly review SSO audit logs for suspicious authentication attempts.

​
Next steps

Role mapping

Configure group-to-role mappings for automatic role assignment

User management

Manage users and their connected accounts

OAuth2 setup

Configure OAuth2 providers without OIDC support

Audit logging

Monitor SSO authentication events