Skip to content
Portal

OpenID Connect (OIDC) Provider Setup Guide

Overview

OpenID Connect (OIDC) providers allow your users to authenticate using external identity services instead of traditional username/password login. This provides enhanced security, centralized user management, and improved user experience through single sign-on (SSO).

Benefits of OIDC Authentication

  • Enhanced Security: Centralized authentication with support for multi-factor authentication (MFA)
  • Reduced Password Management: Users don't need to remember additional passwords
  • Centralized User Management: Manage users in your existing identity provider
  • Single Sign-On (SSO): Users can access multiple services with one login
  • Compliance: Meet enterprise security and compliance requirements

Supported Providers

The platform supports any OIDC-compliant identity provider, including:

  • Google Workspace
  • Microsoft Azure AD / Entra ID
  • Okta
  • Auth0
  • Keycloak
  • Custom OAuth2/OIDC providers

Configuration Steps

Platform operators only

Configuring an OIDC provider is an operator task, at Cloud Admin → Settings → OIDC Providers — not a customer-admin action. The operator documentation has the full field reference: adding a provider, the generated redirect URL, and Group Mapping. The rest of this page covers what happens once a provider exists — restricting access by claim, and what an end user sees when logging in.

Google OIDC Configuration Example

Step 1: Create Google OAuth2 Application

  1. Go to Google Cloud Console
  2. Navigate to APIs & Services > Credentials
  3. Click Create Credentials > OAuth 2.0 Client IDs
  4. Select Web application as the application type
  5. Give your application a name (e.g., "Company Portal SSO")
  6. Click Create

Step 2: Configure Provider in Portal

Use these settings in your OIDC provider configuration:

  • Name: Google
  • Issuer URL: https://accounts.google.com
  • Client ID: Your Google Client ID (e.g., 123456789-abc.apps.googleusercontent.com)
  • Client Secret: Your Google Client Secret from the credentials page

Step 3: Configure Google OAuth2 Settings

In your Google OAuth2 application:

  • Authorized redirect URIs: Add the redirect URL from your OIDC provider configuration

Step 4: Test the Configuration

  1. Activate the provider in the OIDC Providers list
  2. Open an incognito/private browser window
  3. Navigate to your portal login page
  4. You should see a "Sign in with Google" option

Microsoft Azure AD Configuration Example

Step 1: Register Application in Azure AD

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory > App registrations
  3. Click New registration
  4. Configure:
  5. Name: Your application name
  6. Supported account types: Choose appropriate option

Step 2: Configure Application Settings

  1. Note the Application (client) ID
  2. Go to Certificates & secrets and create a new client secret
  3. Note the client secret value (it will only be shown once)

Step 3: Configure Provider in Portal

Use these settings:

  • Name: Microsoft
  • Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0 (replace {tenant-id} with your tenant ID, found in the Azure Active Directory Overview page)
  • Client ID: Your Azure Application (client) ID
  • Client Secret: Your Azure client secret

Step 4: Configure Redirect URI

In your Azure AD application:

  • Redirect URI: Add the redirect URL from your OIDC provider configuration

Keycloak Configuration Example

Step 1: Create Client in Keycloak

  1. Log in to your Keycloak Admin Console
  2. Navigate to Clients in your realm
  3. Click Create Client
  4. Configure:
  5. Client type: OpenID Connect
  6. Client ID: A unique identifier (e.g., "portal-client")
  7. Name: Display name for the client
  8. Click Next

Step 2: Configure Client Settings

  1. Set Client authentication to On
  2. Click Next
  3. Save the configuration

Step 3: Get Client Credentials

  1. Go to the Credentials tab
  2. Note the Client ID (this is the same as the Client ID you set in Step 1)
  3. Copy the Client secret

Step 4: Configure Provider in Portal

Use these settings:

  • Name: Keycloak
  • Issuer URL: https://your-keycloak-domain/realms/{realm-name} (replace with your Keycloak domain and realm name)
  • Client ID: Your Keycloak Client ID
  • Client Secret: Your Keycloak client secret

Step 4: Configure Redirect URI

  1. Configure Valid redirect URIs: Add the redirect URL from your OIDC provider configuration
  2. Save the configuration

Access Control with Claims

You can restrict access based on user claims from the OIDC provider:

Example: Organization-based Access Control

  • Claim Key: organization
  • Claim Value: your-company-name

This ensures only users with the specified organization claim can access the portal.

Example: Group-based Access Control

  • Claim Key: groups
  • Claim Value: portal-users

This restricts access to users who are members of the specified group.

Group to Organization Linking (Automatic Membership)

In addition to access control, an operator can configure a provider to automatically add users to an organization based on their external group membership during OIDC login/registration — see the operator documentation on Group Mapping for how this is configured. A provider can carry more than one mapping.

Notes:

  • The group claim is extracted from the OIDC UserInfo endpoint and supports both array and comma-separated string formats.
  • If a configured group name is present, the user is added as a member of the mapped role (a role organization, not a plain organization) on first login.
  • If the claim or group is missing, login still succeeds; no organization membership is added.

Troubleshooting:

  • Ensure your provider releases group claims to the UserInfo endpoint (for AD FS, see the AD FS guide below for scopes and claim rules).
  • Verify the exact group name spelling and capitalization.
  • Check scopes include at least openid profile email and any provider-specific scope needed to release group claims.

AD FS-specific guide

For a step-by-step Active Directory Federation Services setup, see: Integrate AD FS as an OIDC provider

Entra ID-specific guide

For a step-by-step Microsoft Entra ID setup, see: Integrate Entra ID as an OIDC provider

Troubleshooting

Common Issues

"Invalid redirect URI" error:

  • Ensure the redirect URL is exactly configured in your OIDC provider
  • Check for trailing slashes and protocol mismatches

"Invalid client" error:

  • Verify the client ID and client secret are correct
  • Ensure the OIDC provider application is properly configured

"Access denied" error:

  • Check claim-based access control settings
  • Verify the user has the required claims/permissions

Users can't see the OIDC login option:

  • Ensure the provider is activated in the OIDC Providers list
  • Check that the provider configuration is complete and valid

Password Login Management

You can control whether traditional username/password login is available alongside OIDC authentication:

  • Password Login Enabled: Users can choose between OIDC and password login
  • Password Login Disabled: Only OIDC authentication is available (requires at least one active OIDC provider)

Important

Disabling password login requires at least one active OIDC provider to prevent users from being locked out.