Merge pull request #57 from rciam/configuration-documentation

configuration document and add manage realm rights

README.md

@@ -14,8 +14,10 @@ A keycloak plugin to support advanced group management features:
 * Roles within groups
 
 ## General configuration options 
+All web services to be executed needs realm management rights role.
 
-For general group management configuarion options execute following web service (necessary during first time deployed):
+1. You should define realm attribute 'keycloakUrl' (Keycloak main url)
+2. (optional) For general group management configuration options execute following web service (necessary during first time deployed):
 
 `curl --request PUT \
 --url {server_url}/realms/{realmName}/agm/admin/configuration \
@@ -28,10 +30,47 @@ For general group management configuarion options execute following web service
 }'`
 
 Parameter explanation:
-- invitation-expiration-period = After how many hours the invitation will be expired.
-- expiration-notification-period = How many days before Group Membership expiration (or aup expiration) notification email will be sent to user. Can be overridden per Group.
+- invitation-expiration-period = After how many hours the invitation will be expired. (default value is 72)
+- expiration-notification-period = How many days before Group Membership expiration (or aup expiration) notification email will be sent to user. Can be overridden per Group. (default value is 21)
+
+3. For configuring entitlements user attribute you must execute the following web service :
+   `curl --request POST \
+   --url {server_url}/realms/{realmName}/agm/admin/member-user-attribute/configuration \
+   --header 'Accept: application/json' \
+   --header 'Authorization: Bearer {admin_access_token}' \
+   --header 'Content-Type: application/json' \
+   --data '{
+   "userAttribute" : "entitlements",
+   "urnNamespace" : "urn%3Amace%3Aexample.org",
+   "authority" : "rciam.example.org" // Optional. It will be omitted from the group entitlements if not specified
+   }'`
+
+Only authority is optional.
+
+4.  Configuration rules exists for group configuration options. Web service example:
+   `curl --request POST \
+   --url {server_url}/realms/{realmName}/agm/admin/configuration-rules \
+   --header 'Accept: application/json' \
+   --header 'Authorization: Bearer {admin_access_token}' \
+   --header 'Content-Type: application/json' \
+   --data '{
+   "field" : "membershipExpirationDays" ,
+   "type" : "TOP_LEVEL" ,
+   "required" : true,
+   "defaultValue" : "30",
+   "max" : "45"
+   }'`
+
+Fields explanation :
+- *field* : field of group management (required)
+- *type* : "TOP_LEVEL" or "SUBGROUP" (required)
+- *required* : required field (required)
+- *defaultValue* : default value
+- *max* : max value
+
+With PUT *{server_url}/realms/{realmName}/agm/admin/configuration-rules/{id}* you could update a configuration rule.
+With GET *{server_url}/realms/{realmName}/agm/admin/configuration-rules* you could get all configuration rules.
 
-You should define realm attribute 'keycloakUrl' (Keycloak main url)
 
 ## REST API
 

src/main/java/org/rciam/plugins/groups/services/AdminEnrollmentConfigurationRules.java

@@ -19,6 +19,7 @@
 import org.keycloak.models.RealmModel;
 import org.keycloak.models.jpa.entities.RealmEntity;
 import org.keycloak.models.utils.KeycloakModelUtils;
+import org.keycloak.services.resources.admin.permissions.AdminPermissionEvaluator;
 import org.rciam.plugins.groups.helpers.EntityToRepresentation;
 import org.rciam.plugins.groups.jpa.entities.GroupEnrollmentConfigurationRulesEntity;
 import org.rciam.plugins.groups.jpa.repositories.GroupEnrollmentConfigurationRulesRepository;
@@ -30,22 +31,26 @@ public class AdminEnrollmentConfigurationRules {
     private final RealmModel realm;
     private final GroupEnrollmentConfigurationRulesRepository groupEnrollmentConfigurationRulesRepository;
     private final AdminEventBuilder adminEvent;
+    private  final AdminPermissionEvaluator realmAuth;
 
-    public AdminEnrollmentConfigurationRules(RealmModel realm, KeycloakSession session, AdminEventBuilder adminEvent) {
+    public AdminEnrollmentConfigurationRules(RealmModel realm, KeycloakSession session, AdminEventBuilder adminEvent, AdminPermissionEvaluator realmAuth) {
         this.realm = realm;
         this.groupEnrollmentConfigurationRulesRepository = new GroupEnrollmentConfigurationRulesRepository(session);
         this.adminEvent = adminEvent;
+        this.realmAuth = realmAuth;
     }
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
     public List<GroupEnrollmentConfigurationRulesRepresentation> getEnrollmentConfigurationRules() {
+        realmAuth.realm().requireViewRealm();
         return groupEnrollmentConfigurationRulesRepository.getByRealm(realm.getId()).map(EntityToRepresentation::toRepresentation).collect(Collectors.toList());
     }
 
     @POST
     @Consumes(MediaType.APPLICATION_JSON)
     public Response configureRule(GroupEnrollmentConfigurationRulesRepresentation rep) {
+        realmAuth.realm().requireManageRealm();
         GroupEnrollmentConfigurationRulesEntity entity = new GroupEnrollmentConfigurationRulesEntity();
         entity.setId(KeycloakModelUtils.generateId());
         RealmEntity realmEntity = new RealmEntity();
@@ -64,6 +69,7 @@ public Response configureRule(GroupEnrollmentConfigurationRulesRepresentation re
     @Path("/{id}")
     @Consumes(MediaType.APPLICATION_JSON)
     public Response updateConfigureRule(GroupEnrollmentConfigurationRulesRepresentation rep, @PathParam("id") String id) {
+        realmAuth.realm().requireManageRealm();
         GroupEnrollmentConfigurationRulesEntity entity = groupEnrollmentConfigurationRulesRepository.getEntity(id);
         if (entity == null) {
             throw new NotFoundException("Could not find GroupEnrollmentConfigurationRules by id");
@@ -81,6 +87,7 @@ public Response updateConfigureRule(GroupEnrollmentConfigurationRulesRepresentat
     @Path("/{id}")
     @Produces(MediaType.APPLICATION_JSON)
     public GroupEnrollmentConfigurationRulesRepresentation getConfigureRule(@PathParam("id") String id) {
+        realmAuth.realm().requireViewRealm();
         GroupEnrollmentConfigurationRulesEntity entity = groupEnrollmentConfigurationRulesRepository.getEntity(id);
         if (entity == null) {
             throw new NotFoundException("Could not find GroupEnrollmentConfigurationRules by id");
@@ -92,6 +99,7 @@ public GroupEnrollmentConfigurationRulesRepresentation getConfigureRule(@PathPar
     @Path("/{id}")
     @Produces(MediaType.APPLICATION_JSON)
     public Response deleteConfigureRule(@PathParam("id") String id) {
+        realmAuth.realm().requireManageRealm();
         groupEnrollmentConfigurationRulesRepository.deleteEntity(id);
         return Response.noContent().build();
     }

src/main/java/org/rciam/plugins/groups/services/AdminService.java

@@ -93,6 +93,7 @@ public Response configureGroupManagement(Map<String, String> attributes) {
     @Path("/member-user-attribute/configuration")
     @Produces(MediaType.APPLICATION_JSON)
     public MemberUserAttributeConfigurationRepresentation memberUserAttributeConfiguration() {
+        realmAuth.realm().requireManageRealm();
         MemberUserAttributeConfigurationEntity memberUserAttributeEntity = memberUserAttributeConfigurationRepository.getByRealm(realm.getId());
         return memberUserAttributeEntity != null ? EntityToRepresentation.toRepresentation(memberUserAttributeEntity) : new MemberUserAttributeConfigurationRepresentation();
     }
@@ -101,6 +102,7 @@ public MemberUserAttributeConfigurationRepresentation memberUserAttributeConfigu
     @Path("/member-user-attribute/configuration")
     @Consumes(MediaType.APPLICATION_JSON)
     public Response configureMemberUserAttribute(MemberUserAttributeConfigurationRepresentation rep) {
+        realmAuth.realm().requireManageRealm();
         MemberUserAttributeConfigurationEntity memberUserAttributeEntity = memberUserAttributeConfigurationRepository.getByRealm(realm.getId());
         memberUserAttributeEntity.setUserAttribute(rep.getUserAttribute());
         memberUserAttributeEntity.setUrnNamespace(rep.getUrnNamespace());
@@ -120,7 +122,7 @@ public Response calculateMemberUserAttribute(){
 
     @Path("/configuration-rules")
     public AdminEnrollmentConfigurationRules adminEnrollmentConfigurationRules() {
-        AdminEnrollmentConfigurationRules service = new AdminEnrollmentConfigurationRules(realm, session, adminEvent);
+        AdminEnrollmentConfigurationRules service = new AdminEnrollmentConfigurationRules(realm, session, adminEvent, realmAuth);
         ResteasyProviderFactory.getInstance().injectProperties(service);
         return service;
     }