Skip to main content

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. User Attribute Extension — Manages attribute definitions and user-specific attribute values with scoping, encryption, and retention policies
  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 Scopes​

Attribute definitions support four scope levels:

ScopeDescription
GLOBALApplies to all tenants in the realm
TENANTApplies only to a specific tenant
GLOBAL_TENANT_TYPEApplies to all tenants of a specific tenant type
TENANT_TYPEApplies to tenants matching a tenant type

When creating or updating an attribute definition, set the scope, tenantId, and tenantTypeId fields accordingly.

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 the schema for user attributes — type, validation, visibility, and security settings.

Create attribute definition
curl -X POST \
  "https://<KEYCLOAK_HOST>/admin/realms/<REALM>/attributes/attribute-definitions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "approvalStatus",
    "label": {
      "tr": "Onay Durumu",
      "en": "Approval Status"
    },
    "description": {
      "tr": "Kullanıcının sistemdeki onay durumu",
      "en": "User approval status in the system"
    },
    "type": "select",
    "required": false,
    "allowedValues": ["pending", "approved", "rejected"],
    "visibleInToken": true,
    "visibleInAdmin": true,
    "encryption": {
      "atRest": false,
      "inTransit": true
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "2e0b0ff2-6dda-4d2b-b992-2a7ac8633a4d",
    "code": "approvalStatus",
    "label": { "tr": "Onay Durumu", "en": "Approval Status" },
    "createdAt": "2024-05-10T12:34:56Z",
    "updatedAt": "2024-05-10T12:34:56Z"
  },
  "message": "Attribute definition created successfully."
}

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>/attributes/user-attributes/<USER_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionId": "2e0b0ff2-6dda-4d2b-b992-2a7ac8633a4d",
    "value": "approved",
    "status": "ACTIVE",
    "source": "ADMIN",
    "readonly": false,
    "scope": "TENANT",
    "tenantId": "acme-corp"
  }'

Response:

{
  "success": true,
  "data": {
    "attributeId": "55a876a2-4f95-4805-8a04-2d125f03ee4d",
    "userId": "5c9729d6-4918-409e-acb9-f37da9e4f954",
    "definitionId": "2e0b0ff2-6dda-4d2b-b992-2a7ac8633a4d",
    "value": "approved",
    "status": "ACTIVE",
    "source": "ADMIN",
    "scope": "TENANT",
    "tenantId": "acme-corp",
    "createdAt": "2024-09-22T09:49:53Z",
    "updatedAt": "2024-09-22T09:49:53Z"
  },
  "message": "User attribute created successfully."
}
User Attribute Scope Constraints

When scope is TENANT, the tenantId field is required. When scope is GLOBAL, the tenantId field must be null or omitted.

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 complete list of attribute definition fields including encryption, retention, and visibility options, see Attribute Definition Model.

Validation Scenario​

Scenario​

Create an attribute definition, assign it to a user, and verify the attribute appears in the user's token.

Expected Result​

The user's access token includes the custom attribute with the assigned value.

How to Verify​

  • API evidence: GET /admin/realms/{realm}/attributes/user-attributes/{userId} returns the attribute
  • Token evidence: Decode the access token and verify the attribute claim is present
  • Admin UI evidence: Navigate to the user's attribute list in the Admin Console

Troubleshooting​

  • 409 Conflict on attribute definition — The code value already exists. Use a unique code or update the existing definition.
  • 400 Bad Request on user attribute — Check that definitionId references a valid attribute definition and scope constraints are satisfied.
  • 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.

SCIM Provisioning

Automate user and attribute provisioning via SCIM

Directory Sync Jobs

Configure scheduled directory synchronization

Attribute Model Concepts

Understand attribute definitions and inheritance

Organization Model

Learn about organizations and tenant structure