Roles Management with Eureka
- Craig McNally
- Dennis Bridges
WIP WIP WIP WIP WIP
Overview
The new Eureka platform, which Folio is adopting with the Sunflower release, replaces the permission-based access control model with one based on roles. The purpose of this document is to explain how to manage roles and their assignments.
Terminology
Permission
Permission Set
A permission with one or more subPermissions
Can be nested indefinitely
Resource
Something in Folio which users can perform operations on, e.g. Orders, instances, etc.
Action
A verb describing an operation that manipulates a resource, e.g. Create, edit, view, delete, execute, etc.
Capabilities
Define the ability to perform an action on a Folio resource, e.g. Edit (action) an Instances (resource)
Derived from information in module descriptors (Permissions)
Are managed by the system. Users and admins cannot create/remove capabilities. Rather, they’re created as applications are enabled for tenants.
Maintain a reference to the permission from which they were created.
Maintain a reference to the application which provides them.
Capability Sets
Comprised of capabilities
Derived from information in module descriptors (Permission Sets)
Are managed by the system. Users and admins cannot create/remove capabilities. Rather, they’re created as applications are enabled for tenants.
Maintain a reference to the permission from which they were created.
Maintain a reference to the application which provides them.
Not nested.
Roles
Comprised of capabilities and/or capabilitySets
Are created/managed by administrators, not the system.
Cannot be nested. Roles are flat.
Ideally are reusable (aren’t snowflakes)
Default Roles
Roles provided by the system, effectively reference data optionally loaded during tenant entitlement.
Policies
Provide greater control over who can do what, when, from where, etc. E.g. Policies could be created to only allow a user to perform check-in/check-out operations during normal business hours, from certain locations (not from their dorm room late at night)
Are associated with capabilities
Time-based policies are managed by administrators, not the system.
This functionality is a work in progress.
AuthUser
Refers to a user record in Keycloak
AuthUsers are managed by Folio. No direct interaction with Keycloak is required
Are a subset of Users, which include staff, patrons, administrators, etc.
A user becomes an AuthUser if they are assigned credentials, roles, or capabilities. The keycloak user record is only needed for those who log in and use Folio. There’s no need for Keycloak to know about patrons and others who are just data in the system.
How do these relate to one another? The following diagram may help you visualize the relationships between some of these terms:
Migration
When migrating from the Okapi platform to Eureka adjustments must be made. Some of this will be handled by migration APIs. Other parts will need to be performed by a human.
Migration APIs
There are two APIs which do much of the heavy lifting. The goal of these is to ensure users who could perform certain actions on Okapi, can still perform those same actions on Eureka.
Users migration - provided by mod-users-keycloak. This API will create AuthUser for any User in the system which has at least one permission assigned to them.
Roles migration - provided by mod-roles-keycloak. This API looks at the permissions assigned to users, and creates a Role for each unique set. These system-generated roles are then assigned to the appropriate users.
N.B. Given the high level of nesting in permission sets on the Okapi platform, and the flat roles on Eureka, the migration APIs do not attempt to perform a one-to-one mapping of permission Sets to roles.
Post-migration Cleanup
After the migration APIs have been run, human intervention is likely required to clean up system-generated roles. This includes renaming, providing descriptions, splitting, and possibly combining. Alternatively, administrators could create roles from scratch, transition to them, and eventually remove the system generated roles.
Role Creation
Role creation happens in the “Authorization Roles” section of Settings. Use the “+New” button to open the form for creating a role.
Provide a name and description, then you will need to use the “Select application” button to open the selection modal. The purpose of selecting applications is to specify the functional areas which provide capabilities and capability sets you want to add to the role. Only the Capabilities and Capability Sets provided by the selected application(s) will be shown.
After selecting one or more applications and clicking “Save and close”, the capability and capability set portions of the role creation form will be populated, and you can select those which you want to include in your role by checking individual boxes, or the boxes in the column headers.
A few notes on selecting capabilities and capability sets:
Capabilities and Capability Sets are partitioned into 3 groups: Data, Settings, Procedural. These are intended to make it easier to find what you’re looking for. Also the set of actions (grid columns) differs for some of these.
Data - capabilities for directly managing resources as they exist in Folio (i.e. RESTful)
e.g. “Instance”, “purchase order lines”, etc.
Procedural - capabilities for initiating and controlling processes in Folio (i.e. execution of tasks)
e.g. “check-out-by-barcode”
Settings - administrative capabilities for managing Folio configurations
e.g. “Notes Settings”
Selecting a capability set will result in the automatic selection of its constituent capabilities. You will not be able to unselect individual capabilities which were automatically checked.
Tip: Using “find on page” (e.g.
Ctrl+f/Command-F) can be helpful to find what you’re looking for.
When you’re finished, don’t forget to use the “Save & close” button.
Role Modification
Making adjustments to roles is very similar to creating new roles. Start by selecting the name of the desired role. This will result in a detail pane to be displayed.
Tip: the search bar can help you find what you’re looking for
Use the “Actions” menu in the role details pane to edit the role.
The role edit form looks and behaves the same as the role creation form. Refer to the Role Creation section for details.
Role Deletion
Deletion of a role requires similar steps as role modification. Refer to the Role Modification section for details. However, instead of selecting “Edit” from the “Actions” menu, select “Delete”. You will be asked to confirm. Care should be taken when deleting roles. Deletion of a role cannot be undone. When deleting a role which is assigned to users, the role assignments will automatically be removed.
Role Duplication
Duplication of a role can be accomplished by following similar steps as role modification. Refer to the Role Modification section for details. However, instead of selecting “Edit” from the “Actions” menu, select “Duplicate”. You will be asked to confirm. A system-generated name will be given to the duplicate role. Role assignments will not be copied to the new role.
After confirming you will automatically be taken to the new/duplicate role.
Shared Roles
Shared roles are centrally managed, in that they can only be edited in the consortia manager. A shared role will appear as a Role under in all tenants with the same capabilities. User from the given tenant can be assigned to that role. Editing that role in the central tenant will change it for all tenants.
To share a role users must have permissions to access the consortia manager app and share data. With your active affiliation set to the systems central tenant. Navigate to Consortia manager → Authorization Roles.
Select the central tenant from the Member dropdown at the top of the second pane
Choose a Role that you have created in the central tenant
Click the actions menu
Click “Share to all”
When the confirmation modal appears click “Submit” to confirm and share the role with all tenants in the system
You will see a success toast message
In the view pane for the role you will now see “Centrally managed” = Yes
Managing Role Assignments
Role assignments can be managed from a few different places. Which is most appropriate depends on what you’re doing.
From Settings → Authorization Roles
This is a good choice when assigning or unassigning multiple users to/from a given role.
From the Users app
This is a good choice when managing role assignments for a given user.
From Consortia manager → Authorization Roles (Only applicable to consortia systems with ECS enabled.)
From here you can manage role assignments across all related tenants
From here you can also create “Shared” roles that can be used by all tenants in the system
Settings / Authorization Roles
To manage role assignments in the context of a particular role, navigate to the “Authorization Roles” section of Settings. Start by selecting the name of the desired role. This will result in a detail pane to be displayed.
Tip: the search bar can help you find what you’re looking for
Once you have selected a role, an additional pane will open showing the details of that role. This role detail pane will include an “Assigned users” accordion (which should be expanded by default).
Clicking on the “Assign/Unassign” button will open the “Select User” modal. Use the facets and search functions to help find the user(s) you want to assign or unassign.
To assign a user to the role, check the box in the first column. To unassign a user from the role, uncheck the box. When finished, click “Save”.
In some cases you may see a dialog asking you to confirm the creation of user records in Keycloak. The creation of these records is necessary for the role assignment to succeed. Click “Confirm” to proceed, or “Cancel” if you’re unsure.
Upon completion, you will land back at the role detail view. If the assignment (or unassignment) was successful, you should see a green message indicating the success at the bottom of your screen. The “Assigned users” accordion should be updated to reflect the changes you’ve just made.
Users App
To manage role assignments in the context of a particular user, navigate to the “Users” app. Use the facets and search functions to help find the user you want to assign to roles.
Select a user to open a pane displaying that user’s details. Here you will see a “User roles” accordion (collapsed by default). When collapsed, a bubble in the accordion header indicates how many roles the user is presently assigned to. While this accordion is helpful for viewing a user’s role assignments, you cannot edit a user’s role assignments here. Instead you must select the “Edit” option from the “Action” menu.
On the Edit form, scroll down to and click on the “User roles” accordion to expand it. Here you will see the list of roles this user is assigned to. You can click the “X” icon for a given role to unassign that role. You also have the option to unassign all user roles and add user roles via the buttons below the list or roles.
When using “Unassign all user roles”, you will be prompted to confirm that action. The roles being removed will be listed in the dialog.
When using “Add user roles”, the “Select user roles” modal will be displayed. Use the facets and search functions to help find the role(s) you want to assign to the user. Check the boxes next to the roles you want to assign (or uncheck the roles you want to unassign). When finished, click “Save & close” to submit your changes.
Finally, in order for any of the changes you’ve made to be saved, you must click the “Save & close” button in the user edit form.
N.B. Don’t forget to click “Save & close” on the user edit form to save your changes. If you cancel now, your changes will not take effect.
In some cases you may see a dialog asking you to confirm the creation of a user record in Keycloak. The creation of this record is necessary for the role assignment to succeed. Click “Confirm” to proceed, or “Cancel” if you’re unsure.
Upon completion, you will land back at the user detail view. The “User roles” accordion should be updated to reflect the changes you’ve just made.
Tips and Tricks
TODO: Yada yada
Settings → Developer → Can I haz capabilities?
Where might this be helpful?
I’ve assigned a role, or adjusted a role which was already assigned, now what?
refresh? re-authenticate? neither?
Looking Ahead
TODO: Mention some things eventually coming…
Policies
Why?
Current state/When?
Direct capability/capbilitySet assignments to users
Why?
Current state/When?