OpenID Connect

Enable single sign-on (SSO) using OpenID Connect providers like Microsoft Entra ID, Google Workspace, or any OIDC-compliant identity provider.

Quick Setup

1. Configure your OpenID Connect provider (see Microsoft Entra ID example below)
2. Set environment variables: OPENID_CONNECT_CLIENT_ID, OPENID_CONNECT_CLIENT_SECRET, OPENID_CONNECT_ISSUER_URL
3. Restart your application

Environment Variables

Add these environment variables:

OPENID_CONNECT_CLIENT_ID="your-client-id"
OPENID_CONNECT_CLIENT_SECRET="your-client-secret"
OPENID_CONNECT_ISSUER_URL="https://login.microsoftonline.com/your-tenant-id/v2.0"
OPENID_CONNECT_ISSUER_NAME="Microsoft Entra ID"
OPENID_CONNECT_ROLES_ENABLED="true"

Microsoft Entra ID Setup

Follow these steps to configure Microsoft Entra ID as your OpenID Connect provider:

Step 1: App Registration

Go to App Registrations page in your Microsoft Entra ID portal.

Azure Portal: https://portal.azure.com → Microsoft Entra ID → App registrations

Step 2: Register Application

Register a new application with the correct Redirect URL:

Redirect URL:

https://your-app.example.com/users/auth/openid_connect/callback

Step 3: Create Client Secret

Go To Certificates & secrets and create a new client secret.

Important: Copy the secret value immediately as it won't be shown again.

Step 4: Gather Configuration Values

You'll need these values from your Microsoft Entra ID app registration:

Issuer URL Format

The issuer URL follows this pattern:

https://login.microsoftonline.com/<TENANT_ID>/v2.0

Replace <TENANT_ID> with your Directory (tenant) ID from Microsoft Entra ID.

Other OpenID Connect Providers

This application supports any OpenID Connect compliant provider. Common providers include:

For non-Microsoft providers, configure the environment variables as follows:

• OPENID_CONNECT_ISSUER_NAME — Set to provider name (e.g., "Google", "Auth0", "Okta")
• OPENID_CONNECT_ROLES_ENABLED — Set to "false" for most providers (role extraction currently only supports Microsoft Entra ID)

User Experience

When OpenID Connect is enabled, users will see:

• Login Page: "Sign in with OpenID Connect" button alongside standard email/password login
• Registration: Users can create accounts using their OIDC provider credentials
• Account Linking: Existing users can link their OIDC provider to their account
• Single Sign-On: Once authenticated with the provider, users stay logged in across sessions

Testing Your Setup

To verify your OpenID Connect configuration is working:

1. Restart your application after setting environment variables
2. Visit the login page — you should see "Sign in with OpenID Connect" button
3. Click the button and verify you're redirected to your OIDC provider
4. Complete authentication and verify you're redirected back to the application
5. Check that your user account is created/updated with OIDC provider information

Troubleshooting

Button Not Visible

• Restart your application after changing environment variables
• Check application logs for feature flag loading errors

Authentication Errors

• Verify redirect URL exactly matches what's configured in your OIDC provider
• Check that client ID and secret are correct
• Ensure issuer URL is accessible and returns valid OIDC discovery document
• Review application logs for detailed error messages

SSL/Certificate Issues

• Ensure your application is served over HTTPS in production
• Verify SSL certificates are valid for your domain
• Some providers require HTTPS for redirect URLs

Microsoft Entra ID App Roles (Microsoft Only)

For Microsoft Entra ID providers, you can configure app roles for role-based access control. App roles are more secure and manageable than groups, providing explicit authorization and avoiding the 200-group token limit.

Step 1: Create App Roles in Microsoft Entra ID

1. Go to your Microsoft Entra ID app registration → App roles
2. Click "Create app role"
3. Create roles with these specifications:

Step 2: Assign Users to Roles

1. Go to Microsoft Entra ID → Enterprise applications
2. Search for your app
3. Click on your app
4. Go to Users and groups
5. Click "+ Add user/group"
6. Select your user (e.g., "Jānis Bērziņš")
7. Click "Select a role"
8. Choose the appropriate role (e.g., "Admin")
9. Click "Assign"

Role Permissions

• Admin: App access + admin panel + most admin settings
• Super Admin: Full access to all features and settings

Note: App roles are only supported for Microsoft Entra ID providers. Users from other OAuth providers will have admin access by default.

Security Considerations

Best Practices

• Scope Limitation: Request only necessary scopes from the OIDC provider
• Regular Rotation: Rotate client secrets periodically
• Domain Validation: Verify user email domains if restricting access
• Role Assignment: Regularly review and audit user role assignments in Microsoft Entra ID