Skip to main content
Version: 1.11.0

JWT Claim Mappings

JWT Authentication can bind a fixed external identity to a caller API key. Claim mappings let operators apply a shared policy to identities admitted by department, group, or application claims, without creating a separate key for every member.

A mapping matches verified claims and selects an existing caller API key. Admitted identities inherit its model access, tool access, and rate limits. In AISIX Enterprise and AISIX Cloud, matching budgets also apply. Usage events retain the individual identity from the token.

A token cannot name a new upstream, widen a model allowlist, or create a budget. Trust providers can also extract cost attribution tags from claims; those values set attribution tags and grant no access. AISIX rejects a token that matches no direct binding or claim mapping.

How Mappings Are Evaluated​

For each request with a JWT bearer, after the full trust-provider verification described in JWT Authentication:

  1. If a caller API key binds the token's subject directly through jwt_subject and jwt_provider, the request runs as that key. The direct binding is authoritative for its subject, including when the key is disabled and the request is rejected. Mappings never override it.
  2. Otherwise, AISIX evaluates the enabled mappings whose jwt_provider names the matched trust provider. Lower priority values run first, with ties broken by name. The first mapping whose match conditions all hold selects the key.
  3. If no mapping matches, the request is rejected with jwt_identity_unmapped. There is no default admission.

Keep mapping names unique in a format-2 resources file. If two entries share both a priority and a name, the resource ID becomes the final tie-breaker.

The match field of a mapping is a list of conditions, which must all hold:

FieldDescription
claimNon-empty claim path. AISIX first looks for a top-level claim with the full name; if none exists, dot notation selects a nested value. For example, realm_access.roles selects roles from realm_access. A missing claim never matches.
opWith exact, the claim must be a string equal to one of values. With contains, the claim must be an array containing one of values among its string items; non-string items are ignored. A claim whose type does not fit the operator never matches.
valuesOne or more accepted strings. The condition holds when any one matches.

The named trust provider must verify the token before AISIX considers a mapping.

In AISIX Enterprise and AISIX Cloud, the target key must remain in the same environment. Repoint or delete a mapping before deleting its key. A format-2 resources file validates mapping shape but does not resolve provider names or key IDs at load, so check those references before applying it.

Prerequisites​

Before starting, prepare the following:

  • A registered OIDC trust provider and model configured as described in JWT Authentication.
  • A caller API key to act as the shared policy key. Configure the model access, tool access, and rate limits that admitted identities should inherit. In AISIX Enterprise and AISIX Cloud, matching budgets also apply.
  • One configuration path:
    • AISIX Enterprise or AISIX Cloud with an environment and an attached gateway. Dashboard users need permission to manage claim mappings and update provider requirements. Admin API users need a write-scoped token from an identity allowed to manage claim mappings, update OIDC providers, read the policy key, and read usage events.
    • An open-source AISIX gateway with a complete resources.yaml file and access to the gateway process environment.
  • curl and jq for the AISIX Cloud Admin API workflow. The open-source path uses OpenSSL to generate the policy-key value shown below.

Review Trust Provider Requirements​

AISIX evaluates trust-provider requirements before claim mappings. Remove or update any bound_claims condition whose decision the mapping should make. For this workflow, remove the JWT Authentication example's department: ai-lab condition because the mapping decides which departments to admit.

Open OIDC providers, edit corp-keycloak, and remove the department row from Bound claims (optional). Keep the required scope.

Provider bound-claim condition cleared before department admission moves to a mapping

Select Save changes.

Mapped tokens must still satisfy every requirement left on the provider. The examples retain the ai.access scope.

Configure Claim Mappings​

Configure claim mappings using the management path for your deployment.

Create the mapping in the same environment as its trust provider and policy key.

Use the shared caller key prepared in the prerequisites. This example names it finance-policy-key.

  1. Open Claim mappings in the environment and select New claim mapping.
  2. Set Name to finance-dept and OIDC provider to corp-keycloak.
  3. Set Priority to 100 and Resolve to API key to the prepared policy key.
  4. Under Match conditions, enter department, choose is exactly, and enter finance as the accepted value.
Finance department mapping with an exact claim condition and policy key
  1. Select Create mapping. Check its priority, provider, target key, and condition on the saved row.
Saved finance department mapping and its evaluation priority

To update the rule, select Edit and change its provider, priority, policy key, or conditions. The name is fixed at creation.

Claim mapping editor with its priority, policy key, and match condition

Select Save changes.

Select Disable to keep the rule while excluding it from evaluation. Select Enable to use it again.

Claim mapping retained in a disabled state

Keep finance-dept enabled while completing the priority and verification examples below.

Managed Mapping Fields​

FieldDescription
nameMapping name, unique within the environment and fixed at creation. Also the evaluation tie-break for equal priorities.
jwt_providerName of the OIDC provider whose tokens this mapping applies to. A mapping never matches a token verified by a different provider.
priorityNon-negative evaluation order among the provider's mappings. Lower values run first. Defaults to 0.
matchFrom 1 to 16 claim conditions; all must hold.
resolve.api_key_idID of the caller API key that matching requests run as.
enabledWhether the mapping participates in evaluation. Defaults to true; a disabled mapping is retained but skipped.

Names can contain up to 120 characters. A condition has a claim path up to 256 characters and 1 to 64 accepted values, each up to 256 characters.

Verify Mapping Selection​

First, verify the base mapping end to end. Use a JWT that matches finance-dept but has no direct caller-key binding, ensuring that only the mapping can admit the request.

  1. Choose a subject that is not configured through jwt_subject and jwt_provider.
  2. Obtain a signed JWT containing the claims required by the mapping.
  3. Choose a model that only the policy key selected by the mapping can access.

Export the gateway URL, signed JWT, and model alias for this check:

# AISIX_PROXY is the gateway origin without a trailing slash or endpoint path.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_JWT="YOUR_SIGNED_JWT"
export AISIX_MODEL="MODEL_ALLOWED_ONLY_BY_THE_POLICY_KEY"

Send the model request through the gateway:

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
-H "Authorization: Bearer $AISIX_JWT" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$AISIX_MODEL"'",
"messages": [
{"role": "user", "content": "Reply with a short greeting."}
]
}'

Confirm that the request succeeds, then use the selected path below to verify which mapping admitted it.

Expand the request on Logs. Confirm that JWT identity shows the expected subject and provider and that Claim mapping shows the rule that admitted the request.

Request details with the JWT subject, provider, and admitting mapping

After confirming the successful path, verify that unmatched identities are denied. Send a valid JWT that matches no direct binding or claim mapping. An OpenAI-compatible request should return 401 with error.code: jwt_identity_unmapped.

For a complete Keycloak example covering successful, denied, and overlapping mappings, see Keycloak Integration.

Optional: Layer Mappings with Priorities​

Set priorities so the intended rule wins when claims match more than one mapping. Lower values run first.

  1. Prepare a second caller policy key with the access controls required by platform administrators.
  2. Select New claim mapping, set Name to platform-admins, and Priority to 50.
  3. Select corp-keycloak and the prepared platform policy key.
  4. Under Match conditions, enter groups, choose array contains, and enter platform-admin.
Group-membership mapping using array contains with priority 50
  1. Select Create mapping. Confirm that the list places it before finance-dept, whose priority is 100.
Platform administrator rule evaluated before the finance department rule

A token carrying both department: finance and the platform-admin group now resolves through platform-admins at priority 50 rather than finance-dept at priority 100. Identities that need different effective access controls should resolve to different policy keys. Multiple mappings can resolve to the same key when they should grant the same access.

Repeat the verification above with a JWT that matches both mappings. Confirm that jwt_claim_mapping reports platform-admins, or request a model available only through its policy key. This verifies that the lower priority value wins.

Per-Identity Usage Attribution​

Usage events for requests admitted through a mapping include three attribution fields. Configured observability exporters receive the same fields:

FieldDescription
jwt_subjectThe token's identity-claim value, identifying who ran the request even when many identities share the policy key.
jwt_providerThe trust provider that verified the token.
jwt_claim_mappingThe mapping that admitted the request. Empty for identities bound directly through jwt_subject and jwt_provider.

The fields are included in usage events and CSV exports.

To find one identity's requests, enter its value in the JWT subject filter and press Enter.

Logs filtered by the JWT subject

The subject is personal data when the identity claim contains names or email addresses. Review where exporters deliver usage data before enabling them alongside claim mappings.

Rejection Behavior​

Mapped authentication extends the JWT rejection table. AISIX rejects a verified token before it reaches a provider, MCP server, or vector store when the identity cannot resolve safely.

Each failure below returns HTTP 401. OpenAI-style routes return jwt_identity_unmapped as error.code, while the reason label on aisix_auth_decisions_total identifies the operator-side cause:

reasonMeaning
jwt_identity_unmappedThe verified identity has no direct key binding, and no enabled mapping for its trust provider matches all claim conditions.
claim_mapping_target_missingA mapping matched, but its target caller API key is missing from the active gateway configuration. Control-plane validation ordinarily prevents this state. Format-2 resources files do not validate this reference, so check the key ID and the gateway's active resources.
jwt_binding_ambiguousMore than one caller API key has the same jwt_provider and jwt_subject binding, so the gateway fails closed instead of evaluating mappings. Control-plane validation prevents this state; format-2 files do not check binding uniqueness.

Clean Up the Example Mappings​

Keep the mappings when they represent real access policy. Otherwise, remove the two examples after completing verification.

Open Claim mappings. Select Delete on platform-admins and finance-dept, confirming each deletion.

Confirmation before deleting a claim mapping

Next Steps​