spring-auth-demo/docs/17-keycloak-setup.md

# 17 — Keycloak setup, and the three ways the realm import bites

[← what an unknown kid costs](16-jwks-amplification.md) · [next: resource server checklist →](18-resource-server-checklist.md)

```bash
docker compose -f oauth2-resource-server/docker/compose.yaml up -d
cd oauth2-resource-server && ./scripts/run-rs.sh keycloak,roles
./scripts/keycloak-demo.sh
```

Transcript: [`rs-keycloak.txt`](output/rs-keycloak.txt). Keycloak **26.7.2**, released
19 August 2026.

The point of running against a real issuer is that nothing in the resource server changes.
The application code is identical to the stub runs; one property differs:

```yaml
spring.security.oauth2.resourceserver.jwt.issuer-uri: http://localhost:8080/realms/demo
```

## Pin `KC_HOSTNAME`

Keycloak derives the `iss` claim, and the `issuer` in its discovery document, from the
request host unless you pin it. A token fetched through `localhost:8080` and the same token
fetched through `keycloak:8080` from inside a Docker network carry **different issuers**,
and [chapter 12](12-issuer-and-audience.md) explains why `JwtIssuerValidator` will refuse
one of them.

```yaml
environment:
  KC_HOSTNAME: http://localhost:8080
  KC_HOSTNAME_STRICT: "false"
```

This is the fix for the majority of *“the token works in curl but not from the
application”* reports. Both must agree with the value your resource servers are
configured with, from wherever they run.

## Keycloak does not add an `aud` for you

An access token from a bare Keycloak client has no `aud` naming your resource server. Since
[chapter 12](12-issuer-and-audience.md) argues you should be validating `aud`, you need a
mapper:

```json
{
  "name": "reports-api-audience",
  "protocolMapper": "oidc-audience-mapper",
  "config": {
    "included.client.audience": "reports-api",
    "access.token.claim": "true"
  }
}
```

Note `included.client.audience` for a client that exists in the realm, versus
`included.custom.audience` for an arbitrary string. Using the former means the audience
value is checked against a real client at configuration time.

## A `clientScopes` key in the import replaces the built-ins

This one cost a rebuild. A realm export/import that declares:

```json
"clientScopes": [ { "name": "reports:read", ... } ]
```

does not *add* that scope. It **replaces the entire set**, and Keycloak's built-in
`profile`, `email`, `roles`, `acr`, `basic` and `web-origins` scopes are never created.
Tokens from that realm then have:

- no `realm_access` claim, because the `roles` scope is what adds it
- no `preferred_username`, because the `profile` scope is what adds it

which looks exactly like a broken authorities converter, and sends you to
[chapter 14](14-authentication-converter.md) to debug something that is not wrong. Verified
on 26.7.2 by listing the realm's client scopes through the admin API after import:

```
=== realm client scopes available ===
  offline_access
  reports:read
```

[`realm-demo.json`](../oauth2-resource-server/docker/realm-demo.json) therefore declares no
`clientScopes` at all, and gets permissions across using realm roles and client roles
instead.

## Users need a name

A user in a realm import with no `firstName` and `lastName` fails the password grant with a
message that names nothing useful:

```json
{"error":"invalid_grant","error_description":"Account is not fully set up"}
```

The realm's default required actions want a complete profile. Supply the names, and
`"requiredActions": []`.

## Read the JWK Set before assuming it holds one key

```
keys published: 2
 kid=drdWA3YaK3PfH8uKORPsqYsf30mlkxtLKJdvYFzWqO4 alg=RSA-OAEP use=enc kty=RSA
 kid=B8LKu8nKy9b_CCTMqaZBdRH7dH1ASVjg5Do5hElKpQE alg=RS256 use=sig kty=RSA
```

A JWK Set contains keys you must not verify signatures with. Nimbus's
`JWSVerificationKeySelector` filters on `use` and `alg` before matching `kid`, so this is
handled — but if you are writing anything that reads a JWK Set yourself, filter on
`use: "sig"` rather than taking `keys[0]`.

## `typ` is a claim as well as a header

A Keycloak access token has `typ: "JWT"` in the **JOSE header** and `typ: "Bearer"` in the
**claim set**. `JwtTypeValidator` reads the header, so Keycloak passes the default type
check. Nothing validates the claim. Do not write a validator that reads
`jwt.getClaimAsString("typ")` expecting the header value.

## `start-dev` resets everything

Including the signing keys. Every restart is a new realm from the import, and a new `kid`.
Convenient for the rotation work in [chapter 15](15-jwks-caching-and-rotation.md); a
surprise if you were expecting yesterday's tokens to still verify.

## What a real access token looks like here

```json
{
  "iss": "http://localhost:8080/realms/demo",
  "aud": "reports-api",
  "typ": "Bearer",
  "scope": "email profile",
  "preferred_username": "alice",
  "realm_access":    { "roles": ["USER"] },
  "resource_access": { "reports-api": { "roles": ["reports-reader"] } }
}
```

Which produces, with the converter from [chapter 14](14-authentication-converter.md):

```
"authorities": ["FACTOR_BEARER", "ROLE_USER", "ROLE_reports-reader", "SCOPE_email", "SCOPE_profile"]
```

There is no `client_id` claim, which is why
`JwtValidators.createAtJwtValidator()` — which requires one — refuses Keycloak tokens
unless reconfigured. Keycloak puts the client in `azp`.

---

[← what an unknown kid costs](16-jwks-amplification.md) · [next: resource server checklist →](18-resource-server-checklist.md)

---

For the comparison Keycloak invites — what it costs to run the equivalent yourself in
Spring — see [`authorization-server/`](authorization-server/README.md), and in
particular [10 — Should you run one at all](authorization-server/10-should-you.md).