Before diving into configuration screens, it helps to understand the problem Protocol Mappers were built to solve.

Keycloak in one paragraph

Keycloak is an open-source system that handles logins for other applications. Instead of every app writing its own username-and-password screen, checking passwords, and managing “forgot password” emails, apps hand that job to Keycloak. When someone logs in successfully, Keycloak doesn’t just say “yes, this person is real” — it hands the application a small digital document called a token. That token is what the application actually uses to know who the user is and what they’re allowed to do.

So what is a Protocol Mapper?

A Protocol Mapper is a small, named rule inside Keycloak that says: “take this piece of information about the user (or about the login itself) and put it into the token, under this name, in this format.” Without any mappers at all, a token would only carry the bare minimum — things like who issued it and who it belongs to. Protocol Mappers are how you enrich that token with everything else an application might need: a person’s full name, their email, their department, their roles, or even a completely made-up value that never changes.

What problem existed before mappers?

Early identity systems either sent back everything about a user (wasteful and risky) or sent back nothing useful (forcing every app to make follow-up calls just to learn a user’s name). Protocol Mappers give administrators a middle path: expose precisely what is needed, to precisely the applications that need it, and nothing more.

Protocol Mappers don’t float around on their own — they are attached to specific building blocks inside Keycloak. Understanding those blocks makes everything else click.

Two places a mapper can be attached

Keycloak lets you attach a Protocol Mapper in two different places, and the choice matters a lot as a system grows:

The protocol part of “Protocol Mapper”

Keycloak speaks more than one identity language, or “protocol.” The two most common are OpenID Connect (which produces tokens shaped like small pieces of JSON text) and SAML (an older standard used heavily in large enterprises, which produces XML documents called assertions). A Protocol Mapper always knows which protocol it is shaping output for, because a value that makes sense as a JSON field doesn’t automatically make sense as an XML attribute. This is why the word “Protocol” sits right in the name — the mapper’s job changes slightly depending on which language the token needs to be written in.

Zooming in from “what it is” to “what happens the instant a token gets built.”

Every Protocol Mapper is really just three simple decisions bundled together: where does the value come from, what should the field be called in the token, and which part of the token should it appear in. Keycloak ships with several ready-made mapper kinds so administrators rarely have to invent a rule from scratch.

Where the value comes from

A mapper’s source is usually one of a handful of places:

What the field should be called

Every mapper has a target name — the label the value will sit under inside the token. Applications read tokens by looking up these names, so a mismatched or misspelled name means the application simply won’t find the data, even though the mapper technically ran successfully.

Which part of the token it should appear in

This is one of the most important — and most frequently mishandled — decisions. A single login can produce more than one output at once, and a mapper must be told which of these outputs to write into.

A step-by-step walk through exactly when Protocol Mappers get invoked during a real login.

sequenceDiagram
    participant U as User
    participant A as Application
    participant K as Keycloak
    U->>A: Tries to open the app
    A->>K: Redirects for login
    U->>K: Enters credentials
    K->>K: Loads profile, roles, groups
    K->>K: Runs every Protocol Mapper
    K->>A: Sends back ID Token + Access Token
    A->>A: Reads fields from the tokens
        

An important detail: mappers are re-evaluated every single time a new token is issued, including when an old token is quietly refreshed behind the scenes. This means a change to a user’s role or attribute is reflected the very next time a token is minted — it does not require the user to fully log out and log back in, only for their token to be refreshed, which typically happens automatically and fairly often.

Keycloak ships a toolbox of ready-made mapper types so administrators rarely need to build something exotic.

SAML-specific mappers

Because SAML assertions are structured differently from OpenID Connect tokens, Keycloak provides parallel mapper types tailored to XML output — such as mappers that shape “Attribute Statements” inside the assertion instead of JSON claims. Conceptually they do the same job; only the destination format differs.

Protocol Mappers are powerful, but like any powerful tool, using them carelessly creates its own problems.

A token full of the wrong information is a quiet but serious security risk — here is what to watch for.

Minimizing exposure

The safest approach is to only expose what an application genuinely needs to function, and nothing extra “just in case.” This idea, often called the principle of least privilege, applies to tokens the same way it applies to file permissions or database access: fewer exposed fields means fewer things that can go wrong if a token is ever intercepted or mishandled.

The audience field matters more than it looks

The Audience Mapper deserves special attention because it prevents a subtle attack pattern: a token minted for Application A being replayed against Application B, which might trust the token without realizing it was never meant for it. Setting the audience correctly on every client is one of the cheapest, highest-value security habits an administrator can build.

Roles and groups need care too

Because role and group mappers can reveal an organization’s internal structure — team names, seniority levels, or which department someone belongs to — it is worth asking whether every application genuinely needs that level of detail, or whether a simpler yes/no flag would do the same job with less exposure.

Configuring a mapper is only half the job — knowing it’s behaving correctly in production is the other half.

What’s worth watching

Building a review habit

Treat the full list of mappers on a busy realm the way a good gardener treats a growing plant bed: periodically walk through it, ask whether every mapper is still earning its place, and prune anything left over from an application that no longer exists or a field nobody reads anymore.

Some approaches to organizing mappers age gracefully; others quietly become a mess.

A concise checklist gathered from the patterns above, framed as do’s and don’ts.

A few grounded scenarios showing why organizations reach for Protocol Mappers in practice.

flowchart TD
    A["Realm: company.example"] --> B["Client Scope: basic-profile"]
    A --> C["Client Scope: internal-roles"]
    B --> D["Mapper: full name"]
    B --> E["Mapper: email"]
    C --> F["Mapper: role list"]
    C --> G["Mapper: department attribute"]
    B --> H["Client: HR Portal"]
    C --> H
    B --> I["Client: Partner API"]
        

Straightforward answers to the questions beginners ask most often.

No. Keycloak includes a small set of default mappers on the built-in client scopes already, covering common needs like basic profile info. You only add new mappers for fields that aren’t already covered.

Not immediately for tokens already issued, but the very next time their token is refreshed — which usually happens automatically in the background — the updated mapper takes effect.

Yes. A single mapper can be configured to appear in the ID Token, the Access Token, and the UserInfo response simultaneously, or only in whichever subset actually needs it.

Most mapper types simply omit the field from the token rather than including it blank, though this can vary slightly by mapper type and version.

No. Keycloak provides equivalent mapper types for SAML, shaping XML assertions instead of JSON tokens, so both protocol families benefit from the same underlying idea.

There’s no small fixed limit, but practically speaking, tokens grow with every mapper added — so the real constraint is keeping tokens lean rather than any hard technical cap.

Protocol Mappers are the small, precise rules that shape what appears inside every token Keycloak issues. They read from a user’s properties, attributes, roles, or group memberships — or from a fixed value — and write that data into exactly the right output, whether that’s an ID Token, an Access Token, a UserInfo response, or a SAML Assertion. Used thoughtfully, through shared client scopes and lean, well-audited configurations, they let dozens of applications share one identity system while each receiving precisely the information it needs — no more, no less.