Configure your authorization server
AIGW is designed to obtain a token from the merchant's existing authorization server rather than forcing the merchant API to trust the agent's AIGW token directly.
This page describes the vendor-neutral contract. Use Keycloak for the fully documented setup from the supplied test environment. The supplied materials do not contain equivalent verified Auth0 or Okta console walkthroughs, so those pages intentionally stop at the known integration requirements instead of inventing vendor-specific steps.
What the merchant authorization server must do
For the supplied private_key_jwt path, the merchant AS needs to support two trust relationships:
- Trust the AIGW ResourceResourceThe downstream system registered in a Project. Its kind (Token exchange or OAuth client) decides the role AIGW plays. as an assertion issuer. The user assertion is signed ES256 and uses the per-resource issuerPer-resource issuerThe AIGW authorization server dedicated to one Resource, at /<RESOURCE_ID> on the AIGW API host. Agents discover it; merchants trust it./JWKS.
- Trust AIGW as a client. AIGW authenticates the configured merchant-AS client using a JWT client assertion signed by the same Resource signing keySigning keyA per-Resource ES256 key AIGW uses to sign assertions sent to the merchant authorization server, published at the Resource JWKS URL..
The AS must also:
- accept the configured merchant issuer as the JWT
audused by AIGW in the supplied implementation; - define the requested scope names;
- map the user assertion
subto a merchant user, or provision/link that user according to merchant policy; - issue an access token usable by the merchant backend.
Values you receive from AIGW/MCP provider
Expect these values during onboarding:
| Value | Used for |
|---|---|
| AIGW per-resource issuer | JWT Authorization Grant / trusted assertion issuer |
| AIGW per-resource JWKS URL | Verify AIGW ES256 assertions and client assertions |
| Client ID | Identify the AIGW client at your AS |
| Requested scopes | Define/authorize permissions AIGW may request |
| Merchant issuer URL | Must match AIGW Resource configuration and assertion audience behavior |
| Merchant token endpoint | Where AIGW sends the grant |
User identity mapping
The supplied AIGW backend tries sub candidates in this order:
- each email available from login evidence, in order;
- the AIGW pairwise subject.
It tries the next candidate only when the merchant returns invalid_grant and the error description contains user not found. Other failures stop the sequence.
Your authorization server therefore needs a deliberate answer to: What constitutes the merchant user identifier? If you require federated links, create or auto-provision them. If you match email, ensure the grant implementation actually resolves by email.
Vendor guides
- Keycloak — detailed, screenshot-backed configuration from the supplied environment.
- Auth0 — integration requirements only; no verified walkthrough supplied.
- Okta — integration requirements only; no verified walkthrough supplied.
- Generic OAuth AS — protocol contract for another authorization server.