Claim Mappings¶

Overview¶

Claim mappings add custom claims to the OIDC ID token and access token issued by JustIAM. They are configured per application.

Adding claim mappings¶

UI: Administration → Applications → (select app) → Claim Mappings section

API: Include claim_mappings in the application create or update payload:

PUT /api/v1/applications/{id}
{
  "claim_mappings": [
    { "claim": "department", "value": "Engineering" },
    { "claim": "email_alias", "value": "${email}" },
    { "claim": "full_name", "value": "${name}" },
    { "claim": "groups", "value": "${groups}" },
    { "claim": "app_roles", "value": "${appRoles}", "required_scope": "roles" }
  ]
}

Claim mapping fields¶

Field	Required	Description
`claim`	Yes	The JWT claim name added to the token
`value`	Yes	Template or literal value (see below)
`required_scope`	No	Only emit this claim when this scope was granted in the authorization request

Template variables¶

Variable	Resolves to
`${email}`	User's email address
`${username}`	User's username
`${first_name}`	First name
`${last_name}`	Last name
`${name}`	Full name (`first last`)
`${id}`	User UUID
`${groups}`	Array of all group names the user belongs to
`${appRoles}`	Array of all app role mapping values assigned to the user for this application
`${mapping_key}`	Value from an App Mapping whose Mapping Key is `mapping_key`, assigned to this user or their groups
(anything else)	Included as a literal string

`required_scope`¶

The required_scope field restricts a claim to only be emitted when a specific scope was requested (and granted) by the client.

Example: emit app_roles only when the roles scope is requested:

{
  "claim": "app_roles",
  "value": "${appRoles}",
  "required_scope": "roles"
}

If the client requests scope=openid profile email (without roles), the app_roles claim is omitted. If the client requests scope=openid profile email roles, the claim is included.

Make sure to add the custom scope to the application's allowed_scopes list.

Array claims¶

${groups} and ${appRoles} resolve to JSON arrays, for example:

{
  "groups": ["Engineering", "Platform"],
  "app_roles": ["admin", "deployer"]
}

App Mapping keys¶

App Mappings (see App Role Mappings) define named per-user / per-group values. The Mapping Key of each entry becomes the template variable name. Once assigned, they can be referenced in claim mappings using ${mapping_key}.

For example, if an App Mapping named aws_role_arn is assigned to a user with value arn:aws:iam::123456789012:role/Developers, you can emit it as:

{ "claim": "aws_role", "value": "${aws_role_arn}" }