Protocol mappers

Protocol mappers are the rules that turn user, group, organization and client data into JWT claims. Each mapper belongs to a client scope and runs during token generation.

A mapper is identified by a mapper_type string and carries a JSON config. FerrisKey keeps the Keycloak names for both, so configuration written for Keycloak is recognizable here: keys are dotted, and their values are strings, including the booleans. FerrisKey runs eleven mapper types, listed below.

Keys every mapper reads

Both token flags default to true when the key is absent, so a mapper with no flags writes to both tokens. The client role mapper, the full-name mapper and the audience mapper read the two flags but not claim.name.

token.claim.name is accepted as a legacy alias for claim.name by the property, attribute, realm role and hardcoded claim mappers, because some earlier consoles stored mappers that way. The group and organization mappers read only claim.name. Prefer claim.name in anything new.

A claim name is a dotted path of at most 8 non-empty segments and at most 255 characters. The API rejects a longer claim.name or token.claim.name with a 422 invalid_claim_name. At token time a name outside that shape is dropped silently, with only a warning in the server log.

Mapper types

oidc-usermodel-property-mapper

Maps a built-in user field to a claim.

{
  "user.attribute": "username",
  "claim.name": "preferred_username",
  "jsonType.label": "String",
  "access.token.claim": "true",
  "id.token.claim": "true"
}

oidc-full-name-mapper

Writes the user’s first and last name, trimmed and joined with a space, into the name claim.

The claim name is fixed: this mapper does not read claim.name. It emits nothing when both names are empty. Its only keys are the two token flags.

{
  "access.token.claim": "false",
  "id.token.claim": "true"
}

The seeded profile scope carries given_name and family_name but no name, so add this mapper to a scope if a client expects it.

oidc-usermodel-attribute-mapper

Maps a custom user attribute to a claim. Use it for business data: department, plan tier, feature flags.

The value is always a string. This mapper does not read jsonType.label, so a numeric attribute reaches the token as text.

{
  "user.attribute": "department",
  "claim.name": "department",
  "access.token.claim": "true",
  "id.token.claim": "true"
}

oidc-usermodel-realm-role-mapper

Writes the user’s realm role names into the token. Roles the user inherits from groups are included.

{
  "claim.name": "realm_access.roles",
  "access.token.claim": "true",
  "id.token.claim": "true"
}

{
  "realm_access": {
    "roles": ["admin", "user-manager", "viewer"]
  }
}

oidc-usermodel-client-role-mapper

Writes client-scoped roles under resource_access.<client_id>.roles. The placement is fixed: this mapper does not take a claim.name.

{
  "resource_access": {
    "backend": { "roles": ["read", "write"] }
  }
}

oidc-group-membership-mapper

Writes the groups the user belongs to.

prefix.org exists because a FerrisKey token can carry groups from several organizations at once, and paths are relative to their org, so /finance from two organizations would collide. It only applies to full paths.

oidc-organization-membership-mapper

Writes the organizations the user belongs to, as a JSON object keyed by alias. Keying by alias means a consumer can look up one organization without scanning an array.

id, name and alias are always present. Domain and attributes are opt-in so tokens stay compact by default. A user with no organization gets an empty object.

oidc-organization-detail-mapper

Writes detail about a single organization.

id, name, alias and domain are always present, and domain is null when the organization has none. If the user belongs to no matching organization, the mapper emits nothing.

oidc-organization-role-mapper

Writes the roles a user holds within the scope of each organization, keyed by organization alias. Realm roles land under roles, client roles under clients.<client_id>.roles. An organization where the user holds no scoped role is left out.

Org-scoped roles come from two sources, merged during token assembly: roles assigned directly to the membership, and roles inherited from the user’s groups in that organization.

oidc-audience-mapper

Adds an entry to the audience (aud) claim of the access token. Use it when a token has to be accepted by more than one resource server.

{
  "included.client.audience": "another-client",
  "access.token.claim": "true",
  "id.token.claim": "false"
}

The access token’s aud starts as ["<realm_name>-realm", "account"] and the mapper appends to it. A token request with a resource parameter replaces the whole list with that resource. The ID token’s aud is the client’s client_id and no mapper changes it.

oidc-hardcoded-claim-mapper

Injects a static value. Useful for environment indicators or tenant identifiers that do not come from user data.

{
  "claim.name": "environment",
  "claim.value": "production",
  "jsonType.label": "String",
  "access.token.claim": "true",
  "id.token.claim": "false"
}

Reserved claim names

Ten claim names are removed after every mapper has run, so a mapper cannot overwrite them:

sub  iat  jti  iss  typ  azp  aud  scope  exp  client_id

Target one of these and the mapper appears to be configured correctly yet changes nothing. aud is on the list, which is exactly why adding an audience needs oidc-audience-mapper, which contributes audiences through a separate channel, and not a hardcoded mapper pointed at aud.

Execution order

Mappers within a scope run in the order they were created. Default scopes run before the optional scopes the request named.

Token generation pipeline

1. Resolve scopes. The client’s default scopes, plus any optional scopes named in the request’s scope parameter.
2. Gather mappers. Every protocol mapper on the active scopes.
3. Execute mappers. Each one runs against the authenticated user and the client context, once for the access token and once for the ID token. The ID-token pass only happens when scope includes openid.
4. Filter by token type. access.token.claim and id.token.claim decide which token each claim lands in.
5. Strip reserved claims. The ten names above are removed.
6. Build and sign. Mapper output is merged with the standard claims and the JWT is signed with the realm’s signing key.

Adding a mapper