Skip to content

Groups with Roles Feature

Jump to bottom
Benjamin Kiah Stroud edited this page Feb 3, 2023 · 19 revisions

Groups with Roles

Table of Contents

Defining Roles, Users, and Groups

Permissions for users in Hyku are complex and configurable. This guide will outline the default, recommended way of utilizing these features, but other customizations are possible.

First, it is worthwhile to define some basic concepts:

  • Role: a specific permission over some aspect of repository management. Hyku includes the roles listed below. Each role inherits the abilities of the roles below it:

    • Admin Grants: unrestricted access to this tenant
    • Collection Editor: Can create, read, and edit any Collection in this tenant
    • Collection Manager: Can create, read, edit, and destroy any Collection in this tenant
    • Collection Reader: Can read any Collection in this tenant
    • User Manager: Can read, edit, invite, and remove any User in this tenant
    • User Reader: Can read any User in this tenant
    • Work Editor: Can create, read, edit, and approve any Work in this tenant, as well as move Works between Admin Sets and manage Embargoes and Leases
    • Work Depositor: Can deposit Works into any Admin Set in this tenant. Can read, edit, and manage Embargoes / Leases for Works belonging to them

  • Workflow role: a subset of roles that pertains to the depositing, approving, or managing works within a specific admin set. Roles granted across all repositories are automatically granted different workflow roles over all admin sets:

    • Managing: can add works, edit admin set configuration, and approve works submitted through a mediated deposit workflow
      • Those with Admin and Collection Manager roles are automatically admin set managers
    • Approving: can approve works submitted through a mediated deposit workflow
      • Those with Collection Editor and Work Editor are automatically able to approve in admin sets
    • Depositing: can add works to the admin set, whether a mediated or default workflow
      • Those with the Depositor role can deposit to any admin set

  • Group: a predefined set of roles used to create desired classes of users. Groups are how we recommend you control your user permissions. Hyku comes with the following default groups:

    • Repository Administrators: Users in this group are considered admins for this tenant and have unrestricted access.
      • Roles: Admin.
    • Editors: Users in this group are considered admins for this tenant and have unrestricted access.
      • Roles: Work Editor, Collection Editor, User Reader.
    • Depositors: Users in this group are allowed to deposit Works into any Admin Set in this tenant.
      • Roles: Work Depositor.
    • Registered Users: Contains all users who have signed up in this tenant.
      • No roles.

  • User: individual accounts in Hyku that are assigned specific roles or to a group that has a predefined combination of roles.

Setup an Existing Application to use Groups with Roles

These rake tasks will create data across all tenants necessary to setup Groups with Roles. Run them in the order listed below.

Prerequisites:

  • All Collections must have CollectionTypes and PermissionTemplates (see the Collection Migration section in the Hyrax 2.1 Release Notes)
rake hyku:roles:create_default_roles_and_groups
rake hyku:roles:create_collection_accesses
rake hyku:roles:create_admin_set_accesses
rake hyku:roles:create_collection_type_participants
rake hyku:roles:add_admin_users_to_admin_group
rake hyku:roles:grant_workflow_roles
rake hyku:roles:destroy_registered_group_collection_type_participants # optional

* The hyku:roles:destroy_registered_group_collection_type_participants task is technically optional. However, without it, collection readers will be allowed to create Collections.

Default Roles and Hyrax::Groups are seeded into an account (tenant) at creation time (see CreateAccount#create_defaults), so these only need to be run once.

Role Set Creation Guidelines

  1. Add role names to the RolesService::DEFAULT_ROLES constant
  2. Find related ability concern in Hyrax (if applicable)
  • Look in app/models/concerns/hyrax/ability/ (local repo first, then Hyrax's repo)
  • E.g. ability concern for Collections is app/models/concerns/hyrax/ability/collection_ability.rb
  • If a concern matching the record type exists in Hyrax, but no the local repo, copy the file into the local repo
    • Be sure to add override comments (use the OVERRIDE: prefix)
  • If no concern matching the record type exists, create one.
    • E.g. if creating an ablility concern for the User model, create app/models/concerns/hyrax/ability/user_ability.rb
  1. Create a method in the concern called <record_type>_roles (e.g. collection_roles)
  2. Add the method to the array of method names in Ability#ability_logic
  3. Within the <record_type>_roles method in the ability concern, add CanCanCan rules for each role, following that role's specific criteria.
  • When adding/removing permissions, get as granular as possible.
  • Beware using can :manage -- in CanCanCan, :manage refers to any permission, not just CRUD actions.
    • E.g. If you want a role to be able to create, read, edit, update, but not destroy Users
    # Bad - could grant unwanted permissions
can :manage, User
cannot :destroy, User

# Good
can :create, User
can :read, User
can :edit, User
can :update, User
  • CanCanCan rules are hierarchical: 
    # Will still grant read permission
cannot :manage, User # remove all permissions related to users
can :read, User
  1. Add new / change existing #can? ability checks in views and controllers where applicable

Search Permissions Notes

Using the feature

Managing Users, Groups and Permissions

Clone this wiki locally