Sign in with any OpenID Connect provider.
Your customer runs Okta, your team runs Keycloak, a partner runs their own: if it has an OpenID Connect issuer, people can sign in with it. Give Auth the issuer and a client; Auth reads everything else from the provider's discovery document.
1
Add the provider in the console
In the console, open Auth, pick your app, then Settings. Under Federated sign-in providers, select Add OpenID Connect provider.
Give it a name: people see "Sign in with <name>". The console suggests a key from it, which you can change before the first save: 1 to 32 lowercase letters, digits or hyphens. The provider's id is oidc-<key>, for example oidc-okta, and it is part of the redirect URI, so it cannot change later. An app can have as many OpenID Connect providers as you need, each with its own key.
2
Create an application at your identity provider
What it is called differs per provider: a Web app in Okta, a confidential client in Keycloak, a Regular Web Application in Auth0.
- Type: web, with a client secret, and the Authorization Code grant. Auth always uses PKCE (S256); allow it if the provider has a setting for it.
- Sign-in redirect URI: the URL from step 2 in the console. It looks like this, with your app's slug and your key:
https://api.auth.productcraft.co/<your-app-slug>/v1/auth/oauth/oidc-<key>/callbackCopy the issuer (for example https://acme.okta.com or https://sso.acme.com/realms/acme), the client ID and the client secret.
3
Check the issuer
Paste the issuer and select Check issuer. Auth fetches {issuer}/.well-known/openid-configuration and shows what it found.
The console lists the sign-in, token and key endpoints Auth will use, the signing algorithms it will accept, and flags scopes or claims you ask for that the provider does not list. The check fails when:
- the issuer or an endpoint is not
https(discovery_not_https); - the document cannot be fetched within 5 seconds (
discovery_unreachable), or the host is a private network address, which Auth never calls (discovery_blocked); - the document misses an endpoint, offers no usable signing algorithm, or lists PKCE methods without S256 (
discovery_invalid); - the document's
issueris not exactly the one you entered (discovery_issuer_mismatch). Copy it from the document, trailing slash and all.
Saving runs the same check and refuses the save with 422 OIDC_DISCOVERY_FAILED when it fails. Auth keeps the document for an hour; if the provider later stops serving it, the provider shows as Blocked with the reason discovery_failed after the next credential check.
4
Credentials, scopes and claims
Paste the client ID and secret, then adjust only what your provider does differently.
- Client authentication: how the secret reaches the token endpoint.
client_secret_basic(an Authorization header) is the default;client_secret_postsends it in the form body. - Scopes:
openid email profileby default.openidis required. - Claims: which ID token claim holds the user ID (
sub), email, email verified, name and picture. Change one only when the provider uses another name, for exampleoidfor the user ID. - Trust the provider's email verification: on by default. Turn it off when the provider lets users or admins set an email without proving it; every email is then treated as unverified and never links to an existing account by itself.
When you save, Auth checks the issuer, then sends the token endpoint a code that cannot work: invalid_client shows as Rejected (sign-in stays blocked until it is fixed), invalid_grant as Accepted.
The same over the API (the secret is write-only):
curl -X PUT https://api.auth.productcraft.co/v1/apps/<your-app-id>/auth-config/providers/oidc-okta \
-H "Authorization: Bearer <your-workspace-api-key>" \
-H "Content-Type: application/json" \
-d '{
"config": {
"display_name": "Acme Okta",
"issuer": "https://acme.okta.com",
"client_id": "<client-id>",
"client_secret": "<client-secret>",
"scopes": ["openid", "email", "profile"],
"claim_mapping": { "sub": "sub", "email": "email" },
"trust_email_verified": true,
"token_endpoint_auth_method": "client_secret_basic"
},
"enabled": false
}'To see what an issuer offers before saving, call POST /v1/apps/<your-app-id>/auth-config/providers/oidc/discover with {"issuer": "https://acme.okta.com"}.
5
Try sign-in, switch it on, add the button
Step 5 runs the round trip in a small window; no account is created and no token is issued.
When it passes, switch on Enabled, save, and make sure your site is under Allowed redirect origins. Then link to Auth:
<a href="https://api.auth.productcraft.co/<your-app-slug>/v1/auth/oauth/oidc-okta/authorize?return_to=https%3A%2F%2Fapp.acme.com%2Flogin%2Fdone">
Sign in with Acme Okta
</a>The user comes back with ?heimdall_code=… and your backend swaps it for tokens:
import { Auth, AuthenticationError } from "@productcraft/auth";
const consumer = new Auth().consumer("acme");
async function completeProviderSignIn(code: string) {
try {
// code: the heimdall_code query value
const { access_token, refresh_token, expires_in } =
await consumer.exchangeProviderCode({ code });
// Drop into your session cookie / store as you'd handle a sign-in.
return { access_token, refresh_token, expires_in };
} catch (err) {
// 401: unknown, expired or already used
if (err instanceof AuthenticationError) return null;
throw err;
}
}The access token's amr claim is ["oauth", "oidc-okta"], and the sign-in webhooks carry "provider": "oidc-okta".
How Auth verifies the sign-in
Auth exchanges the code at the token endpoint with PKCE and checks the ID token it gets back: the signature against the provider's published keys, the issuer exactly as saved, your client ID in the audience, and the nonce Auth sent. An ID token posted straight to the callback is never trusted. OpenID Connect providers are web sign-in only: there is no native ID-token endpoint for them.