feat: ensure required hawk-client user-claims are present

Author: Neunerlei

.gitignore

@@ -10,3 +10,4 @@
 
 .maven/*
 target/*
+!target/.gitignore

README.md

@@ -16,14 +16,17 @@ To install the extension download the latest release from the [releases page](ht
 After the installation of the extension you need to restart the keycloak server.
 With the restart the extension will create a bunch of new roles you need to assign to your clients.
 To make your life easier, we have created a new role `hawk-client` that combines all the roles needed to access the new endpoints.
-
-Create a new client, or use an existing one, and assign the `hawk-client` role to the "Service account roles" of the client.
-This will give your client read-only access to the new endpoints.
-
-If you want to do management operations (like updating the profile structure or managing resource permissions),
-you need to assign the corresponding roles to your client: `hawk-manage-profile-structure`, `hawk-manage-profile-data`, `hawk-manage-resource-permissions`.
-
-As a last step, open your "Realm settings" you want to use the client with go to "Events" and add the "hawk-cache-buster" event listener.
+The installer will also automatically add a new group of client scopes to your realm called `hawk-client` as well, that you can assign to your clients.
+
+1. Create a new client, or use an existing one
+2. Open the client and navigate to the "Service account roles" tab
+3. Assign the `(realm-management) hawk-client` role to the client
+   - If you want to do management operations (like updating the profile structure or managing resource permissions),
+     you need to assign the corresponding roles to your client: `hawk-manage-profile-structure`, `hawk-manage-profile-data`, `hawk-manage-resource-permissions`.
+4. Open the "Client scopes" tab
+5. Add the `hawk-client` scope using the "Default" option.
+6. Open the "Realm settings" in your main menu
+7. Navigate to the "Events" tab and add the `hawk-cache-buster` event listener.
 
 ## What's in the box?
 

src/main/java/com/hawk/keycloak/ClientScopeRegistration.java

@@ -0,0 +1,84 @@
+package com.hawk.keycloak;
+
+import lombok.RequiredArgsConstructor;
+import org.keycloak.models.*;
+import org.keycloak.models.utils.KeycloakModelUtils;
+import org.keycloak.protocol.oidc.mappers.GroupMembershipMapper;
+import org.keycloak.protocol.oidc.mappers.OIDCAttributeMapperHelper;
+import org.keycloak.protocol.oidc.mappers.UserClientRoleMappingMapper;
+import org.keycloak.protocol.oidc.mappers.UserRealmRoleMappingMapper;
+
+import java.util.stream.Stream;
+
+@RequiredArgsConstructor
+public class ClientScopeRegistration {
+    public final static String CLIENT_SCOPE_NAME = "hawk-client";
+
+    final private KeycloakSessionFactory sessionFactory;
+
+    public void register() {
+        KeycloakModelUtils.runJobInTransaction(sessionFactory, (KeycloakSession session) -> {
+            Stream<RealmModel> realms = session.realms().getRealmsStream();
+            realms.forEach(this::registerInRealm);
+        });
+    }
+
+    public void registerInRealm(RealmModel realm) {
+
+        ClientScopeModel scope = realm.getClientScopesStream()
+                .filter(s -> s.getName().equals(CLIENT_SCOPE_NAME))
+                .findFirst()
+                .orElse(null);
+
+        if (scope != null) {
+            return;
+        }
+
+        // Create the scope
+        scope = realm.addClientScope(CLIENT_SCOPE_NAME);
+        scope.setDescription("Required claims for the hawk-client library");
+        scope.setProtocol("openid-connect");
+        scope.setIncludeInTokenScope(false);
+        scope.setDisplayOnConsentScreen(false);
+
+        // Realm Roles
+        ProtocolMapperModel realmRoleMapper = UserRealmRoleMappingMapper.create(
+                null,
+                "realm roles",
+                "hawk.roles.realm",
+                false,
+                false,
+                false,
+                true
+        );
+        realmRoleMapper.getConfig().put(OIDCAttributeMapperHelper.INCLUDE_IN_USERINFO, "true");
+        scope.addProtocolMapper(realmRoleMapper);
+
+        // Client Roles
+        ProtocolMapperModel clientRoleMapper = UserClientRoleMappingMapper.create(
+                null,
+                null,
+                "client roles",
+                "hawk.roles.client.${client_id}",
+                false,
+                false,
+                false,
+                true
+        );
+        clientRoleMapper.getConfig().put(OIDCAttributeMapperHelper.INCLUDE_IN_USERINFO, "true");
+        scope.addProtocolMapper(clientRoleMapper);
+
+        // Groups
+        ProtocolMapperModel groupMapper = GroupMembershipMapper.create(
+                "groups",
+                "hawk.groups",
+                false,
+                null,
+                false,
+                false,
+                false
+        );
+        groupMapper.getConfig().put(OIDCAttributeMapperHelper.INCLUDE_IN_USERINFO, "true");
+        scope.addProtocolMapper(groupMapper);
+    }
+}

src/main/java/com/hawk/keycloak/HawkResourceProviderFactory.java

@@ -25,7 +25,10 @@ public void init(Config.Scope scope) {
     @Override
     public void postInit(KeycloakSessionFactory keycloakSessionFactory) {
         java.util.concurrent.Executors.newSingleThreadScheduledExecutor().schedule(
-                () -> new RoleRegistration(keycloakSessionFactory).register(),
+                () -> {
+                    new RoleRegistration(keycloakSessionFactory).register();
+                    new ClientScopeRegistration(keycloakSessionFactory).register();
+                },
                 1, // delay duration
                 java.util.concurrent.TimeUnit.SECONDS // delay unit
         );