Add an OIDC Identity Provider

This guide explains how to register a generic OpenID Connect (OIDC) identity provider (IdP) in ThunderID. Use this type for any standard OIDC-compliant provider.

Prerequisites

• ThunderID is running. See Get Started.
• You can sign in to the ThunderID Console.
• A client application registered in the external OIDC provider with a Client ID, Client Secret, and redirect URI.

Finding endpoint URLs

Most OIDC providers publish their endpoint URLs in a discovery document at:

https://<provider-domain>/.well-known/openid-configuration

Open this URL in a browser to find the authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, and issuer values.

Create the OIDC Connection

1

Step 1: Add a Custom Connection

1. Sign in to the ThunderID Console.
2. Navigate to Connections.
3. Click the Add custom connection card.

2

Step 2: Choose the Connection Type

1. On the Connection type step, click OpenID Connect Provider.
2. Click Continue.

3

Step 3: Configure the Connection

Enter the following fields, then click Create connection:

Field	Required	Description
Connection name	Yes	A friendly name used to identify this connection.
Client ID	Yes	The client ID issued by the OIDC provider.
Client secret	Yes	The client secret issued by the OIDC provider.
Authorization endpoint	Yes	The provider's authorization endpoint, used to start the sign-in flow.
Token endpoint	Yes	The provider's token endpoint, used to exchange the authorization code for tokens.
UserInfo endpoint	No	The provider's userinfo endpoint. Used to fetch additional profile claims.
JWKS endpoint	No	The URL of the provider's JSON Web Key Set. Required when Enable token exchange is on.
Issuer	No	The provider's issuer identifier, expected in tokens from this provider. Required when Enable token exchange is on.
Scopes	No	Space-separated OIDC scopes to request. Defaults to openid email profile if left blank.

The Redirect URI field is read-only. Copy its value and register it as the callback URL with your OIDC provider.

Under Federation, turn on Enable token exchange to accept subject tokens from this provider for token exchange. This makes Issuer and JWKS endpoint required, and reveals an optional Trusted token audience field, the accepted audience value for external tokens during token exchange.

note

The connection also accepts logoutEndpoint and prompt fields. These are not available in the Console and can only be set through the Connections API.

Attribute Configuration

External providers emit attributes under their own names, which may differ from the attribute names ThunderID uses locally (for example, a provider may emit given_name where your user type defines firstName). Open the connection and go to the Attribute Configuration tab to map external attributes to local user attributes.

User Type Resolution

By default, every federated identity resolves to the connection's Default User Type. To derive the user type from an incoming claim instead, turn on Resolve user type from an attribute and set the attribute whose value decides the user type (for example, user_type; supports dot notation for nested claims, for example profile.role).

Under Value Mapping, map each external attribute value to a local user type (for example, staff to Employee, partner to Contractor) using Add Value. The Default User Type remains the fallback used when the claim is missing or its value has no mapping.

The resolved user type selects which mapping set applies under Attribute Mappings.

Attribute Mappings

Click Add User Type to add a mapping set for a user type, then click Add Mapping to add attribute mappings within that set. Each mapping has:

Field	Description
External Attribute	The external attribute name (for example, given_name).
Local Attribute	The target local attribute (for example, firstName). Must be an attribute defined in that user type's schema.

Behavior:

• The external attribute supports complex forms. Use dot notation to read a value nested inside another attribute. For example, email.work reads the work field from an email object.
• The local attribute must be defined in the user type's schema; this is validated when you save the connection.
• An attribute whose name is mapped is renamed to its local attribute; attributes without a mapping pass through unchanged.

The mapping applies both when a user signs in through this connection in an authentication flow and when a token from this provider is exchanged (see Trusted Issuer). The resulting local attributes flow into the issued access and ID tokens, subject to the application's userAttributes configuration.

Account Linking

To resolve an incoming federated identity to an existing local user by attributes when the subject identifier (sub) does not match, add attributes under Account Linking. Click Add Attribute to add an external attribute (for example, email) that is matched to find the associated local user.

Behavior:

• Resolution tries the subject identifier (sub) first. If it resolves an existing user, that user is used.
• Otherwise, all configured attributes that have a value are matched together (AND) to resolve a unique local user.
• Each attribute is an external claim name; if it's mapped under Attribute Mappings (for example, email to work_email), the mapped local attribute is used for the lookup instead.
• If neither sub nor the configured attributes resolve a user, the user is treated as new (subject to the flow's provisioning configuration).

Click Save changes to apply your attribute configuration.

Next Steps

• Connect an IdP to an Application: Add this OIDC IdP to an application's authentication flow.
• Manage Identity Providers: Update or delete identity providers.