keycloak-attribute-endpoints-provider/README.md

Attribute Endpoints Provider

This is a Keycloak Provider that exports an anonymized list of user profile attribute values. For this it will provide API endpoints for every configured attribute-group. The configuration of the provider is possible via an admin page.

Every endpoint responds with a list of all attribute values, that:

• is in the attribute group matching attribute-group
• matches an optional RegEx Pattern attribute-regex
• belongs to a user with a role matching match-role
• is non-empty

Multivalue attributes are flattened in the response.

Example Setup

We assume an unconfigured, fresh Keycloak installation running under http://localhost:8080.

1. Add a new realm
   e.g. "TestRealm"
2. Under Realm Settings > User profile > Attributes Group, add a new attribute Group
   Example:
   • Name = "my-attributes-group"
   • Display name = "Endpoint Attributes"
   • Display description = "Attributes exported by the provider."
3. Under Realm Settings > User profile > Attributes, add a new attribute
   Example:
   • Attribute [Name] = "ssh-keys"
   • Display name = "SSH Keys"
   • Multivalued = On
   • Attribute group = "my-attributes-group"
   • Who can edit? = user, admin
   • Validators
     You can add validators, which will limit what values the user can enter. These validators are ignored by the provider.
4. Under Realm roles, add two new roles
   Example:
   1. Role name = "myattribute-match"
   2. Role name = "myattribute-export"
5. Under Users, add a new user
   Example:
   • Username = "user"
   • Email = "user@example.com"
   • First name = "User"
   • Last name = "User"
   • SSH Keys = "example-value-1", "example-value-2"
6. In the Settings of the newly created user, go to Role mapping > Assing role > Realm roles and check the role myattribute-match
7. create a second user to use the provider
   • Username = "bot-user"
   • Email = "bot@example.com"
   • First name = "Bot"
   • Last name = "Bot"
   • After creating:
     • give it the role myattribute-export
     • set a password in the users settings Creadentials > Set password. For Example "password"
8. Under 🪪 Attribute Endpoints 🚀 > Create item, add a new endpoint to the provider
   Example:
   • Slug = "ssh_keys"
   • Attribute Group = "my-attributes-group"
   • Match Role = "myattribute-match"
   • Auth Role = "myattribute-export"
   • Attribute RegEx = ".*"
9. Aquire an OIDC Access Token:

   curl --request POST \
       --url http://localhost:8080/realms/TestRealm/protocol/openid-connect/token \
       --header 'content-type: application/x-www-form-urlencoded' \
       --data scope=openid \
       --data username=bot-user \
       --data password=password \
       --data grant_type=password \
       --data client_id=admin-cli
   

10. copy the value of the response key access_token and use it in a second request:

    curl --request GET \
        --url http://localhost:8080/realms/TestRealm/attribute-endpoints-provider/export/ssh_keys \
        --header 'authorization: Bearer ey...' \
        --header 'content-type: application/json'
    

11. You should get a response like this:

    ["example-value-1","example-value-2"]
    

Although this example uses a simple bot account to authenticate to Keycloak, we recommend using a client with service account, when using this provider programmatically.