Test tokens¶
Check which of a realm's keys signed a token, where that key is held, and whether the signature is valid. You can get a token with client credentials, or paste one you got elsewhere.
What it does¶
Test tokens is in the admin console under Manage → Realms. It has two modes:
| Mode | What you do | What happens |
|---|---|---|
| Client credentials | Choose a confidential client of the realm, enter its secret and an optional scope, and select Get token. | HelixIAM requests one token from the realm's own token endpoint, as the client would, and checks it. |
| Inspect a token | Paste an access or ID token, for example one an application got with the authorization code flow, and select Inspect token. | HelixIAM checks the token. |
Only clients of this realm that may use the client credentials grant are offered. If there are none, turn the grant on for a confidential client under Applications, or inspect a token instead.
Who may use it¶
An administrator with the permission manage-realm in the realm, and only for that realm. Only the realm's own keys
are read: a token whose issuer names another realm, or a kid the realm does not publish, is reported as
Signature invalid with no signing key.
What the result shows¶
- Signing key: the key ID (
kid), the realm key, algorithm, purpose and status. - Custody: where the key is held.
- Direct: the private key never leaves the key store.
- Wrapped: encrypted under the key store's key.
- Software: encrypted in the database.
- Key store: for a direct or wrapped key, the realm's key store, with its kind (for example HSM). See Key custody.
- Signature verdict: Signature valid or Signature invalid. The signature is checked against the public key
the realm publishes in its JWKS under that
kid. RS256, PS256, ES256, ES384 and EdDSA are supported. - Issuer check: Issuer is this realm, or Issuer differs from the realm's public issuer. The full issuer is compared with the realm's public issuer.
- Expiry: Expired or Not expired.
- The decoded header and claims. A client credentials test also shows the token, with a Copy token button.
The one-line verdict reads, for example, "Signed by key {kid} in key store {store} (HSM, direct custody) — signature valid".
Privacy¶
The client secret and the token are never stored and never audited. Each test is written to the audit log as
TOKEN_TEST. It names the mode, the client, the kid, the key and the verdict, and nothing else. The answer is sent
with Cache-Control: no-store.
Admin API¶
POST /admin/realms/{realmId}/token-tests needs the permission manage-realm in that realm. Both examples assume
you have set $HELIX_URL and $REALM and logged in, see
Authenticating to the API.
Client credentials mode:
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"mode": "client_credentials", "clientId": "reporting", "clientSecret": "<client-secret>", "scope": "reports.read"}' \
"$HELIX_URL/admin/realms/$REALM/token-tests"
Inspect mode:
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
-d '{"mode": "inspect", "token": "<jwt>"}' \
"$HELIX_URL/admin/realms/$REALM/token-tests"
The answer has:
- the decoded
headerandclaims; kid,algandsignatureValid;issuerMatchesRealmandexpired;message, which says why the signature is not valid or why the issuer differs;signingKey(keyId,kid,algorithm,purpose,status,custody, and for a wrapped or direct key the realm's key storebackendIdand itsbackendType, for examplepkcs11for an HSM), ornullwhen no key of the realm has thatkid.
A client credentials test also returns the token.
The client credentials request goes from the server to its own token endpoint over the loopback address
(/realms/{realmId}/oauth2/token, nothing else). With IDP_BASE_URL set (Helm idpBaseUrl), the token carries the
realm's public issuer, as one from the public token endpoint does. The server needs its plain HTTP API port behind the
TLS-terminating proxy (server.ssl.enabled=false, the default), and the client must accept client_secret_basic. If
server.address is a single non-loopback IP address, the server logs a warning and test tokens carry the internal
issuer.
Limits¶
Starting an authorization code flow from the console is not available yet. To check a token from a sign-in, sign in to the application and paste its token under Inspect a token.