Keycloak (Admin REST API)

This module allows Anjana Data to connect to a Keycloak realm to download and synchronize users via the Admin REST API.

The synchronization retrieves all active users from the configured realm, including their standard attributes (username, email, firstName, lastName) and any custom attributes (User Profile).

Part 1: Configuration in Keycloak Admin Console

For Anjana to be able to read users, you need to create a confidential client with a service account and assign it the appropriate read permissions.

Step 1: Create the provisioning client

1. Access the Keycloak Admin Console and select the realm from which you want to synchronize users.

2. Go to Clients > Create client.

3. Configure the basic fields:

   • Client type: OpenID Connect

   • Client ID: Set a descriptive name, e.g. anjana-provisioning

4. On the Capability config screen:

   • Client authentication: ON (confidential mode, required to obtain the secret)

   • Service accounts roles: ON (enables the service account for this client)

   • Authorization: OFF

5. Click Save.

6. On the Credentials tab, copy the Client Secret.

Step 2: Assign the view-users role

The client's service account needs the view-users role from the internal realm-management client.

1. With the newly created client open, go to the Service accounts roles tab.

2. Click Assign role.

3. In the filter dropdown, select Filter by clients.

4. Search for realm-management and select the view-users role.

5. Click Assign.

Step 3: Verify access

You can verify that the credentials are correct with the following call:

# 1. Get access token
TOKEN=$(curl -s -X POST \
  "https://<keycloak-server>/realms/<realm>/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=anjana-provisioning" \
  -d "client_secret=<client-secret>" | jq -r '.access_token')

# 2. List users (should return a JSON array)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://<keycloak-server>/admin/realms/<realm>/users?max=5"

Part 2: Configuration in application.yml

Edit the Anjana configuration file and include the data obtained in the security.provisioning.providers.keycloak section.

security:
  provisioning:
    providers:
      keycloak:
        # Unique key to identify this provider (can be any name, e.g: keycloak-corp)
        keycloak-corp:
          # Base URL of the Keycloak server (without the realm)
          server-url: "https://sso.mi-dominio.com"
          # Name of the realm from which users will be synchronized
          realm: "mi-realm"
          # Client ID of the client created in Step 1
          client-id: "anjana-provisioning"
          # Client Secret obtained in Step 1
          client-secret: "${KEYCLOAK_PROVISIONING_SECRET}"

keycloak:
  keycloak-corp:
    server-url: "https://sso.mi-dominio.com"
    realm: "corp"
    client-id: "anjana-provisioning"
    client-secret: "..."
  keycloak-partners:
    server-url: "https://sso.mi-dominio.com"
    realm: "partners"
    client-id: "anjana-provisioning"
    client-secret: "..."

Synchronized attributes

The following fields are obtained from the GET /admin/realms/{realm}/users endpoint. All standard and custom attributes are available for field-mapping.

Custom field mapping (field-mapping)

Anjana includes a default mapping that covers common cases. You can override any field by specifying the Keycloak attribute key from which the value should be read. The keys are listed in priority order: the first non-empty value is used.

Default mapping

Available fields

Anjana exposes both the user's root fields and all custom attributes flattened as top-level keys.

Configuration example

security:
  provisioning:
    providers:
      keycloak:
        keycloak-corp:
          server-url: "https://sso.mi-dominio.com"
          realm: "mi-realm"
          client-id: "anjana-provisioning"
          client-secret: "..."
          field-mapping:
            # Use email as userName if username is empty
            user-name: ["username", "email"]
            # Read phone from the 'mobile' or 'phoneNumber' attribute
            phone: ["mobile", "phoneNumber"]
            # Job title from the 'position' or 'title' attribute
            title: ["position", "title"]

Summary of required data