Groups with Roles Feature

Groups with Roles

Table of Contents

• Creating Default Roles and Groups
• Setup an Existing Application to use Groups with Roles
• Role Set Creation Guidelines
  • Other Information
• Search Permissions Notes

---

Creating Default Roles and Groups

Default Roles and Hyrax::Groups are seeded into an account (tenant) at creation time (see CreateAccount#create_defaults).

To manually seed default Roles and Hyrax::Groups across all tenants, run this rake task:

rake hyku:roles:create_default_roles_and_groups

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.

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

3. Create a method in the concern called <record_type>_roles (e.g. collection_roles)
4. Add the method to the array of method names in Ability#ability_logic
5. 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

6. Add new / change existing #can? ability checks in views and controllers where applicable

Other Information

• For guidelines on overriding dependencies, see the Overrides to Dependencies section of the README
• Add ability specs and feature specs

Search Permissions Notes

• Permissions are injected in the solr query's fq ("filter query") param (link to code)
• Enforced (injected into solr query) in Blacklight::AccessControls::Enforcement
• Represented by an instance of Blacklight::AccessControls::PermissionsQuery (see #permissions_doc)
• Admin users don't have permission filters injected when searching (link to code)
• SearchBuilder may be related to when permissions are and aren't enforced
• Related discussions in Slack:
  • first inheritance question
  • second inheritance question

Extra Resources

Managing Users, Groups and Permissions