MODROLESKC-215 Spike - Ability to rename capabilities

1 Spike Overview
2 Background
3 Scope
4 Research
- 4.1 Case 1 - Replace multiple permissions with a single permission
  - 4.1.1 Inputs
  - 4.1.2 Outputs
- 4.2 Case 2 - Replace permission set with ordinary permissions
  - 4.2.1 Inputs
  - 4.2.2 Outputs
5 Conclusion
6 Attachments

Spike Overview

Objective: Spike - How Okapi handles permission replacement and what Eureka should do to honor this properly.

Background

During a module enabling OKAPI is responsible for providing the permissions from ModuleDescriptor and the corresponding moduleId to the _tenantPermissions API provided by mod-permissions module. Determination of the appropriate actions to be taken is the responsibility of this module. Most of this will happen without explicit or special provisioning in the ModuleDescriptor. Adding, removing or updating the permissions in the permissionsSet property of ModuleDescriptor is usually sufficient. One exception to that is renaming or replacing one or more permissions / permission sets with another. This is accomplished via the replaces property on the permission object, e.g.

...
"permissionSets": [
    ...
    {
      "permissionName": "tags.item.manage",
      "displayName": "Tags - manages tag",
      "description": "Manages tags",
      "replaces": [ "tags.item.get", "tags.item.post", "tags.item.put", "tags.item.delete" ]
    },
    ...

Scope

Check how permission replacement works in OKAPI
- multiple permissions replace one old permission
- one permission replaces multiple old permissions
Check how OKAPI handles cases for UI
- Does _/self endpoint return old permissions
- Does _/self endpoint return new permissions (without direct assignment)
Check how replaces works for permissions sets (permission with sub permissions)
Identify changes required to support replacement functionality by Eureka platform.

Research

Case 1 - Replace multiple permissions with a single permission

Inputs

tags.item.manage permission replaces four individual permissions:
- tags.item.get,
- tags.item.post,
- tags.item.put,
- tags.item.delete

"permissionSets": [
    {
      "permissionName": "tags.collection.get",
      "displayName": "Tags - get tags collection",
      "description": "Get tags collection"
    },
    {
      "permissionName": "tags.item.get",
      "displayName": "Tags - get individual tag from storage",
      "description": "Get individual tag"
    },
    {
      "permissionName": "tags.item.post",
      "displayName": "Tags - create tag",
      "description": "Create tag"
    },
    {
      "permissionName": "tags.item.put",
      "displayName": "Tags - modify tag",
      "description": "Modify tag"
    },
    {
      "permissionName": "tags.item.delete",
      "displayName": "Tags - delete tag",
      "description": "Delete tag"
    },
    {
      "permissionName": "tags.all",
      "displayName": "Tags module - all permissions",
      "description": "Entire set of permissions needed to use the tags module",
      "subPermissions": [
        "tags.collection.get",
        "tags.item.get",
        "tags.item.post",
        "tags.item.put",
        "tags.item.delete"
      ],
      "visible": false
    }
  ]

"permissionSets": [
    {
      "permissionName": "tags.collection.get",
      "displayName": "Tags - get tags collection",
      "description": "Get tags collection"
    },
    {
      "permissionName": "tags.item.manage",
      "displayName": "Tags - manages tag",
      "description": "Manages tags",
      "replaces": [ "tags.item.get", "tags.item.post", "tags.item.put", "tags.item.delete" ]
    },
    {
      "permissionName": "tags.all",
      "displayName": "Tags module - all permissions",
      "description": "Entire set of permissions needed to use the tags module",
      "subPermissions": [
        "tags.collection.get",
        "tags.item.manage"
      ],
      "visible": false
    }
  ],

All four initial permissions have been assigned to a user (user id = "bd397d0d-0bfc-4e01-8c05-8ae19d92bbe4"):

Each of initial permissions has deprecated property set to false, displayName corresponds to the one defined in the ModuleDescriptor and grantedTo refers to permission assignment. The content of tags.item.delete as an example:

Outputs

After the module upgrade procedure the user receives one additional permission to the list of his assigned permissions and nothing is removed

So the replacement is not actually substitutes four initial permissions but only marks them as deprecated

Case 2 - Replace permission set with ordinary permissions

Inputs

note.types.allops permission set is replaced by five existing individual permissions:
- note.types.collection.get,
- note.types.item.get,
- note.types.item.post,
- note.types.item.put,
- note.types.item.delete

Test user has the permission set assigned (user id = "bd397d0d-0bfc-4e01-8c05-8ae19d92bbe4"):

Each of the existing initial permissions as well as the assigned permission set have deprecated property set to false, displayName corresponds to the one defined in the ModuleDescriptor. grantedTo property of the permission set refers to user’s assignment

Outputs

After the module upgrade procedure the user receives NO additional permissions to the list of his assignments permissions and nothing is removed. So although permission set has been replaced by ordinary permissions it remains assigned and what is more interesting the permissions have not been granted to the user:

The only difference in the whole permission set after upgrade is that the replaced permission set marked as deprecated, no changes in the ordinary permissions happened (they haven’t been assigned to the user):

Conclusion

Okapi replacement permission functionality does two things:

marks replaced permission / permission set as deprecated
adds new permission / permission set to a user if the user has been previously granted with replaced permission / permission set. Note: this doesn’t work in all cases

Okapi replacement permission functionality doesn’t do the following:

doesn’t physically delete replaced permission / permission set (performs soft delete), although there is an endpoint to clean-up obsolete permissions: POST /perms/purge-deprecated
doesn’t filter out deprecated permission / permission set from user’s /_self response

To support replacement permission functionality Eureka platform should be able to perform permission replacement as well as permission re-assignment, but since Eureka doesn’t support downgrades it makes no sense for now to keep deprecated permissions: so once a permission or a permission set is replaced it won’t appear in any response, neither response from user’s /_self endpoint nor from complete permissions list (GET /perms/permissions). Permission replacement and re-assignment in terms of Eureka means that the respective capabilities (capability sets) will be created / removed and then assigned / revoked from user or role.

Spike Status: Completed IN Progress On hold

Attachments

Postman collection to play with Okapi replacement functionality:
initial tag’s Module Descriptor:
tag’s Module Descriptor with replacements:
initial note’s Module Descriptor:
note’s Module Descriptor with replacements: