Skip to main content

Configure your authorization server

AIGW obtains a token from the merchant's authorization server for calls to the merchant API.

For a walkthrough, follow Configure Keycloak. For Auth0, see integration requirements. For Okta or another authorization server, start with the Generic OAuth requirements.

What the merchant authorization server must do​

For the private_key_jwt path, the merchant AS needs to support two trust relationships:

  1. Trust the AIGW Resource as an assertion issuer. The user assertion is signed ES256 and uses the per-resource issuer/JWKS.
  2. Trust AIGW as a client. AIGW authenticates the configured merchant-AS client using a JWT client assertion signed by the same Resource signing key.

The AS must also:

  • accept the configured merchant issuer as the JWT aud in AIGW assertions;
  • define the requested scope names;
  • map the user assertion sub to 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:

ValueUsed for
AIGW per-resource issuerJWT Authorization Grant / trusted assertion issuer
AIGW per-resource JWKS URLVerify AIGW ES256 assertions and client assertions
Client IDIdentify the AIGW client at your AS
Requested scopesDefine/authorize permissions AIGW may request
Merchant issuer URLMust match AIGW Resource configuration and assertion audience behavior
Merchant token endpointWhere AIGW sends the grant

User identity mapping​

AIGW tries these user identifiers as the assertion's sub, one at a time:

  1. each email returned by the user's sign-in provider, in order;
  2. the AIGW pairwise subject.

It tries the next identifier 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 — step-by-step configuration with screenshots.
  • Auth0 — required capabilities and configuration inputs.
  • Generic OAuth AS — protocol contract for another authorization server.