A new Keycloak realm is not an OAuth 2.1 server and not a FAPI 2.0 server. It issues authorization codes without PKCE, it accepts authorization requests that were never pushed, and it gives public clients refresh tokens that work from anywhere, as often as you like. Keycloak ships client profiles that fix all three. We tested how well they do it, and found one choice in the setup that decides whether your public clients keep working.
We ran the same ten checks three times against Keycloak 26.8.2. The first realm used console defaults. The second followed Keycloak's guidance and linked the built-in profiles. The third added every single setting the documentation offers for each check. This post shows what changed between the three and how to repeat it.
The setup
- Keycloak 26.8.2 in production mode (
start), imagequay.io/keycloak/keycloak@sha256:3879c623248408de29a5303178b5816c77e8dfef3890c361f8c0bbeaa979ba3b, HTTPS with a lab CA. - Realm
trackfholds one confidential client and stands for the FAPI 2.0 case. - Realm
trackrholds one confidential and one public client and stands for the OAuth 2.1 case. - Every client is created with the fields of the console's create-client wizard. That means standard flow on, direct access grants off and implicit flow off (
NewClientForm.tsxat tag 26.8.2, lines 70 to 72). - Each check runs on a new client of its own, and every test that spends tokens gets its own grant, so one test cannot change what the next one sees.
- Each check first sends a valid request that must succeed on that client. The negative request then changes one thing only. A refusal from a client that cannot work at all proves nothing, so a negative test without a working control counts as inconclusive, not as a pass.
- Every HTTP exchange is written to a log with an id, and each verdict below points to the ids it rests on.
The ten checks come from RFC 9700 (OAuth 2.0 Security Best Current Practice), the OAuth 2.1 draft and the FAPI 2.0 Security Profile. The lab repository lists each requirement with its source section and level.
| # | Check | Level | Default realm | Keycloak guidance | Every setting |
|---|---|---|---|---|---|
| P1 | Password grant refused | MUST | pass | pass | pass |
| P2 | PKCE with S256 required | MUST | fail | pass | pass |
| P3 | PKCE downgrade refused | MUST | pass | pass | pass |
| P4 | Pushed authorization request required (FAPI) | MUST | fail | pass | pass |
| P5 | Exact redirect URI match | MUST | pass | pass | pass |
| P6 | Code reuse refused | MUST | pass | pass | pass |
| P6r | Tokens from a reused code revoked | SHOULD | pass | pass | pass |
| P7 | Code lifetime 60 seconds or less (FAPI) | MUST | pass | pass | pass |
| P8 | Client assertion aud is the issuer, as a string (FAPI) |
MUST | not used | see below | see below |
| P9 | Public client refresh token bound or rotated | MUST | fail | pass | pass |
| P10 |
iss in the authorization response |
MUST | pass | pass | pass |
Seven of the eleven rows pass on a default realm. Direct access grants are off in the wizard, so the password grant is refused. A reused code is refused, and the tokens it first produced stop working. The code lifetime is already 60 seconds, and the issuer is already in the response. The three failures are the ones that matter for browser and mobile apps.
What a default realm gives you
No PKCE. An authorization request with no code_challenge goes through login and comes back with a code. A request with code_challenge_method=plain does the same. This holds for every client in both realms.
No pushed authorization request. On the FAPI realm, a plain front-channel authorization request, never pushed to the PAR endpoint, still ends in a code.
Public refresh tokens that work anywhere. We tested refresh tokens from the public client four ways, each on a fresh token so one test could not spoil the next. A normal refresh returned 200. Keycloak handed back a new refresh token, but the old one still worked when we sent it again, with 200. A refresh with a DPoP proof from a different key returned 200, and one with no proof at all also returned 200. So a refresh token taken from a single-page app keeps working, from any machine, until it expires.
Keycloak's fix: client profiles
Keycloak has three global client profiles for this: fapi-2-dpop-security-profile, oauth-2-1-for-confidential-client and oauth-2-1-for-public-client. You do not attach a profile to a client directly. You write a client policy, and the policy has two parts. Its conditions decide which clients it applies to, and its profiles decide which executors run on them.
With the profiles linked, the same requests get these answers:
- No
code_challenge:Missing parameter: code_challenge_method. -
code_challenge_method=plain:Invalid parameter: code challenge method is not matching the configured one. - Unpushed request on the FAPI realm: HTTP 400 and an error page.
- Public refresh token with a different DPoP key: 400. With no proof: 400.
The public refresh token is now bound to the client's DPoP key, so a stolen copy is useless elsewhere. It is still not rotated in RFC 9700's sense, because Keycloak issues a new refresh token but the old one keeps working from the right key. RFC 9700 accepts either binding or rotation, so this passes. If you also want rotation, turn on Revoke Refresh Token in the realm settings and set Refresh Token Max Reuse to 0. With both set, the old token returned 400 once it had been used.
The FAPI profile also changes your client in ways you should plan for:
- It switches a confidential client to
private_key_jwtauthentication (client-jwtin the admin API) but does not register a key. Every token request then fails withUnable to load public keyuntil you add the client's JWKS. - It enforces PAR even though the client's own Pushed authorization request required switch stays off. Read the policy, not the client page, to see what is enforced.
The condition trap
Keycloak's documentation says to use oauth-2-1-for-confidential-client for confidential clients or oauth-2-1-for-public-client for public clients. It does not say which policy condition to use. The quickest setup is one policy with the condition any-client and both OAuth 2.1 profiles linked. We set that up on a fresh realm on 26.8.2 and created a public client with the wizard fields.
The public client came back with clientAuthenticatorType set to client-jwt and with mTLS-bound access tokens switched on. The confidential profile had been applied to it as well. Its first authorization request, with correct PKCE, was refused before login:
error=invalid_client
error_description=invalid client access type: public
The same client in a realm with one policy per client type kept its authentication type, got PKCE S256 and DPoP binding, and reached the login page. This is the policy set that works:
{
"policies": [
{
"name": "oauth21-confidential",
"enabled": true,
"conditions": [
{ "condition": "client-access-type", "configuration": { "type": ["confidential"] } }
],
"profiles": ["oauth-2-1-for-confidential-client"]
},
{
"name": "oauth21-public",
"enabled": true,
"conditions": [
{ "condition": "client-access-type", "configuration": { "type": ["public"] } }
],
"profiles": ["oauth-2-1-for-public-client"]
}
]
}
You can send it to PUT /admin/realms/{realm}/client-policies/policies, or build the same two policies in the console under Realm settings, Client policies. On our FAPI realm any-client was fine, because every client in it is a confidential FAPI client. In any realm that mixes client types, use client-access-type.
One deliberate difference from FAPI 2.0
FAPI 2.0 asks the server to accept only its own issuer identifier, as a string, in the aud claim of a client assertion. Under the FAPI profile, Keycloak 26.8.2 also accepts a JSON array that holds only the issuer, ["https://.../realms/trackf"]. It refuses an array with any second value, an array with only another value, and the token endpoint URL, so no unrelated audience gets through. We reported this as issue #54743. The maintainers closed it as not planned, because a single-value array still rules out every other audience and refusing it adds no security. If your conformance suite checks the exact type, expect this one finding.
Run it yourself
Everything is in the lab repository, keycloak-client-profiles-lab. On a Linux machine with Docker, one command runs it all:
./run.sh
-
setup-keycloak.shstarts Keycloak at the digest above on127.0.0.1, with a throwaway lab CA. -
probes.py S0,S1andS2Lbuild both realms for the default, guidance and every-setting cases, run the ten checks and writeresults.json, with a verdict and evidence ids for every test. -
trap_anyclient.pybuilds the two policy sets and records what happens to a public client in each. -
requirements.ymllists every requirement, its source section and its tests.
Codes and tokens are redacted in the log by default. Run the lab against your own Keycloak version before you trust a table written for someone else's, and if a row differs, open an issue with your results.json.
What we did not test
The OAuth 2.1 confidential profile binds tokens with mutual TLS, and our lab has no client-certificate PKI yet. So the confidential client in trackr was judged at the default stage only, and under the profiles its results are marked inconclusive. We did not test the mTLS variants of the FAPI profile, and we did not run the OpenID conformance suite, which Keycloak runs itself for its certification.
Top comments (0)