mod-roles-keycloak

Overview

mod-roles-keycloak is a Spring-based module responsible for the following functionality:

  1. Role management

  2. Policy management

  3. Capability and capability set storage

  4. Permissions mapping to capabilities and capability sets

  5. Links management between roles and capability and capability sets

  6. Links management between users and capability and capability sets

  7. Keycloak role, policy management based on entities stored in mod-roles-keycloak

  8. Keycloak permission management based on existing relations between users and roles to capability and capability sets

  9. User folio-permissions for _self request

GitHub repository: https://github.com/folio-org/mod-roles-keycloak

API-Documentation: https://s3.amazonaws.com/foliodocs/api/mod-roles-keycloak/s/mod-roles-keycloak.html

Functionality

Role management

mod-roles-keycloak allows role management:

  1. A user can view, create, edit, and delete roles

  2. A user can assign and unassign roles to/from a user

Policy management

mod-roles-keycloak allows policy management:

  1. A user can view, create, edit, and delete policies for types: time, role, user

In current implementation, policies are created during the capability and capability set assignment to the role or user.

Policies created by users are not used in authorization processes.

A generated name for role policy would look like: Policy for role: {roleId}, for user: Policy for user: {userId}

Capability and capability sets

mod-roles-keycloak receives events with permission data from mgr-tenant-entitlements and transforms permission data into capabilities and capability sets:

Permission-Capability/CapabilitySet mapping algorithm

Reference roles (Loadable roles)

mod-roles-keycloak can store pre-defined roles as reference data and be populated through the Tenant Entitlement process.

Loadable role JSON file has the following format:

{ "roles": [ { "name": "{{role name}}", "description": "{{role description}}", "permissions": [ // list with Folio permission name ] } ] }

Reference data policies

mod-roles-keycloak can create a policy from reference data.

Policies JSON example:

{ "policies": [ { "id": "15f45670-1edf-441e-a247-51f6c000faa3", "name": "Business Hours", "type": "TIME", "source": "USER", "timePolicy": { "start": "2023-07-01T00:00:00", "expires": "2033-07-01T00:00:00", "logic": "POSITIVE", "monthStart": "1", "monthEnd": "12", "hourStart": "8", "hourEnd": "20" } } ] }

Permission migration

mod-roles-keycloak provides an API to migrate existing user permissions from mod-permissions and assign them to newly created roles with unique names, based on SHA1 hash from all contained permissions to this role.

Algorithm is described at User permissions migration.

Core models and entities

Role

A role in Keycloak is a fundamental building block used for access control and authorization within the Keycloak identity and access management system. Roles define a set of permissions or capabilities that can be assigned to users or groups to regulate their access to resources and functionalities within an application or system. By assigning roles, administrators can manage user permissions in a scalable and organized manner, ensuring that users have the appropriate level of access required to perform their duties while maintaining security and compliance.

Property

Type

Description

Property

Type

Description

id

UUID

A unique identifier for this role

name

String

A human-readable name/label for this role

description

String

A free form description of the role

type

String (enum)

Role type

One of DEFAULT, SUPPORT, REGULAR, CONSORTIUM

metadata

metadata

System-generated metadata (createdBy, updatedBy, createdDate, updatedDate)

User-Role

Describes a relation between user and role.

Property

Type