Custom OIDC provider

When the identity provider you want to federate with is not in the "built-in" list, use the custom OIDC connection. If the provider speaks OpenID Connect (most enterprise IDPs do — Okta, Keycloak, Auth0, OneLogin, Ping, ForgeRock, ADFS in OIDC mode, Authentik, Zitadel), this works.

This is also the right path for partner-IDP scenarios: your B2B customer has their own IDP, they want their employees to sign into your product using it, and they will share their OIDC discovery URL with you.

What you need from the provider

Four things:

Issuer URL — the base URL of the IDP. Usually something like https://login.example.com or https://example.okta.com/oauth2/default.
Client ID — the IDP's identifier for your application.
Client secret — paired with the client id. The IDP issues this when you register your app on their side.
Scopes — at minimum openid. Usually openid profile email too.

If the IDP exposes a discovery document (almost all do), you do not need to know the individual endpoint URLs — IntelliAuth fetches <issuer>/.well-known/openid-configuration and pulls them out.

On the IDP side

You (or your customer) register an OIDC application on the IDP. Most IDPs ask for:

Application name — what users see at consent.
Application type — "Web application" or "Server-side application".
Redirect URI — set this to:

https://<your-tenant-url>/auth/callback/oidc/<connection-slug>

Where <connection-slug> is the slug you choose for the connection in IntelliAuth (e.g., cymmetri-okta). The full URL becomes the registered redirect.

Some IDPs let you add multiple redirect URIs — useful if you have separate dev and prod IntelliAuth tenants.

On the IntelliAuth side

Tenant admin console → Authentication → Social providers → Custom OIDC.

Fill in:

Slug — your identifier for this connection. URL-safe; will appear in the callback URL. E.g., cymmetri-okta.
Display name — what the sign-in button shows ("Sign in with Cymmetri SSO").
Issuer URL.
Client ID + Client secret.
Scopes — openid profile email is the common starter.
Discovery — toggled on by default. IntelliAuth fetches the discovery document.

Save and test with the "Try sign-in" button. The popup should round-trip through the IDP and return successfully.

What ends up in the user record

The fields IntelliAuth captures depend on what the IDP returns in its id token and userinfo. By default:

sub from the id token → unique identifier.
email, email_verified from the id token or userinfo.
name, given_name, family_name, picture if present.

For non-standard claims, configure attribute mapping in the connection's "Advanced" settings. For example, if the IDP puts the user's department in a department claim, you can map that to a user attribute on the IntelliAuth side.

<button onClick={() => loginWithRedirect({ connection: 'cymmetri-okta' })}>
  Sign in with Cymmetri SSO
</button>

connection matches the slug you chose.

Common configurations

Okta (as an OIDC provider, not SAML)

Okta has both an OIDC and a SAML face. For OIDC:

Issuer URL → https://<your-okta-domain>/oauth2/default (or the custom auth server you've configured).
Application type → "Web Application" with the authorization code grant enabled.

Keycloak

Issuer URL → https://<keycloak-host>/realms/<realm-name>.

Auth0

Issuer URL → https://<your-tenant>.auth0.com/.
Make sure the "OIDC Conformant" flag is on in the Auth0 application.

Zitadel

Issuer URL → https://<your-zitadel-instance>.

When the discovery fetch fails

If IntelliAuth cannot fetch the IDP's discovery document, the connection setup fails. Causes:

Issuer URL is wrong. The .well-known/openid-configuration must resolve relative to the issuer.
IDP is behind a private network. IntelliAuth's outbound calls must reach the IDP; if the IDP is internal-only, you need to either expose it or use a different federation pattern.
Self-signed TLS certificate on the IDP. IntelliAuth refuses non-CA-signed certificates. Get a real certificate (Let's Encrypt is free), or terminate TLS at a reverse proxy with a valid cert.

The error message in the tenant admin console identifies which of these applies.

When the user reaches the IDP and signs in but the callback fails

Common causes:

Redirect URI mismatch. The URI registered on the IDP must match what IntelliAuth sends, exactly.
State parameter not echoed. Some legacy IDPs strip state; IntelliAuth refuses the callback in that case (it is a CSRF check).
Nonce mismatch. Similar to state; IntelliAuth refuses if the IDP did not include the nonce in the id token.

For new partner-IDP integrations, expect to spend an hour or two iterating on these. The audit log records each failure with the specific error.