diff --git a/README.md b/README.md new file mode 100644 index 0000000..4697503 --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +# 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: +- 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 + +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. diff --git a/ssh-key-provider/.gitignore b/attribute-endpoints-provider/.gitignore similarity index 100% rename from ssh-key-provider/.gitignore rename to attribute-endpoints-provider/.gitignore diff --git a/ssh-key-provider/pom.xml b/attribute-endpoints-provider/pom.xml similarity index 95% rename from ssh-key-provider/pom.xml rename to attribute-endpoints-provider/pom.xml index 90651ca..7769188 100644 --- a/ssh-key-provider/pom.xml +++ b/attribute-endpoints-provider/pom.xml @@ -5,11 +5,11 @@ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 - de.ccc.hamburg.keycloak.ssh_key - ssh-key-provider + de.ccc.hamburg.keycloak.attribute_endpoints + attribute-endpoints-provider 1.0-SNAPSHOT - ssh-key-provider + attribute-endpoints-provider http://www.example.com diff --git a/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AdminUiPage.java b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AdminUiPage.java new file mode 100644 index 0000000..cfd26b6 --- /dev/null +++ b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AdminUiPage.java @@ -0,0 +1,153 @@ +package de.ccc.hamburg.keycloak.attribute_endpoints; + +import java.util.List; +import java.util.regex.Pattern; + +import org.keycloak.Config; +import org.keycloak.component.ComponentModel; +import org.keycloak.component.ComponentValidationException; +import org.keycloak.models.KeycloakSession; +import org.keycloak.models.KeycloakSessionFactory; +import org.keycloak.models.RealmModel; +import org.keycloak.models.RoleModel; +import org.keycloak.provider.ProviderConfigProperty; +import org.keycloak.provider.ProviderConfigurationBuilder; +import org.keycloak.representations.userprofile.config.UPConfig; +import org.keycloak.services.ui.extend.UiPageProvider; +import org.keycloak.services.ui.extend.UiPageProviderFactory; +import org.keycloak.userprofile.UserProfileProvider; + +import com.google.auto.service.AutoService; + +/** + * Implements UiPageProvider to show a config page in the admin + */ +@AutoService(UiPageProviderFactory.class) +public class AdminUiPage implements UiPageProvider, UiPageProviderFactory { + public static final String PROVIDER_ID = "Attribute Endpoints"; + + @Override + public void init(Config.Scope config) { + } + + @Override + public void postInit(KeycloakSessionFactory factory) { + } + + @Override + public void close() { + } + + @Override + public String getId() { + return PROVIDER_ID; + } + + public String getHelpText() { + return "Configure endpoints of the Attribute Endpoint Provider."; + } + + @Override + public void validateConfiguration(KeycloakSession session, RealmModel realm, ComponentModel model) { + String errorString = "\n"; + Boolean hasError = false; + + Pattern slugPattern = Pattern.compile("^[a-zA-Z0-9_-]*$"); + String configAttributeSlug = model.getConfig().getFirst("slug"); + if (configAttributeSlug == null) { + hasError = true; + errorString += " • [Slug] can not be empty\n"; + } else if (!slugPattern.matcher(configAttributeSlug).matches()) { + hasError = true; + errorString += " • [Slug] can only contain anlphanumeric characters, dash and underscore (a-z A-Z 0-9 _ - )\n"; + } + + String configAuthRole = model.getConfig().getFirst("auth-role"); + if (configAuthRole == null) { + hasError = true; + errorString += " • [Auth Role] can not be empty\n"; + } else if (realm.getRole(configAuthRole) == null) { + hasError = true; + errorString += " • [Auth Role] does not exist\n"; + } + + String configMatchRole = model.getConfig().getFirst("match-role"); + if (configMatchRole == null) { + hasError = true; + errorString += " • [Match Role] can not be empty\n"; + } else if (realm.getRole(configMatchRole) == null) { + hasError = true; + errorString += " • [Match Role] does not exist\n"; + } + + UserProfileProvider profileProvider = session.getProvider(UserProfileProvider.class); + UPConfig upconfig = profileProvider.getConfiguration(); + String configAttributeGroup = model.getConfig().getFirst("attribute-group"); + if (configAttributeGroup == null) { + hasError = true; + errorString += " • [Attribute Group] can not be empty\n"; + } else if (!upconfig.getGroups().stream().anyMatch(g -> g.getName().equals(configAttributeGroup))) { + hasError = true; + errorString += " • [Attribute Group] does not exist\n"; + } + + String configAttributeRegex = model.getConfig().getFirst("attribute-regex"); + Boolean regexIsBlank = configAttributeRegex == null; + + if (!regexIsBlank) { + try { + Pattern.compile(configAttributeRegex); + } catch (Exception e) { + hasError = true; + errorString += " • [Attribute RegEx] is not a valid regex pattern\n"; + } + } + + if (hasError) { + throw new ComponentValidationException(errorString); + } + } + + @Override + public List getConfigProperties() { + return ProviderConfigurationBuilder.create() + .property() + .name("slug") + .label("Slug") + .helpText( + "The slug in the path of the API endpoint (e.g. /realms/:realm/attribute-endpoint-provider/export/:slug)") + .type(ProviderConfigProperty.STRING_TYPE) + .add() + + .property() + .name("attribute-group") + .label("Attribute Group") + .helpText("The attribute group to export.") + .type(ProviderConfigProperty.STRING_TYPE) + .add() + + .property() + .name("match-role") + .label("Match Role") + .helpText("Export only attributes of users with this role.") + .type(ProviderConfigProperty.STRING_TYPE) + .add() + + .property() + .name("auth-role") + .label("Auth Role") + .helpText("Role needeed by the authenticated account to be able to use this endpoint.") + .type(ProviderConfigProperty.STRING_TYPE) + .add() + + .property() + .name("attribute-regex") + .label("Attribute RegEx") + .helpText("A RegEx Rule used to verify each attribute value. Only matching values are returned.") + .type(ProviderConfigProperty.STRING_TYPE) + .add() + + .build(); + } + +} 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 new file mode 100644 index 0000000..8c17ec3 --- /dev/null +++ b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProvider.java @@ -0,0 +1,160 @@ +package de.ccc.hamburg.keycloak.attribute_endpoints; + +import java.util.Collection; +import java.util.List; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Stream; + +import org.jboss.logging.Logger; +import org.keycloak.component.ComponentModel; +import org.keycloak.models.ClientModel; +import org.keycloak.models.KeycloakContext; +import org.keycloak.models.KeycloakSession; +import org.keycloak.models.RealmModel; +import org.keycloak.models.RoleModel; +import org.keycloak.models.UserModel; +import org.keycloak.models.UserProvider; +import org.keycloak.representations.userprofile.config.UPConfig; +import org.keycloak.services.managers.AppAuthManager; +import org.keycloak.services.managers.Auth; +import org.keycloak.services.managers.AuthenticationManager.AuthResult; +import org.keycloak.services.resource.RealmResourceProvider; +import org.keycloak.userprofile.UserProfileProvider; + +import jakarta.ws.rs.ForbiddenException; +import jakarta.ws.rs.GET; +import jakarta.ws.rs.NotAuthorizedException; +import jakarta.ws.rs.NotFoundException; +import jakarta.ws.rs.Path; +import jakarta.ws.rs.PathParam; +import jakarta.ws.rs.Produces; +import jakarta.ws.rs.ServerErrorException; +import jakarta.ws.rs.core.MediaType; +import jakarta.ws.rs.core.Response; + +public class AttributeEndpointsResourceProvider implements RealmResourceProvider { + private static final Logger LOG = Logger.getLogger(AttributeEndpointsResourceProvider.class); + private final KeycloakSession session; + + public AttributeEndpointsResourceProvider(KeycloakSession keycloakSession) { + this.session = keycloakSession; + } + + @Override + public Object getResource() { + return this; + } + + @Override + public void close() { + } + + @GET + @Path("export/{slug}") + @Produces(MediaType.APPLICATION_JSON) + public Response exportAttributeValues(@PathParam("slug") String slug) { + KeycloakContext context = session.getContext(); + RealmModel realm = context.getRealm(); + + List componentList = realm.getComponentsStream() + .filter(c -> c.getProviderId().equals(AdminUiPage.PROVIDER_ID)) + .filter(c -> c.getConfig().getFirst("slug").equals(slug)) + .toList(); + + Auth auth = AttributeEndpointsResourceProvider.getAuth(session); + + if (componentList.isEmpty()) { + throw new NotFoundException("Endpoint not found."); + } + + if (componentList.size() > 1) { + throw new NotFoundException( + "Endpoint Configuration Error - Multiple configurations exist for this endpoint."); + } + + ComponentModel component = componentList.get(0); + + String configAuthRole = component.getConfig().getFirst("auth-role"); + RoleModel authRole = realm.getRole(configAuthRole); + if (authRole == null) { + throw new ServerErrorException("Endpoint Configuration Error - auth-role does not exist.", 500); + } + + String configMatchRole = component.getConfig().getFirst("match-role"); + RoleModel matchRole = realm.getRole(configMatchRole); + if (matchRole == null) { + throw new ServerErrorException("Endpoint Configuration Error - match-role does not exist.", 500); + } + + UserProfileProvider profileProvider = session.getProvider(UserProfileProvider.class); + UPConfig upconfig = profileProvider.getConfiguration(); + String configAttributeGroup = component.getConfig().getFirst("attribute-group"); + if (!upconfig.getGroups().stream().anyMatch(g -> g.getName().equals(configAttributeGroup))) { + throw new ServerErrorException("Endpoint Configuration Error - attribute-group does not exist.", 500); + } + + String configAttributeRegex = component.getConfig().getFirst("attribute-regex"); + Boolean regexIsBlank = configAttributeRegex == null; + + if (!regexIsBlank) { + try { + Pattern.compile(configAttributeRegex); + } catch (Exception e) { + throw new ServerErrorException( + "Endpoint Configuration Error - attribute-regex is not a valid regex pattern.", 500); + } + } + + UserModel authUser = auth.getUser(); + if (!authUser.hasRole(authRole)) { + throw new ForbiddenException("User does not have required auth role."); + } + + List attributeNames = upconfig.getAttributes() + .stream() + .filter(a -> a.getGroup() != null && a.getGroup().equals(configAttributeGroup)) + .map(a -> a.getName()) + .toList(); + + UserProvider userProvider = session.users(); + Stream users = userProvider.getRoleMembersStream(realm, matchRole); + + List attribute_list = users + .map(user -> { + Stream attributeStream = attributeNames.stream() + .map(attributeName -> user.getAttributeStream(attributeName).toList()) + .flatMap(Collection::stream); + + return attributeStream + .filter(attribute -> !attribute.isEmpty()) + .toList(); + }) + .flatMap(List::stream) + .filter(attribute -> { + if (regexIsBlank) { + return true; + } + final Pattern pattern = Pattern.compile(configAttributeRegex); + final Matcher matcher = pattern.matcher(attribute); + return matcher.find(); + }) + .toList(); + + return Response.ok(attribute_list).build(); + + } + + private static Auth getAuth(KeycloakSession session) { + AuthResult auth = new AppAuthManager.BearerTokenAuthenticator(session).authenticate(); + + if (auth == null) { + throw new NotAuthorizedException("Bearer"); + } + + RealmModel realm = session.getContext().getRealm(); + ClientModel client = auth.getClient(); + return new Auth(realm, auth.getToken(), auth.getUser(), client, auth.getSession(), false); + } + +} diff --git a/ssh-key-provider/src/main/java/de/ccc/hamburg/keycloak/ssh_key/SSHKeyResourceProviderFactory.java b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProviderFactory.java similarity index 66% rename from ssh-key-provider/src/main/java/de/ccc/hamburg/keycloak/ssh_key/SSHKeyResourceProviderFactory.java rename to attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProviderFactory.java index d5ac583..e4dc476 100644 --- a/ssh-key-provider/src/main/java/de/ccc/hamburg/keycloak/ssh_key/SSHKeyResourceProviderFactory.java +++ b/attribute-endpoints-provider/src/main/java/de/ccc/hamburg/keycloak/attribute_endpoints/AttributeEndpointsResourceProviderFactory.java @@ -1,4 +1,4 @@ -package de.ccc.hamburg.keycloak.ssh_key; +package de.ccc.hamburg.keycloak.attribute_endpoints; import org.keycloak.Config; import org.keycloak.models.KeycloakSession; @@ -9,16 +9,16 @@ import org.keycloak.services.resource.RealmResourceProviderFactory; import com.google.auto.service.AutoService; @AutoService(RealmResourceProviderFactory.class) -public class SSHKeyResourceProviderFactory implements RealmResourceProviderFactory { - static final String PROVIDER_ID = "ssh-key-provider"; +public class AttributeEndpointsResourceProviderFactory implements RealmResourceProviderFactory { + static final String PROVIDER_ID = "attribute-endpoints-provider"; @Override public RealmResourceProvider create(KeycloakSession keycloakSession) { - return new SSHKeyResourceProvider(keycloakSession); + return new AttributeEndpointsResourceProvider(keycloakSession); } @Override - public void init(Config.Scope scope) { + public void init(Config.Scope config) { } @Override diff --git a/ssh-key-provider/src/test/java/de/ccc/hamburg/keycloak/AppTest.java b/attribute-endpoints-provider/src/test/java/de/ccc/hamburg/keycloak/AppTest.java similarity index 100% rename from ssh-key-provider/src/test/java/de/ccc/hamburg/keycloak/AppTest.java rename to attribute-endpoints-provider/src/test/java/de/ccc/hamburg/keycloak/AppTest.java diff --git a/compose.yaml b/compose.yaml index da8b72e..6acf6dc 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,8 +1,8 @@ services: keycloak: - image: quay.io/keycloak/keycloak:26.4.2 + image: quay.io/keycloak/keycloak:26.5.3 pull_policy: always - command: start-dev + command: "start-dev --features=declarative-ui" environment: KEYCLOAK_ADMIN: admin KEYCLOAK_ADMIN_PASSWORD: admin @@ -10,4 +10,4 @@ services: ports: - "8080:8080" volumes: - - ./ssh-key-provider/target/ssh-key-provider-1.0-SNAPSHOT.jar:/opt/keycloak/providers/ssh-key-provider.jar \ No newline at end of file + - ./attribute-endpoints-provider/target/attribute-endpoints-provider-1.0-SNAPSHOT.jar:/opt/keycloak/providers/attribute-endpoints-provider.jar \ No newline at end of file diff --git a/ssh-key-provider/src/main/java/de/ccc/hamburg/keycloak/ssh_key/SSHKeyResourceProvider.java b/ssh-key-provider/src/main/java/de/ccc/hamburg/keycloak/ssh_key/SSHKeyResourceProvider.java deleted file mode 100644 index fd91f34..0000000 --- a/ssh-key-provider/src/main/java/de/ccc/hamburg/keycloak/ssh_key/SSHKeyResourceProvider.java +++ /dev/null @@ -1,117 +0,0 @@ -package de.ccc.hamburg.keycloak.ssh_key; - -import java.util.List; -import java.util.Map; -import java.util.Objects; -import java.util.regex.Matcher; -import java.util.regex.Pattern; -import java.util.stream.Stream; - -import org.jboss.logging.Logger; -import org.keycloak.models.ClientModel; -import org.keycloak.models.GroupModel; -import org.keycloak.models.KeycloakSession; -import org.keycloak.models.RealmModel; -import org.keycloak.models.UserModel; -import org.keycloak.models.UserProvider; -import org.keycloak.representations.userprofile.config.UPConfig; -import org.keycloak.services.managers.AppAuthManager; -import org.keycloak.services.managers.AppAuthManager.BearerTokenAuthenticator; -import org.keycloak.services.managers.Auth; -import org.keycloak.services.managers.AuthenticationManager.AuthResult; -import org.keycloak.services.resource.RealmResourceProvider; -import org.keycloak.userprofile.UserProfileProvider; - -import jakarta.ws.rs.ForbiddenException; -import jakarta.ws.rs.GET; -import jakarta.ws.rs.NotAuthorizedException; -import jakarta.ws.rs.Path; -import jakarta.ws.rs.PathParam; -import jakarta.ws.rs.Produces; -import jakarta.ws.rs.core.MediaType; -import jakarta.ws.rs.core.Response; - -public class SSHKeyResourceProvider implements RealmResourceProvider { - private static final Logger LOG = Logger.getLogger(SSHKeyResourceProvider.class); - private final KeycloakSession session; - - // taken from: https://github.com/nemchik/ssh-key-regex - private static final Pattern SSH_PUBLIC_KEY = Pattern.compile( - "^(?(ssh-dss AAAAB3NzaC1kc3|ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNT|ecdsa-sha2-nistp384 AAAAE2VjZHNhLXNoYTItbmlzdHAzOD|ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbmlzdHA1Mj|sk-ecdsa-sha2-nistp256@openssh.com AAAAInNrLWVjZHNhLXNoYTItbmlzdHAyNTZAb3BlbnNzaC5jb2|ssh-ed25519 AAAAC3NzaC1lZDI1NTE5|sk-ssh-ed25519@openssh.com AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29t|ssh-rsa AAAAB3NzaC1yc2)[0-9A-Za-z+/]+[=]{0,3})(\\s.*)?$"); - - public SSHKeyResourceProvider(KeycloakSession keycloakSession) { - this.session = keycloakSession; - } - - @Override - public Object getResource() { - return this; - } - - @Override - public void close() { - } - - @GET - @Path("export/{group_id}") - @Produces(MediaType.APPLICATION_JSON) - public Response exportKeys(@PathParam("group_id") String groupId) { - try { - SSHKeyResourceProvider.getAuth(session); - } catch (Exception e) { - System.err.println(e); - return Response.status(401, e.getMessage()).build(); - } - - UserProvider userProvider = session.users(); - UserProfileProvider profileProvider = session.getProvider(UserProfileProvider.class); - UPConfig upconfig = profileProvider.getConfiguration(); - List attributeNames = upconfig.getAttributes() - .stream() - .filter(a -> a.getGroup() != null && a.getGroup().equals("de.ccc.hamburg.keycloak.ssh_key.keys")) - .map(a -> a.getName()) - .toList(); - - RealmModel realm = session.getContext().getRealm(); - - // TODO: add allowlist check - GroupModel group = realm.getGroupById(groupId); - - Stream users = userProvider.getGroupMembersStream(realm, group); - - List keys = users - .map(user -> { - return attributeNames - .stream() - .map(attributeName -> user.getAttributeStream(attributeName).findFirst()) - .filter(attribute -> attribute.isPresent()) - .map(attribute -> attribute.get()) - .toList(); - }) - .flatMap(List::stream) - .map(key -> { - final Matcher matcher = SSH_PUBLIC_KEY.matcher(key); - return matcher.find() ? matcher.group("key") : null; - }) - .filter(Objects::nonNull) - .toList(); - - return Response.ok(Map.of("keys", keys)).build(); - - } - - private static Auth getAuth(KeycloakSession session) { - AuthResult auth = new AppAuthManager.BearerTokenAuthenticator(session).authenticate(); - - if (auth == null) { - throw new NotAuthorizedException("Bearer"); - } else if (!auth.getToken().getIssuedFor().equals("admin-cli")) { - throw new ForbiddenException(); - } - - RealmModel realm = session.getContext().getRealm(); - ClientModel client = auth.getClient(); - return new Auth(realm, auth.getToken(), auth.getUser(), client, auth.getSession(), false); - } - -}