Skip to content
Dashboard
Theme
Theme

Trusted third-party tokens

Exchange a JWT from an identity provider you trust for an OhAuthCat profile.

View Markdown

If your users already sign in somewhere else (your own identity service, another auth provider, a partner), OhAuthCat can accept that issuer’s JWTs and return an OhAuthCat profile for them, in the spirit of OAuth token exchange (RFC 8693). This is a Business plan feature.

POST /v1/trusted_issuers (or ohauthcat trusted-issuers create) with:

Field Meaning
issuer The exact iss value
jwks_url Where the issuer publishes its public keys
audiences 1 to 10 accepted aud values
algorithms Allowed algorithms: RS256, ES256 and/or EdDSA
skew_seconds Allowed clock skew, 0 to 300 (default 60)
claim_mapping Which claims hold the subject, email, email verification and names
organization_id The organization every exchanged user belongs to (optional)
jit_by_domain Instead, place users by a verified domain of a verified email

POST /v1/sso/token_exchange with the token (scope sso:exchange) returns the profile.

OhAuthCat checks the algorithm against the issuer’s list before touching any key, refuses tokens that carry their own key or key URL (jku, x5u, jwk, x5c) or a crit header, takes keys only from the registered JWKS, and requires an exact issuer and audience, an exp, a lifetime of at most 24 hours and plausible nbf and iat. Each jti is accepted once. Failures answer trusted_token_invalid or trusted_token_replayed.

The exchange returns the profile and stores it (audit trusted_token.exchanged). Exchanged identities are not end users: they never count toward monthly active users and are not billable.

Add client_id (a publishable key of the environment) to the exchange and the answer also carries access_token, issued_token_type, token_type and expires_in. The token is an ES256 JWT signed with the environment’s key ring (JWKS on the login host), issued by https://login.ohauthcat.com, with aud = the client_id, sub = the stored profile’s tprof_… ID, and the claims ext_iss, ext_sub, trusted_issuer_id, env, org_id (when the profile belongs to an organization) and jti. It lives 10 minutes by default (configurable from 1 minute to 1 hour).