App Role Mappings¶

Overview¶

App Role Mappings (also called App Mappings) are named key-value entries scoped to an application. They let you define per-user or per-group values that are automatically injected into OIDC claim mappings and SAML attribute mappings using the ${mapping_key} template syntax (where mapping_key is the Mapping Key you define for each entry).

This is useful for use cases such as:

Injecting AWS IAM role ARNs into SAML assertions
Assigning application-specific roles to groups
Providing per-user custom attributes to applications

Concepts¶

Application
    └── App Mapping (name="aws_role_arn", value="arn:aws:iam::123:role/Developers")
            ├── Assigned to: Group "Engineering"
            └── Assigned to: User "alice"

At authentication time, JustIAM resolves all App Mappings for the application that are assigned to the user (directly or via their groups). The resolved values are available as ${mapping_key} (using each entry's Mapping Key as the variable name) in claim/attribute templates, and also collectively via ${appRoles} (an array of all values).

Creating a mapping entry¶

UI: Administration → Applications → (select app) → App Mappings tab

API:

POST /api/v1/app-mappings
Authorization: Bearer <token>
Content-Type: application/json

{
  "application_id": "<app-uuid>",
  "variable_name": "aws_role_arn",
  "value": "arn:aws:iam::123456789012:role/Developers",
  "description": "Engineering team AWS developer role"
}

Assigning to users and groups¶

Once a mapping entry is created, assign it to users or groups:

# Assign to a group
POST /api/v1/groups/{groupId}/app-mappings
{ "mapping_id": "<mapping-uuid>" }

# Assign to a user
POST /api/v1/users/{userId}/app-mappings
{ "mapping_id": "<mapping-uuid>" }

Using in OIDC claim mappings¶

Reference a variable by name:

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

Or use ${appRoles} to get an array of all assigned mapping values:

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

Using in SAML attribute mappings¶

The multi-value ${role} template emits one AttributeValue per assigned mapping, which is required by AWS SAML SSO:

{
  "name": "https://aws.amazon.com/SAML/Attributes/Role",
  "value": "${role}",
  "format": "uri"
}

Listing mappings for an application¶

GET /api/v1/applications/{id}/app-mappings

Returns all mapping entries with their user and group assignments.

Multiple values for a user¶

A user can have multiple App Mapping entries for the same application (e.g., via different group memberships). All resolved values are available in ${appRoles} / ${role}.