CCCHH/keycloak-attribute-endpoints-provider
0
0
Fork 0
Code Issues 5 Pull requests 5 Projects Releases Packages Activity Actions

Add exporting individual attributes
All checks were successful
/ Verify (pull_request) Successful in 41s
Details

Browse source 
Based off #32

Also:
* rework README.md
* improve configuration error messages
This commit is contained in:
Stefan Bethke 2026-07-19 13:37:07 +02:00
commit c9f36f7100
6 changed files with 120 additions and 144 deletions
Download patch file Download diff file Expand all files Collapse all files

117
README.md
View file

@ -1,16 +1,38 @@
# Attribute Endpoints Provider
# Attribute Endpoints Provider - Export User Attributes
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.
This is a Keycloak Provider that exports user profile attribute values.
The selection of attributes and authorization is manage through an endpoint configuration.
Every endpoint responds with a list of all attribute values, that:
- are in the attribute group matching `attribute-group`
- match an optional RegEx Pattern `attribute-regex`
- belong to a user with a role matching `match-role`
- are non-empty
## Usage
The provider adds an object type "Attribute Endpoints" to the Keycloak admin website.
You configure the provider by creating one or more endpoint configurations.
Each endpoint configuration requires:
- a name that is the reference in the endpoint URL (slug)
- the name of a role that the calling user must have to be allowed to query this endpoint
- the name of an attribute or an attribute group that should be exported
- the name of a role that users must have to be included in the list
- an optional regular expression that must match to have a value included
> **Note** The attribute (group) and the roles need to exist before you can create the endpoint configuration.
There are two endpoints returning JSON:
- `export/slug`: collate all attribute values into a single list
- `export/slug/map`: produce a map of lists, with the key being the attribute name
No other data is included in the response, in particular, there is no information on which attribute value is associated with which user.
User Attribute values can be single or multi-value; the resulting list will include them as a flattened list.
> **⚠️ Note** The authorization and the selection of the user attributes are not tied together in any way.
> Every user that has the matching role will have all the attributes included that are specified in the endpoint configuration.
> In other words, if you are exporting an attribute group, all attributes will be included.
> **⚠️ Note** Keycloak has no concept of authorization for individual user attributes (for example, based on assigned roles).
> Users will be able to see and edit any attribute that has been made available to users, irrespective of whether a user would
> be included in an endpoint configuration export or not.
Multivalue attributes are flattened in the response.
## Building
@ -20,79 +42,8 @@ Once all dependencies are met, simply call `make` to build the provider, which s
There's also `make clean` available for removing the output directory.
To add the provider to your Keycloak install, copy `attribute-endpoints-provider/target/attribute-endpoints-provider-1.0-SNAPSHOT.jar` to the Keycloak Provider directory (`/opt/keycloak/providers/`).
## Testing Setup
See [testing/README.md](testing/README.md) for details on the Docker Compose based setup that includes a realm and the ability to attach a debugger to the running Keycloak.
## 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](#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:
```shell
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:
```shell
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:
```json
["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.