Skip to content

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 header and claims;
  • kid, alg and signatureValid;
  • issuerMatchesRealm and expired;
  • 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 store backendId and its backendType, for example pkcs11 for an HSM), or null when no key of the realm has that kid.

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.

See also