Skip to main content

Generic OAuth authorization server

Use this page when your merchant authorization server is not Keycloak or when you are implementing the AIGW contract directly.

Option A — RFC 7523 path (private_key_jwt in the current AIGW console)​

For the supplied backend, this setting results in two JWTs sent to the merchant token endpoint:

  1. User assertion used with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.
  2. Client assertion used for JWT client authentication.

Both are ES256-signed with the AIGW ResourceResourceThe downstream system registered in a Project. Its kind (Token exchange or OAuth client) decides the role AIGW plays. signing keySigning keyA per-Resource ES256 key AIGW uses to sign assertions sent to the merchant authorization server, published at the Resource JWKS URL..

User assertion claims​

iss = https://api.aigw.eval.loginid.ai/<RESOURCE_ID>
sub = external user reference (email candidate(s), then AIGW subject)
aud = <merchant issuer configured in AIGW>
iat = now
exp = now + assertion lifetime
jti = unique UUID

Client assertion claims​

iss = <merchant-AS client ID>
sub = <merchant-AS client ID>
aud = <merchant issuer configured in AIGW>
iat = now
exp = now + assertion lifetime
jti = unique UUID

Your AS must verify ES256 against:

https://api.aigw.eval.loginid.ai/<RESOURCE_ID>/.well-known/jwks.json

Option B — RFC 8693 Token Exchange​

The supplied backend can also send:

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<AIGW signed user assertion>
subject_token_type=urn:ietf:params:oauth:token-type:jwt
requested_token_type=urn:ietf:params:oauth:token-type:access_token
resource=<Resource indicator, if configured>
scope=<requested scopes>

with JWT client authentication.

External subject tokens

The merchant AS must accept an external AIGW-signed subject token. Do not assume a product's "standard token exchange" feature supports external subject tokens; Keycloak's standard mode does not for this pattern.

User resolution​

AIGW tries candidate sub values in order. Your AS needs to return a recognizable invalid_grant / user not found error if you want AIGW to try the next candidate. Other errors stop the fallback loop.

Scope contract​

Every AIGW requested scope should exist in the merchant AS and map to the backend permission expected by the API. AIGW sends the requested/intersected scope string to the merchant token endpoint.

Response contract​

For a successful merchant-token acquisition, return an OAuth access-token response. In RFC 8693 mode, the supplied backend also expects a valid issued_token_type of access token and a meaningful token_type.