# Keycloak Integration

This walkthrough connects a Keycloak realm to the gateway end to end. Users sign in to Keycloak, call the gateway with the resulting JWT, and use a caller API key selected by department or group. This avoids distributing per-user keys or duplicating the directory. The guide complements [JWT Authentication](https://docs.api7.ai/ai-gateway/traffic-controls/jwt-authentication.md) and [JWT Claim Mappings](https://docs.api7.ai/ai-gateway/traffic-controls/claim-mappings.md).

What you build:

* A Keycloak realm whose access tokens carry the gateway audience, a `department` claim, and a `groups` claim.
* Two policy keys at the gateway — a restricted `finance` key and an unrestricted platform key.
* Two claim mappings: members of the `platform-admin` group run under the platform key; everyone with `department = finance` runs under the finance key; everyone else is rejected.

The steps were verified against Keycloak 26 (`quay.io/keycloak/keycloak:26.3 start-dev`). Field names may sit in slightly different places in other versions; the values are what matter.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before starting, prepare the following:

* Administrator access to a Keycloak deployment.

* A gateway proxy URL and two working model aliases named `finance-model` and `general-model`. The second model verifies that mapping priority selects the broader administrator key.

* One gateway configuration path:

  <!-- -->

  * AISIX Enterprise or AISIX Cloud with an environment, an attached gateway, permission to manage trust providers, caller API keys, and claim mappings, and the model IDs for both test models.
  * An open-source AISIX gateway with an existing complete `resources.yaml` file that defines both test models and their provider keys, plus access to the gateway process environment.

* `curl` and `jq`. The open-source AISIX gateway path also uses OpenSSL to generate placeholder caller-key values that agents never receive.

## Create the Realm and Client[​](#create-the-realm-and-client "Direct link to Create the Realm and Client")

Create a realm (this walkthrough uses `aisix`) and an OpenID Connect client in it for the applications that will request tokens:

| Client setting        | Value                                                        |
| --------------------- | ------------------------------------------------------------ |
| Client ID             | `ai-clients`                                                 |
| Client authentication | On (confidential — the client has a secret)                  |
| Direct access grants  | On, if you want to test with `curl` password grants as below |
| Standard flow         | Per your application's sign-in shape                         |

Note the client secret from the client's **Credentials** tab.

## Add Claims to Access Tokens[​](#add-claims-to-access-tokens "Direct link to Add Claims to Access Tokens")

Out of the box a Keycloak access token carries neither the gateway's audience nor your directory attributes. Add three protocol mappers to the client (**Clients → ai-clients → Client scopes → ai-clients-dedicated → Add mapper → By configuration**):

| Mapper type      | Configuration                                                                                                                                      |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Audience         | **Included Custom Audience**: `aisix-gateway`, add to access token. The gateway rejects tokens whose `aud` does not include a configured audience. |
| User Attribute   | **User Attribute**: `department`, **Token Claim Name**: `department`, claim type String, add to access token.                                      |
| Group Membership | **Token Claim Name**: `groups`, **Full group path**: Off, add to access token.                                                                     |

One realm-level switch matters on Keycloak 24 and later: custom user attributes such as `department` are silently dropped unless the realm's user profile knows them. Either declare the attribute (**Realm settings → User profile → Create attribute**) or set **Unmanaged attributes** to `Enabled` on the same screen. Without this, the attribute you type on a user simply does not persist, and the claim never appears in tokens.

## Create Groups and Users[​](#create-groups-and-users "Direct link to Create Groups and Users")

Create the `platform-admin` group, then the users:

* `alice`: attribute `department = finance`.
* `bob`: attribute `department = finance` and member of `platform-admin`, to prove that the group mapping wins when both mappings match.
* `charlie`: neither, to prove the default-deny path.

Give every user a password and a **complete profile** (email, first name, last name — or relax the profile requirements in the realm's user profile). A user with unmet profile requirements or pending required actions fails a direct-grant login with `Account is not fully set up`.

## Trust the Keycloak Realm[​](#trust-the-keycloak-realm "Direct link to Trust the Keycloak Realm")

Register the realm as a trust provider. The `issuer` must equal the token's `iss` claim byte for byte — for a realm named `aisix` that is `<keycloak base URL>/realms/aisix` — and the JWKS URI is discovered from it automatically.

For the open-source AISIX gateway, add the provider to the complete [resources file](https://docs.api7.ai/ai-gateway/reference/resources-file.md) that already defines `finance-model`, `general-model`, and their provider keys. If `corp-keycloak` already exists from [JWT Authentication](https://docs.api7.ai/ai-gateway/traffic-controls/jwt-authentication.md), replace that entry instead of adding a second provider with the same name, and omit its `bound_claims` and `required_scopes`:

```
oidc_providers:

  - id: f1aac41c-d83d-41ef-b2d3-abae0b774fbe

    name: corp-keycloak

    issuer: https://sso.example.com/realms/aisix

    audiences: ["aisix-gateway"]
```

In AISIX Enterprise and AISIX Cloud, create the same provider under **OIDC providers** or through the AISIX Cloud Admin API. Use the name, issuer, and audiences shown above. Omit `bound_claims` and `required_scopes` unless the tokens include those values; otherwise AISIX rejects the request with `jwt_claims_rejected` before claim mappings run. See [JWT Authentication](https://docs.api7.ai/ai-gateway/traffic-controls/jwt-authentication.md) for the remaining provider fields.

## Map Claims to Policy Keys[​](#map-claims-to-policy-keys "Direct link to Map Claims to Policy Keys")

Create the two policy keys and the two mappings. The group rule gets the better (lower) priority so platform admins in the finance department still land on the platform key. Use the same configuration path you used to trust the realm.

### AISIX Enterprise or AISIX Cloud[​](#aisix-enterprise-or-aisix-cloud "Direct link to AISIX Enterprise or AISIX Cloud")

Create two [caller API keys](https://docs.api7.ai/ai-gateway/traffic-controls/caller-api-keys.md) in the environment:

* `finance-policy-key`, allowed to call only `finance-model`.
* `admin-policy-key`, allowed to call `finance-model`, `general-model`, and any other models the administrators should reach.

Record both key IDs. Then open the environment's **Claim mappings** page and create these mappings, or submit the equivalent payloads through the [Admin API workflow for AISIX Enterprise or AISIX Cloud](https://docs.api7.ai/ai-gateway/traffic-controls/claim-mappings.md?product=enterprise-cloud\&interface=admin-api#configure-claim-mappings):

| Mapping           | Priority | Condition                              | Policy key           |
| ----------------- | -------- | -------------------------------------- | -------------------- |
| `platform-admins` | `50`     | `groups` contains `platform-admin`     | `admin-policy-key`   |
| `finance-dept`    | `100`    | `department` exactly matches `finance` | `finance-policy-key` |

### AISIX OSS[​](#aisix-oss "Direct link to AISIX OSS")

Generate values for the two caller-key resources and set them in the gateway process environment. The users authenticate with Keycloak tokens, so do not distribute these values to them:

```
export FINANCE_POLICY_KEY="$(openssl rand -hex 32)"

export FINANCE_POLICY_KEY_SHA256="$(printf '%s' "$FINANCE_POLICY_KEY" | sha256sum | cut -d ' ' -f 1)"

export ADMIN_POLICY_KEY="$(openssl rand -hex 32)"

export ADMIN_POLICY_KEY_SHA256="$(printf '%s' "$ADMIN_POLICY_KEY" | sha256sum | cut -d ' ' -f 1)"
```

Add the two policy keys to `api_keys` and the two mappings to `claim_mappings`. Create `claim_mappings` if needed, and keep the other resources unchanged:

resources.yaml (API keys and claim mappings)

```
api_keys:

  - id: d597a758-39d4-4d3f-bb1a-31800c47dcd3

    display_name: finance-policy-key

    key_hash: ${FINANCE_POLICY_KEY_SHA256}

    allowed_models: ["finance-model"]

  - id: 2034d59a-e454-487e-a425-21b75c52b407

    display_name: admin-policy-key

    key_hash: ${ADMIN_POLICY_KEY_SHA256}

    allowed_models: ["*"]



claim_mappings:

  - id: 402ecfdc-945e-49d5-8d2e-a735a12fc975

    name: platform-admins

    jwt_provider: corp-keycloak

    priority: 50

    match:

      - claim: groups

        op: contains

        values: ["platform-admin"]

    resolve:

      api_key_id: 2034d59a-e454-487e-a425-21b75c52b407

  - id: 262a8c5b-b3b8-4fdc-b147-4c8af398ed86

    name: finance-dept

    jwt_provider: corp-keycloak

    priority: 100

    match:

      - claim: department

        op: exact

        values: ["finance"]

    resolve:

      api_key_id: d597a758-39d4-4d3f-bb1a-31800c47dcd3
```

Validate and apply the complete resources file by following [Add New Environment Variables](https://docs.api7.ai/ai-gateway/deployment/configuration-propagation.md#add-new-environment-variables). Exporting the variables on the host does not add them to an already-running container, so recreate the gateway with both variables instead of sending only `SIGHUP`.

`contains` is the operator for Keycloak's array claims (`groups` here, or `realm_access.roles` for realm roles — dots traverse nested objects); `exact` fits single-valued attributes like `department`. Evaluation order, tie-breaking, and the interaction with direct `jwt_subject` bindings are specified in [JWT Claim Mappings](https://docs.api7.ai/ai-gateway/traffic-controls/claim-mappings.md#how-mappings-are-evaluated).

## Verify Claim Mapping[​](#verify-claim-mapping "Direct link to Verify Claim Mapping")

Export the Keycloak client, user, gateway, and model values. The Keycloak URL and gateway URL have no trailing slash:

```
export KEYCLOAK_URL="https://sso.example.com"

export KEYCLOAK_CLIENT_ID="ai-clients"

export KEYCLOAK_CLIENT_SECRET="YOUR_CLIENT_SECRET"

export KEYCLOAK_USERNAME="alice"

export KEYCLOAK_PASSWORD="ALICE_PASSWORD"

export AISIX_PROXY="https://gateway.example.com"

export AISIX_MODEL="finance-model"
```

Fetch the user's token and call the gateway with it as the bearer. URL encoding preserves client secrets and passwords that contain form-delimiter characters:

```
TOKEN=$(curl -sS --fail-with-body \

  "$KEYCLOAK_URL/realms/aisix/protocol/openid-connect/token" \

  --data-urlencode "grant_type=password" \

  --data-urlencode "client_id=$KEYCLOAK_CLIENT_ID" \

  --data-urlencode "client_secret=$KEYCLOAK_CLIENT_SECRET" \

  --data-urlencode "username=$KEYCLOAK_USERNAME" \

  --data-urlencode "password=$KEYCLOAK_PASSWORD" \

  | jq -er '.access_token')



curl -sS --fail-with-body "$AISIX_PROXY/v1/chat/completions" \

  -H "Authorization: Bearer $TOKEN" \

  -H "Content-Type: application/json" \

  --data-binary @- <<EOF

{

  "model": "${AISIX_MODEL}",

  "messages": [

    {

      "role": "user",

      "content": "hello"

    }

  ]

}

EOF
```

Repeat the token and gateway requests after setting `KEYCLOAK_USERNAME`, `KEYCLOAK_PASSWORD`, and `AISIX_MODEL` for each matrix row. Testing another model requires another configured model alias.

For the expected `401` and `403` rows, `curl` exits with a nonzero status because `--fail-with-body` is set, but it still prints the gateway's error body.

The three users pin the whole contract:

| Caller                                              | Request         | Result                                                                                               |
| --------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| `alice` (department = finance)                      | `finance-model` | Succeeds. The `finance-dept` mapping selected the finance key.                                       |
| `alice`                                             | `general-model` | Returns `403`. The finance key's `allowed_models` governs every request it admits.                   |
| `bob` (finance department and platform-admin group) | `general-model` | Succeeds. The group rule at priority 50 outranks the matching finance rule at priority 100.          |
| `charlie` (no match)                                | `finance-model` | Returns `401` with code `jwt_identity_unmapped`. No rule matched, and there is no default admission. |

Every request's usage is attributed to the individual: usage events and logs carry `jwt_subject` (Keycloak's `sub` by default), the provider name, and the matched mapping — see [Attribution](https://docs.api7.ai/ai-gateway/traffic-controls/claim-mappings.md#per-identity-usage-attribution).

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

| Symptom                                              | Cause and fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Token endpoint answers `Account is not fully set up` | The user has pending required actions or an incomplete profile for a direct grant. Complete email/first/last name (or relax the realm's user profile requirements) and clear required actions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `department` never appears in the token              | On Keycloak 24+ the user profile drops undeclared attributes. Declare the attribute or enable unmanaged attributes as described in [Add Claims to Access Tokens](#add-claims-to-access-tokens), then re-set the value on the user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `401` with `jwt_invalid` despite a fresh token       | The token's `aud` does not include a configured audience (missing audience mapper), or `issuer` does not equal the token's `iss` exactly — scheme, host, and path included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `401` with `jwt_identity_unmapped`                   | Verification succeeded but no mapping matched: the claim is missing from the token, the operator does not fit the claim's type (`exact` on an array, `contains` on a string), or no rule covers the identity. Decode the token (for example at jwt.io) and compare its claims against your `match` conditions.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `503` with `jwks_unavailable`                        | AISIX could not fetch or resolve the provider's OIDC discovery document or JWKS. Inspect the `aisix::auth` warning for the failed discovery or JWKS request; a transport failure includes its underlying DNS, connection, or TLS cause. If the identity provider's certificate is signed by a private or enterprise certificate authority, trust it with `upstream.tls.ca_file` as described in [Trust an Upstream Behind a Private Certificate Authority](https://docs.api7.ai/ai-gateway/deployment/tls-and-mtls.md#trust-an-upstream-behind-a-private-certificate-authority). AISIX does not follow redirects on these requests, so the issuer and JWKS URLs must answer directly rather than with a `301`. |
| `403` with `jwt_claims_rejected`                     | The token is valid but does not satisfy the provider's `required_scopes` or `bound_claims`. Check that the token request asked for the required scopes, and compare the token's claim values against `bound_claims`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
