Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rciam/keycloak-group-management
A keycloak plugin to perform advanced group management
https://github.com/rciam/keycloak-group-management
Last synced: about 1 month ago
JSON representation
A keycloak plugin to perform advanced group management
- Host: GitHub
- URL: https://github.com/rciam/keycloak-group-management
- Owner: rciam
- License: apache-2.0
- Created: 2022-07-21T12:51:23.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T07:16:17.000Z (3 months ago)
- Last Synced: 2024-04-12T15:07:06.606Z (3 months ago)
- Language: CSS
- Size: 1.34 MB
- Stars: 9
- Watchers: 4
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Lists
- awesome-keycloak - rciam/keycloak-group-management
README
# keycloak-group-management
A keycloak plugin to support advanced group management features:
* User-driven group enrollment flows:
* Users can request membership in groups:
* Accept group Terms & Conditions
* Provide comment/justification
* Membership requests are reviewed by group managers
* Time-based group membership:
* Automatic expiration of group membership beyond a configurable time period after joining the group
* Membership renewal process
* Roles within groups
## Keycloak compatibility matrix
| Group management version | Keycloak version |
|--------------------------|------------------|
| 0.9.0 | 18.0.1-2.17 |
| 0.10.0 | 22.0.5-1.1 + |
| 0.13.0 | 22.0.5-1.2 + |
## General configuration options
All web services to be executed needs realm management rights role.
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 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {admin_access_token}' \
--header 'Content-Type: application/json' \
--data '{
"invitation-expiration-period":"72",
"expiration-notification-period": "21"
}'`
Parameter explanation:
- 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.
When a group is created, a default configuration is created. Group admin can change it/ create a new one.
Configuration rules determines the default group configuration and applies rules in group configuration creation/ update.
Default group configuration values without any configuration rules:
| Field | Label | Default value |
|--------------------------|------------------|---------------------|
| name | name | Join + |
| requireApproval | Requires approval| True |
| commentsNeeded | Comments | True |
| visibleToNotMembers | Visible | False |
| active | Active | True |
| membershipExpirationDays | Expiration date | null |
| aup.url | Aup url | null |
Default group role is member (default group role during creation)
## REST API
Main url : {server_url}/realms/{realm}/agm
**User web services ( Any Keycloak User)**
| Path | Method | Description | Classes |
|----------------------------------------------|--------|--------------------------------------------------------------------------------------|---------------------------------|
| /account/user/groups | GET | get all user groups | UserGroups |
| /account/user/invitation/{id} | GET | get invitation by id | UserGroups |
| /account/user/invitation/{id}/accept | POST | accept invitation and become group member or admin | UserGroups |
| /account/user/invitation/{id}/reject | POST | reject invitation for becoming group member or admin | UserGroups |
| /account/user/groups/configurations | GET | get all available group configurations (active and visibleToNotMembers) by groupPath | UserGroups |
| /account/user/groups/configuration/{id} | GET | get group configuration by id | UserGroups |
| /account/user/group/{groupId}/configurations | GET | get all available group configurations (active and visibleToNotMembers) | UserGroup |
| /account/user/group/{groupId}/member | GET | get user group membership | UserGroupMember |
| /account/user/group/{groupId}/member | DELETE | leave user group membership | UserGroupMember |
| /account/user/enroll-requests | GET | get all user ongoing enrollment requests | UserGroups |
| /account/user/enroll-request | POST | create new enrollment request | UserGroups |
| /account/user/enroll-request/{id} | GET | get enrollment request by id | UserGroupEnrollmentRequestAction |
| /account/user/enroll-request/{id}/respond | POST | respond t enrollment request by id | UserGroupEnrollmentRequestAction |
**Group admin web services ( for group specific web services user must have admin rights to this group)**
| Path | Method | Description | | Classes |
|--------------------------------------------------------------------|--------|-------------------------------------------------------------------------------|------------------------------|
| /account/group-admin/groups | GET | get all groups that this user has admin rights | GroupAdminService |
| /account/group-admin/configuration-rules | GET | get group enrollment configuration rules based on group type | GroupAdminService |
| /account/group-admin/groupids/all | GET | get all groups ids that this user has admin rights | GroupAdminService |
| /account/group-admin/groups/members | GET | get all groups members given the groupids as comma-separated string | GroupAdminService |
| /account/group-admin/group/{groupId} | DELETE | delete group | GroupAdminGroup |
| /account/group-admin/group/{groupId}/all | GET | get all group information | GroupAdminGroup |
| /account/group-admin/group/{groupId}/children | POST | create child group | GroupAdminGroup |
| /account/group-admin/group/{groupId}/configuration/all | GET | get all group enrollment configurations | GroupAdminGroup |
| /account/group-admin/group/{groupId}/configuration/{id} | GET | get group enrollment configuration | GroupAdminGroup |
| /account/group-admin/group/{groupId}/configuration | POST | create/ update group enrollment configuration | GroupAdminGroup |
| /account/group-admin/group/{groupId}/configuration/{id} | DELETE | delete group enrollment configuration | GroupAdminGroup |
| /account/group-admin/group/{groupId}/default-configuration | POST | change default group enrollment configuration | GroupAdminGroup |
| /account/group-admin/group/{groupId}/roles | GET | get all group roles | GroupAdminGroup |
| /account/group-admin/group/{groupId}/roles | POST | create group role | GroupAdminGroup |
| /account/group-admin/group/{groupId}/role/{name} | DELETE | delete group role | GroupAdminGroup |
| /account/group-admin/group/{groupId}/members | GET | get all group members pager, being able to search and get by type (fe active) | GroupAdminGroupMembers |
| /account/group-admin/group/{groupId}/members/invitation | POST | send invitation to a user based on email | GroupAdminGroupMembers |
| /account/group-admin/group/{groupId}/member/{memberId} | PUT | update specific fields of group member | GroupAdminGroupMembers |
| /account/group-admin/group/{groupId}/member/{memberId} | DELETE | delete group member | GroupAdminGroupMember |
| /account/group-admin/group/{groupId}/member/{memberId}/role | POST | add role to group member | GroupAdminGroupMember |
| /account/group-admin/group/{groupId}/member/{memberId}/role/{name} | DELETE | delete role from group member | GroupAdminGroupMember |
| /account/group-admin/group/{groupId}/member/{memberId}/suspend | POST | suspend group member | GroupAdminGroupMember |
| /account/group-admin/group/{groupId}/member/{memberId}/activate | POST | activate group member | GroupAdminGroupMember |
| /account/group-admin/group/{groupId}/admin/{userId} | POST | add user as admin | GroupAdminGroup |
| /account/group-admin/group/{groupId}/admin/invite | POST | invite user as group admin for this groupId group | GroupAdminGroup |
| /account/group-admin/group/{groupId}/admin/{userId} | DELETE | delete group admin | GroupAdminService |
| /account/group-admin/enroll-requests | GET | get all group admin enrollment requests | GroupAdminService |
| /account/group-admin/enroll-request/{enrollId} | GET | get enrollment request | GroupAdminEnrollementRequest |
| /account/group-admin/enroll-request/{enrollId}/extra-info | POST | request extra infrormation from user | GroupAdminEnrollementRequest |
| /account/group-admin/enroll-request/{enrollId}/accept | POST | accept group enrollment request | GroupAdminEnrollementRequest |
| /account/group-admin/enroll-request/{enrollId}/reject | POST | reject group enrollment request | GroupAdminEnrollementRequest |
**manage-groups account role**
Role name can be changed in database( column GROUP_ROLE_NAME of table GROUP_MANAGEMENT_EVENT)
| Path | Method | Description | Classes |
|----------------------------|-----------|----------------------------------------------|--------------------|
| /account/group-admin/group | POST | create top level group | GroupAdminService |
**Admin web services**
| Path | Method | Description | Classes |
--------------------------------------------|---------|---------------------------------------------------|------------------------------------|
/admin/group | POST | create top level group | AdminService |
/admin/configuration | PUT | change realm settings (realm attributes) | AdminService |
/admin/member-user-attribute/configuration | GET | get member user attribute configuration | AdminService |
/admin/member-user-attribute/configuration | POST | update member user attribute configuration | AdminService |
/admin/configuration-rules | GET | get group enrollment configuration rules | AdminEnrollmentConfigurationRules |
/admin/configuration-rules | POST | create group enrollment configuration rule | AdminEnrollmentConfigurationRules |
/admin/configuration-rules/{id} | GET | get group enrollment configuration rule by id | AdminEnrollmentConfigurationRules |
/admin/configuration-rules/{id} | PUT | update group enrollment configuration rule | AdminEnrollmentConfigurationRules |
/admin/configuration-rules/{id} | DELETE | delete group enrollment configuration rule | AdminEnrollmentConfigurationRules |
/admin/memberUserAttribute/calculation | POST | update member user attribute value for all users | AdminService |
/admin/user/{id} | DELETE | delete user | AdminService |
/admin/group/{groupId} | DELETE | delete group | AdminGroups |
/admin/group/{groupId}/configuration/{id} | GET | get group enrollment configuration | AdminGroups |
/admin/group/{groupId}/configuration | POST | create/update group enrollment configuration | AdminGroups |
/admin/group/{groupId}/admin/{userId} | POST | create group admin | AdminGroups |
/admin/group/{groupId}/admin/{userId} | DELETE | delete group admin | AdminGroups |
/admin/group/{groupId}/children | POST | create child group | AdminGroups |