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.

Building

Maven is required for building the provider.

Once all dependencies are met, simply call make to build the provider, which should then produce a attribute-endpoints-provider-1.0-SNAPSHOT.jar in the attribute-endpoints-provider/target/ directory.

There's also make clean available for removing the output directory.

Example Setup

We assume an unconfigured, fresh Keycloak installation running under http://localhost:8080.
(This can be achieved by running the provided compose.yaml after building the provider as outlined in Building.)

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.