# 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.