Attribute & Role Mappers

Goal

Configure attribute definitions and user attribute mapping, and assign roles to organizations using Keymate's Keycloak extensions. This guide covers both attribute-based and role-based mapping strategies for identity federation.

Audience

• Platform engineers setting up identity federation
• Developers integrating attribute and role mapping into applications

Prerequisites

• Keycloak instance with Keymate extensions deployed
• Admin access to the target realm
• Valid bearer token for API authentication

Before You Start

Keymate extends Keycloak with two extensions for mapping:

1. KEOPS Attribute API — Manages definitions, applicability policy inputs, and direct values; unsupported per-definition encryption, masking, retention, and automatic inheritance must not be inferred from this API
2. Organizations Extension — Handles organization-to-role and organization-to-group mappings

Both extensions expose REST APIs under the realm admin path (/admin/realms/{realm}/).

Attribute ownership and applicability

Definitions carry a governance owner (ownerScopeType and ownerRef) and a separate subjectType. Direct values carry their own value owner. Applicability records are independent policy inputs; the absence of a matching record means direct-only/no-inheritance. See Attribute Definition Model.

Worked Example

This guide demonstrates:

1. Creating an attribute definition for user approval status
2. Assigning the attribute to a user
3. Mapping roles to an organization

Steps

1. Create an Attribute Definition

Attribute definitions describe schema and policy metadata. key is semantic; the created id is the stable identity used by value records. tokenVisible is eligibility, not automatic release.

Create attribute definition

curl -X POST \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/keops/v1/attributes/definitions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "approvalStatus",
    "displayName": "Approval status",
    "ownerScopeType": "tenant",
    "ownerRef": "acme-corp",
    "subjectType": "user",
    "type": "custom",
    "projectionTarget": "keycloak_user_profile_managed_attribute",
    "editability": "admin_editable",
    "valueType": "string",
    "multivalued": false,
    "sensitivity": "internal",
    "tokenVisible": false
  }'

Selected response fields:

{
  "id": "2e0b0ff2-6dda-4d2b-b992-2a7ac8633a4d",
  "key": "approvalStatus",
  "displayName": "Approval status",
  "ownerScopeType": "tenant",
  "ownerRef": "acme-corp",
  "subjectType": "user",
  "valueType": "string",
  "tokenVisible": false
}

2. Assign an Attribute to a User

After creating a definition, assign values to individual users.

Assign user attribute

curl -X POST \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/keops/v1/attributes/values" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionId": "2e0b0ff2-6dda-4d2b-b992-2a7ac8633a4d",
    "ownerScopeType": "user",
    "ownerRef": "<USER_ID>",
    "value": "approved"
  }'

Selected response fields:

{
  "id": "55a876a2-4f95-4805-8a04-2d125f03ee4d",
  "definitionId": "2e0b0ff2-6dda-4d2b-b992-2a7ac8633a4d",
  "ownerScopeType": "user",
  "ownerRef": "<USER_ID>",
  "value": "approved"
}

Direct-value boundary

This creates a direct value for one explicit owner. It does not prove inheritance, precedence, provenance, conflict resolution, or an effective-value result.

Organization Terminology

In the Keycloak API paths below, organizations refers to Keymate Organizations — hierarchical units within a Tenant. For details on the organization hierarchy, see Organization Model.

3. List Organization Roles

View roles currently assigned to an organization.

List organization roles

curl -X GET \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/keymate/organizations/<ORG_ID>/roles?offset=0&count=50" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Use isGlobal=true to filter for realm-level roles only.

4. Add a Role to an Organization

Assign an existing role to an organization.

Add role to organization

curl -X POST \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/keymate/organizations/<ORG_ID>/roles" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "roleId": "<ROLE_ID>"
  }'

5. Create and Assign a Role in One Step

Create a new realm role and assign it to the organization simultaneously.

Create organization role

curl -X POST \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/keymate/organizations/<ORG_ID>/roles/create" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "document-editor",
    "description": "Can edit organization documents"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "7a3c9e12-8f4b-4d6a-b123-9e8f7a6b5c4d",
    "name": "document-editor",
    "description": "Can edit organization documents",
    "organizationId": "<ORG_ID>"
  },
  "message": "Role created and assigned successfully."
}

6. Remove a Role from an Organization

Remove role from organization

curl -X DELETE \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/keymate/organizations/<ORG_ID>/roles/<ROLE_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Attribute Definition Reference

For the evidence-backed definition contract, unsupported claims, and token eligibility boundary, see Attribute Definition Model.

Validation Scenario

Scenario

Create an attribute definition and direct user value, then verify direct storage independently from token projection.

Expected Result

The direct-value API returns the stored value for the explicit user owner. A token claim is expected only when every projection gate described in Identity Attributes and Claims is satisfied.

How to Verify

• API evidence: GET /admin/realms/{realm}/keops/v1/attributes/values?ownerScopeType=USER&ownerRef={userId} returns the direct value
• Token evidence: If projection is intentionally configured, decode the allowed token surface and verify the governed claim; absence is correct when any gate is closed
• Admin UI evidence: Navigate to the user's attribute list in the Admin Console

Troubleshooting

• 409 Conflict on attribute definition — The key value already exists within its governed uniqueness boundary. Use the stable returned id to address the existing definition.
• 400 Bad Request on user attribute — Check that definitionId references a valid attribute definition and the value owner fields are valid.
• 404 Not Found on role assignment — Verify the role ID exists in the realm before assigning to an organization.

Next Steps

After configuring attribute and role mappers, proceed to set up Directory Sync Jobs to automate attribute population from external identity sources.

Related Docs

SCIM Provisioning

Automate user and attribute provisioning via SCIM

Directory Sync Jobs

Configure scheduled directory synchronization

Attribute Model Concepts

Understand definitions, direct values, resolution, and projection gates

Organization Model

Learn about organizations and tenant structure