Let’s start with a precise, plain-English definition.

An ID token is a piece of digital proof, issued by Keycloak right after a successful login, that tells an application exactly who the user is. It’s built as a JSON Web Token (JWT) — a compact, signed block of text containing structured information called claims, such as the user’s unique ID, name, and email address. Because it’s digitally signed by Keycloak, any application receiving it can verify the information hasn’t been tampered with, without needing to ask Keycloak “is this really true?” every single time.

The ID token belongs to a well-established, widely adopted industry standard called OpenID Connect, which sits on top of the older OAuth 2.0 standard. This matters because it means ID tokens aren’t a Keycloak-specific invention — any application built to understand OpenID Connect can work with an ID token issued by Keycloak, or by a completely different identity provider, without special custom logic.

To appreciate the ID token, it helps to see the gap it was specifically designed to fill.

Before OpenID Connect became widespread, the underlying OAuth 2.0 standard was excellent at handing out tokens that granted access to resources — but it was never actually designed to answer the specific question, “who is this person?” Applications improvised ways to squeeze identity information out of access tokens, which led to inconsistent, insecure, and hard-to-verify approaches across different systems.

OpenID Connect — and with it, the ID token — was created specifically to close this gap: a standardized, purpose-built token whose entire job is representing “who logged in,” cleanly separated from tokens whose job is “what can be accessed.”

Let’s open up the token itself and see what’s actually inside.

An ID token is made of three parts, joined together by dots, though as a beginner you mainly need to understand what the middle part — the payload — contains: a set of claims.

Why Signing Matters

Keycloak signs every ID token cryptographically using a private key that only it holds. Any application can verify this signature using Keycloak’s matching public key, confirming the token genuinely came from Keycloak and that none of its claims were altered afterward — all without needing to contact Keycloak directly for every single check.

A look at the components involved in creating and verifying an ID token.

Every realm in Keycloak has its own signing keys and its own issuer identity, meaning ID tokens from one realm are never mistakenly trusted as valid for another. This isolation is a deliberate security boundary, not an accident of design.

Tracing exactly when and how an ID token comes into existence during a login.

sequenceDiagram
    participant U as User
    participant App as Application
    participant KC as Keycloak
    U->>App: Complete login
    App->>KC: Exchange authorization code
    KC->>KC: Build claims and sign token
    KC-->>App: Return ID token + access token
    App->>App: Verify signature using public key
    App->>App: Read claims (sub, name, email)
    App-->>U: Show logged-in user profile
        

An ID token has a defined lifespan, and understanding it prevents a common source of bugs.

flowchart LR
    A[Token Issued at Login] --> B[Application Reads Claims Once]
    B --> C[Token Stored Briefly by Application]
    C --> D{Still Within Expiration?}
    D -->|Yes| E[Claims Still Considered Valid Snapshot]
    D -->|No| F[Token Considered Stale/Expired]
    F --> G[New Login or Token Refresh Needed]
        

This is the single most important distinction to get right when working with Keycloak tokens.

Understanding both sides helps you use ID tokens appropriately rather than by habit.

A handful of checks separate a safely handled ID token from a security liability.

Keeping an eye on token issuance and validation reveals a lot about system health and potential abuse.

Well-tested habits keep ID token usage clean and secure.

A practical checklist for working with ID tokens correctly.

A few concrete scenarios showing the ID token in action.

No. An ID token proves who the user is, meant for the application itself. An access token grants permission to call APIs on the user’s behalf. They serve different purposes and shouldn’t be used interchangeably.

Yes. The token is signed, not encrypted, so its claims are readable by anyone who has a copy of it — the signature only prevents tampering, not reading. Sensitive secrets should never be placed inside it.

The application should reject it immediately. A mismatched signature means either the token was altered after issuance or it wasn’t actually issued by the expected Keycloak realm.

No. An ID token is a fixed snapshot taken at login time. If a user updates their email or name afterward, the application needs a fresh token — through re-authentication or a new sign-in — to see the updated information.

The audience claim states which specific application the token was intended for, so a token meant for one app can’t be mistakenly (or maliciously) accepted by a completely different one.

Generally not recommended. ID tokens are meant to be short-lived, and storing them long-term risks working with stale identity data and unnecessarily extending how long a leaked token could remain sensitive, even though it will eventually expire.

An ID token in Keycloak is a signed, self-contained proof of identity, issued the moment a user successfully logs in, built on the OpenID Connect standard, and formatted as a JSON Web Token. It carries a small set of claims — who the user is, who issued the token, which application it’s meant for, and when it expires — all protected by a cryptographic signature that lets any receiving application trust the information without needing to call Keycloak back to double-check. Its clean, singular purpose is to answer “who is this?”, deliberately separate from the access token’s job of controlling API access. Understanding this distinction, and applying the right verification checks every time, is what turns the ID token from a convenient shortcut into a genuinely trustworthy piece of identity infrastructure.