Keycloak (Admin REST API)

Este módulo permite a Anjana Data conectarse a un realm de Keycloak para descargar y sincronizar usuarios mediante la Admin REST API.

La sincronización obtiene todos los usuarios activos del realm configurado, incluyendo sus atributos estándar (username, email, firstName, lastName) y cualquier atributo personalizado (User Profile).

Parte 1: Configuración en Keycloak Admin Console

Para que Anjana pueda leer los usuarios, es necesario crear un cliente confidencial con una cuenta de servicio y asignarle los permisos de lectura adecuados.

Paso 1: Crear el cliente de aprovisionamiento

1. Acceda a la Admin Console de Keycloak y seleccione el realm del que desea sincronizar los usuarios.

2. Vaya a Clients > Create client.

3. Configure los campos básicos:

   • Client type: OpenID Connect

   • Client ID: Defina un nombre descriptivo, ej. anjana-provisioning

4. En la pantalla de Capability config:

   • Client authentication: ON (modo confidencial, necesario para obtener el secreto)

   • Service accounts roles: ON (habilita la cuenta de servicio para este cliente)

   • Authorization: OFF

5. Haga clic en Save.

6. En la pestaña Credentials, copie el Client Secret.

Paso 2: Asignar el rol view-users

La cuenta de servicio del cliente necesita el rol view-users del cliente interno realm-management.

1. Con el cliente recién creado abierto, vaya a la pestaña Service accounts roles.

2. Haga clic en Assign role.

3. En el desplegable de filtro, seleccione Filter by clients.

4. Busque realm-management y seleccione el rol view-users.

5. Haga clic en Assign.

Paso 3: Verificar el acceso

Puede verificar que las credenciales son correctas con la siguiente llamada:

# 1. Obtener token de acceso
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. Listar usuarios (debe devolver un array JSON)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://<keycloak-server>/admin/realms/<realm>/users?max=5"

Parte 2: Configuración en application.yml

Edite el archivo de configuración de Anjana e incluya los datos obtenidos en la sección security.provisioning.providers.keycloak.

security:
  provisioning:
    providers:
      keycloak:
        # Clave única para identificar este proveedor (puede ser cualquier nombre, ej: keycloak-corp)
        keycloak-corp:
          # URL base del servidor Keycloak (sin el realm)
          server-url: "https://sso.mi-dominio.com"
          # Nombre del realm del que se sincronizarán los usuarios
          realm: "mi-realm"
          # Client ID del cliente creado en el Paso 1
          client-id: "anjana-provisioning"
          # Client Secret obtenido en el Paso 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: "..."

Atributos sincronizados

Los siguientes campos se obtienen del endpoint GET /admin/realms/{realm}/users. Todos los atributos estándar y personalizados están disponibles para field-mapping.

Mapeo de campos personalizado (field-mapping)

Anjana incluye un mapeo por defecto que cubre los casos habituales. Puede sobreescribir cualquier campo indicando la clave del atributo Keycloak de la que debe leer el valor. Las claves son listas en orden de prioridad: se usa el primer valor no vacío.

Mapeo por defecto

Campos disponibles

Anjana expone tanto los campos raíz del usuario como todos los atributos personalizados aplanados como claves de primer nivel.

Ejemplo de configuración

security:
  provisioning:
    providers:
      keycloak:
        keycloak-corp:
          server-url: "https://sso.mi-dominio.com"
          realm: "mi-realm"
          client-id: "anjana-provisioning"
          client-secret: "..."
          field-mapping:
            # Usar email como userName si username está vacío
            user-name: ["username", "email"]
            # Leer teléfono del atributo 'mobile' o 'phoneNumber'
            phone: ["mobile", "phoneNumber"]
            # Cargo del atributo 'position' o 'title'
            title: ["position", "title"]

Resumen de datos requeridos