Trusted third-party tokens
Exchange a JWT from an identity provider you trust for an OhAuthCat profile.
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.
Trust an issuer
Section titled “Trust an issuer”POST / (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 |
Exchange a token
Section titled “Exchange a token”POST / 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.
Get an OhAuthCat access token
Section titled “Get an OhAuthCat access token”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:, 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).