# 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](key-custody.md).
- **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](../getting-started/api-authentication.md).

Client credentials mode:

```bash
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:

```bash
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

- [Key custody (HSM / KMS)](key-custody.md)
- [Realm keys](realm-keys.md)
- [Upgrades](upgrades.md#test-tokens)
