86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# 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:
|
|
```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.
|