IDENTITY PROVIDERS

Identity Providers

Identity Providers allow users to sign in to your platform using external authentication services like Google, Microsoft, Auth0, Okta, PingOne, or any OpenID Connect (OIDC) compliant provider. This enables Single Sign-On (SSO) and simplifies user management by delegating authentication to trusted third-party services.

To manage identity providers, navigate to Identity Providers in the admin console.

Creating an Identity Provider

Click Add Identity Provider to configure a new provider. The configuration is organized into several sections:

Basic Information

• Identifier: A unique lowercase identifier for this provider (e.g., google, azure-ad, okta-prod). This identifier is used internally and in URLs.

• Name: The display name shown to users on the login page (e.g., "Google", "Company SSO").

• Description: Optional notes for administrators about this provider's purpose or configuration.

• Type: The authentication protocol. Currently, only OIDC (OpenID Connect) is supported.

• Enabled: Toggle to enable or disable the provider. Disabled providers won't appear on the login page.

OIDC Configuration

This section contains the core settings for connecting to your identity provider.

Domain

The domain of your identity provider. This is used to discover the OIDC endpoints automatically via the .well-known/openid-configuration endpoint.

Examples:

• Google: accounts.google.com

• Microsoft/Azure AD: login.microsoftonline.com/{tenant-id}/v2.0

• Auth0: your-tenant.us.auth0.com

• Okta: your-org.okta.com

• PingOne: auth.pingone.com/{environment-id}/as

Use the Test Connection button to verify the domain is correct. A successful test displays:

• Issuer URL

• Authorization endpoint

• Token endpoint

• JWKS URI with key count

• Supported signing algorithms

Client ID

The OAuth2 client identifier provided by your identity provider when you register your application.

Client Secret

The OAuth2 client secret provided by your identity provider. This value is stored securely and masked in the interface.

Authentication Method

How credentials are sent to the token endpoint:

• client_secret_post (default): Client ID and secret sent in the request body

• client_secret_basic: Client ID and secret sent via HTTP Basic Authentication header

• none: No client authentication (for public clients using PKCE only)

Choose the method supported by your identity provider. Most providers support client_secret_post.

Scopes

The OAuth2 scopes to request during authentication. Enter scopes separated by commas or spaces.

Common scopes:

• openid (required for OIDC)

• profile - User's name and profile information

• email - User's email address

• groups - Group memberships (if supported)

• offline_access - Request refresh tokens

Default recommendation: openid profile email

Callback URL

The OAuth2 redirect URI that must be configured in your identity provider. This field is read-only and automatically generated based on your platform URL:

https://your-platform.com/oauth/callback

Copy this URL and add it to the "Allowed Redirect URIs" (or similar) setting in your identity provider's application configuration.

User Provisioning

Controls how users are created and managed when they sign in through this provider.

Provisioning Mode

• Auto Provision (default): Automatically create new user accounts when users sign in for the first time. User profile information is populated from the identity provider's claims.

• Match Only: Only allow sign-in for users that already exist in the platform. New users will be rejected.

Allowed Domains

Restrict sign-in to users with email addresses from specific domains. Leave empty to allow all domains.

Examples:

• company.com - Only allow users with @company.com emails

• company.com, subsidiary.com - Allow multiple domains

This is useful for enterprise deployments where you want to ensure only employees can access the platform.

Email Trust Mode

Determines how email verification is handled for users signing in through this provider:

• Verify with Claim (default): Trust the email only if the identity provider sends an email_verified: true claim. Otherwise, send a verification email.

• Trust IdP: Always trust emails from this provider without verification. Use this for enterprise providers where you control the user directory.

• Always Verify: Always send a verification email, regardless of the provider's claims. Use this for maximum security.

Display Options

Customize how the provider appears on the login page.

Logo

Upload a logo image for the provider. This appears on the login button.

• Recommended size: 64x64 pixels (for high-DPI displays)

• Supported formats: PNG, JPG, SVG

Button Text

Custom text for the login button. If not specified, defaults to "Login with {Provider Name}".

Examples:

• "Sign in with Google"

• "Company SSO"

• "Employee Login"

Attribute Mapping

Map claims from the identity provider's ID token to user profile fields. Most OIDC providers use standard claim names, but some may use custom attributes.

Platform Field	Default Claim	Description
Username	preferred_username	User's unique identifier
Email	email	User's email address
Name	name	User's full display name
Picture	picture	Profile photo URL
Website	website	User's website
Company	organization	Company or organization name
Location	locale	User's locale or location

Only modify these mappings if your identity provider uses non-standard claim names.

---

Provider-Specific Setup Guides

Google

1. Go to the Google Cloud Console

2. Create a new project or select an existing one

3. Navigate to APIs & Services → Credentials

4. Click Create Credentials → OAuth client ID

5. Select Web application

6. Add your callback URL to Authorized redirect URIs

7. Copy the Client ID and Client Secret

Configuration:

• Domain: accounts.google.com

• Scopes: openid profile email

Microsoft / Azure AD

1. Go to the Azure Portal

2. Navigate to Azure Active Directory → App registrations

3. Click New registration

4. Enter a name and select the appropriate account types

5. Add your callback URL as a Redirect URI (Web platform)

6. After creation, copy the Application (client) ID

7. Go to Certificates & secrets → New client secret

8. Copy the secret value

Configuration:

• Domain: login.microsoftonline.com/{tenant-id}/v2.0

  • Use common for multi-tenant apps

  • Use your specific tenant ID for single-tenant apps

• Scopes: openid profile email

Auth0

1. Go to your Auth0 Dashboard

2. Navigate to Applications → Create Application

3. Select Regular Web Application

4. Go to the Settings tab

5. Add your callback URL to Allowed Callback URLs

6. Copy the Domain, Client ID, and Client Secret

Configuration:

• Domain: your-tenant.us.auth0.com (or your custom domain)

• Scopes: openid profile email

Okta

1. Go to your Okta Admin Console

2. Navigate to Applications → Create App Integration

3. Select OIDC - OpenID Connect and Web Application

4. Add your callback URL to Sign-in redirect URIs

5. Copy the Client ID and Client Secret

Configuration:

• Domain: your-org.okta.com

• Scopes: openid profile email

PingOne

1. Go to your PingOne Admin Console

2. Navigate to Connections → Applications

3. Create a new OIDC Web App

4. Add your callback URL to the redirect URIs

5. Copy the Client ID and Client Secret

6. Note your Environment ID

Configuration:

• Domain: auth.pingone.com/{environment-id}/as

• Scopes: openid profile email

Custom OIDC Provider

Any OIDC-compliant identity provider can be configured:

1. Register an application/client in your provider

2. Configure the callback URL as an allowed redirect URI

3. Obtain the Client ID and Client Secret

4. Find the OIDC discovery URL (usually https://provider/.well-known/openid-configuration)

5. Extract the domain from the issuer URL

Use the Test Connection button to verify your configuration is correct before saving.

---

Enabling Federated Login

After configuring identity providers, you must enable federated login for users to see the providers on the login page.

1. Navigate to Settings → Accounts

2. In the Authentication section, enable Federated Login

3. Select which identity providers should be available

4. Save your settings

The login page will now display the configured providers in the "Or continue with" section.

Note: Federated login can also be enabled at the brand level, allowing different brands to have different identity provider configurations.

---

User Experience

Signing In

When federated login is enabled, users see additional sign-in options on the login page:

1. Click the provider button (e.g., "Sign in with Google")

2. Redirect to the identity provider's login page

3. Authenticate with the provider (may include the provider's own MFA)

4. Redirect back to the platform

5. User is signed in (or account is created if auto-provisioning is enabled)

Linking Accounts

Existing users can link their account to an identity provider:

1. Sign in with username/password

2. Go to Account → Security

3. In the Connected Accounts section, click to link a provider

4. Authenticate with the provider

5. The account is now linked

Managing Connected Accounts

Users can view and manage their connected accounts in the Security settings:

• View all linked identity providers

• See the email associated with each provider

• See when each account was linked

• Unlink providers (with restrictions - see below)

Unlinking Restrictions

To maintain account access, users cannot unlink an identity provider if:

• It's their only authentication method, AND

• They don't have a password set

Users must either set a password or link another provider before unlinking.

---

Troubleshooting

Connection Test Fails

• Verify the domain is correct and accessible

• Check that the OIDC discovery endpoint is publicly accessible

• Ensure there are no firewall rules blocking the connection

Invalid Client Error

• Verify the Client ID and Client Secret are correct

• Check that the callback URL matches exactly what's configured in the provider

• Ensure the application is not disabled in the provider's console

User Not Created

• Check the provisioning mode - if set to "Match Only", users must exist beforehand

• Verify allowed domains if domain restrictions are configured

• Check the email trust mode settings

Claims Not Mapping

• Use the provider's token debugger to inspect the actual claims

• Update attribute mapping to match the provider's claim names

• Ensure requested scopes include the claims you need

Redirect Loop

• Verify the callback URL is correctly configured in both the platform and provider

• Check for cookie/session issues in the browser

• Ensure HTTPS is properly configured