From 1381bf6b2ae10ce458d6ffd35a21643a6bc920fb Mon Sep 17 00:00:00 2001
From: kritzl <kritzl@kritzl.dev>
Date: Tue, 17 Feb 2026 16:16:48 +0100
Subject: [PATCH] update README

---
 README.md                                     | 106 +++++++++++++-----
 .../AttributeEndpointsResourceProvider.java   |   1 +
 2 files changed, 81 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 319bc1e..c58b329 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,86 @@
-What does this Keykloak Provider do?
+# Attribute Endpoints Provider
 
-Export an anonymized list of User-Attribute values.
-This provider will provide an api endpoit for every configured attribute-group.
-Multivalues attribues are not supported (yet).
+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
 
-Configuration in Keykloak
+We assume an unconfigured, fresh Keycloak installation running under `http://localhost:8080`.
 
-- Client with Service-Account
-  - Assigned roles allow access to attribute export
-- User profile Groups with attributes
+ 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"]
+    ```
 
-
-```json
-{
-    "endpoints": [
-        {
-            "slug": "myattribute",
-            "attribute-group": "myattributes",
-            "match-role": "myattribute-access",
-            "auth-role": "myattribute-export",
-            "attribute-regex": "^(?<key>(ssh-ed25519 AAAAC3NzaC1lZDI1NTE5|ssh-rsa AAAAB3NzaC1yc2)[0-9A-Za-z+/]+[=]{0,3})(\\s.*)?$",
-        }
-    ]
-}
-```
-
-
-
-We recommend using a client with service-account, but you can also use a bot-account to authenticate against the provider.
+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.
diff --git a/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProvider.java b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProvider.java
index f812639..33a9c1d 100644
--- a/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProvider.java
+++ b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProvider.java
@@ -134,6 +134,7 @@ public class AttributeEndpointsResourceProvider implements RealmResourceProvider
                             .toList();
                 })
                 .flatMap(List::stream)
+                // TODO: Ignore regex when empty
                 .map(attribute -> {
                     final Matcher matcher = attributeRegex.matcher(attribute);
                     return matcher.find() ? attribute : null;