Protocol Mappers

Protocol mappers are the rules that transform user and client data into JWT claims. Each mapper belongs to a client scope and runs during token generation. Aegis provides six built-in mapper types that cover the most common claim patterns.

Mapper Types

user_property

Maps a built-in user field directly to a token claim.

Example: Map the user’s email to the email claim:

{
  "property": "email",
  "claim_name": "email",
  "claim_type": "String",
  "add_to_id_token": true,
  "add_to_access_token": true
}

user_attribute

Maps a custom user attribute (key-value metadata) to a token claim. Use this for business-specific data like department, plan tier, or feature flags.

user_realm_role_mapper

Includes the user’s realm-level role names in the token.

Output example:

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

user_client_role_mapper

Includes the user’s client-specific role names. Useful when different clients have their own role hierarchies.

audience_mapper

Adds audience (aud) values to the token. Use this when your token needs to be accepted by multiple resource servers.

hardcoded_claim_mapper

Injects a static value as a claim. Useful for environment indicators, feature flags, or tenant identifiers that don’t come from user data.

Example: Add an environment indicator:

{
  "claim_name": "environment",
  "claim_value": "production",
  "claim_type": "String",
  "add_to_id_token": false,
  "add_to_access_token": true
}

Execution Order

Protocol mappers execute in the order they appear within their scope. When multiple scopes are active, mappers from each scope run in scope order.

Token Generation Pipeline

When a token is generated, Aegis follows this pipeline:

1. Resolve scopes — Collect all default scopes for the client, plus any optional scopes requested in the scope parameter
2. Gather mappers — Collect all protocol mappers from the active scopes
3. Execute mappers — Run each mapper against the authenticated user and client context
4. Build payload — Merge mapper outputs with standard claims (sub, iss, exp, etc.)
5. Filter by token type — Include only claims marked for the target token type (access token vs ID token)
6. Sign — Sign the JWT with the realm’s signing key

Creating Custom Mappers

To add a custom claim to your tokens: