Write documentation for roles & permissions concept

[kulmann]

Write documentation for roles & permissions concept. This is intended to be a living document and it should reflect decisions made during the development process. The end result being a document in a state that mirrors the settings service functionality regarding roles and permissions.

[refs]

Preliminary draft:

Roles and Permissions

Roles and Permissions live in the ocis-settings service. There is a set of basic operations that are defined on the settings service regarding roles and permissions, and these are:

• ListRoles
• ListRoleAssignments
• AssignRoleToUser
• RemoveRoleFromUser

The scope of roles and permissions is only inside the ocis-extensions framework. Do not confuse with Reva grants. Roles and permissions do not handle actions on shared resources. i.e: an admin cannot restrict access to users on a given folder based on roles defined in this service.

The intended usage of Roles and Permissions can be clarified with an example: An admin user wants to configure so that only users with the role USER can update their name. This means that only users with roles ADMIN and USER (since a user with the ADMIN role contains the role USER) will be allowed to update such setting on the ocis-accounts extension. In this scenario, users with the role GUEST will not be allowed to update such option.

Assigning a role to a user

When assigning a role to a user an assignment is created. An assignment relates an account with a role.

Design

Roles and Permissions was built on top of settings bundles, instead of building a service that exclusively deals with them. This API reuses most of what has already been implemented for the settings bundles and extends it with roles and permissions. It does so by adding the TYPE_ROLE to the definition of a SettingsBundle and also a value of type PermissionSetting to the Setting message type.

When an extension starts, it registers its roles and permissions (as well as the settings bundles, in fact, roles and permissions are just another settings bundle of type ROLE) to the ocis-settings service (rendering ocis-settings a mandatory service to start on the runtime) that records which roles are allowed to change the extension behavior.

Testing

In order to retrieve Roles and Permissions for a given user, these need to be assigned. Let's do so using the API and the micro command. By default, no assignments are created, so we would need to create a new one using the settings service:

Request:

micro call com.owncloud.api.settings RoleService.AssignRoleToUser '{"assignment": {"account_uuid": "4c510ada-c86b-4815-8820-42cdf82c3d51", "role_id": "71881883-1768-46bd-a24d-a356a2afdf7f"}}'

Response:

{
        "assignment": {
                "id": "9490d020-cfb2-46d8-804c-6b6d088adb62",
                "account_uuid": "4c510ada-c86b-4815-8820-42cdf82c3d51",
                "role_id": "71881883-1768-46bd-a24d-a356a2afdf7f"
        }
}

Note: The role_ids for default roles are exposed as svc.BundleUUIDRole(Admin|User|Guest) in ocis-settings. To be sure of having the correct role id, while using the filesystem driver: cat /var/tmp/ocis-settings/bundles/* | jq . and look for those bundles with TYPE: ROLE.

Now let us retrieve the assignments for the user with ID 4c510ada-c86b-4815-8820-42cdf82c3d51:

Request:

micro call com.owncloud.api.settings RoleService.ListRoleAssignments '{"account_uuid": "4c510ada-c86b-4815-8820-42cdf82c3d51"}'

Response:

{
        "assignments": [
                {
                        "id": "9490d020-cfb2-46d8-804c-6b6d088adb62",
                        "account_uuid": "4c510ada-c86b-4815-8820-42cdf82c3d51",
                        "role_id": "71881883-1768-46bd-a24d-a356a2afdf7f"
                }
        ]
}

The ListRoles method SHOULD list the entire set of permissions for the queried user per extension.

Filesystem driver

Overview of the ocis-settings extension tree when using the filesystem as a storage backend for settings. Everything in the ocis-settings service is identified by a UUID.

/var/tmp/ocis-settings
├── bundles
│   ├── 2a506de7-99bd-4f0d-994e-c38e72c28fd9.json
│   ├── 38071a68-456a-4553-846a-fa67bf5596cc.json
│   ├── 71881883-1768-46bd-a24d-a356a2afdf7f.json
│   └── d7beeea8-8ff4-406b-8fb6-ab2dd81e6b11.json
└── role-assignments
    ├── 721a5cce-a750-47b2-93c2-5decbab1aa87.json
    ├── 9490d020-cfb2-46d8-804c-6b6d088adb62.json
    └── cf1b10a9-ba30-432e-b3da-4f6be71bcfb1.json

/var/tmp/ocis-settings/bundles

The bundles directory stores information related to the SettingsBundle message type (see settings.proto for an updated version of the message). For the current version, a SettingsBundle is declared as:

message SettingsBundle {
  enum Type {
    TYPE_UNKNOWN = 0;
    TYPE_DEFAULT = 1;
    TYPE_ROLE = 2;
  }
  string id = 1;
  string name = 2;
  Type type = 3;
  string extension = 4;
  string display_name = 5;
  repeated Setting settings = 6;
  Resource resource = 7;
}

As all roles are by definition settings bundles, the roles are located in the bundles directory, alongside all other settings bundles.

/var/tmp/ocis-settings/role-assignments

The contents of this directory are a tuple of account_uuid + role_id. Essentially binding a user with a role and set of permissions.

{
  "id": "721a5cce-a750-47b2-93c2-5decbab1aa87",
  "accountUuid": "4c510ada-c86b-4815-8820-42cdf82c3d51",
  "roleId": "d7beeea8-8ff4-406b-8fb6-ab2dd81e6b11"
}

Vocabulary

Role: A named set of permissions.

Permission: An operation that can be done on a constraint. i.e: "update my language on the files extension".

Assignment: Tuple of account_uuid + role_id. Internal.

/var/tmp/ocis-settings/values

The values directory contains user defined data that resulted from saving a setting. Continuing the example from above, there would be one json file for any name that was set by a user. Since roles & permissions are declared in settings bundles, values are not relevant for roles & permissions.

TODO

• insert diagrams: https://cloud.owncloud.com/index.php/s/qcq08xjN9WuSZKS
• document the process step-by-step:
  • start an extension that registers its settings bundle on the settings service.
  • create values for the settings bundle for the given extension.
  • define roles.
  • use defined roles on existing user accounts.

[kulmann]

Changes:

• added a note on the exposed uuids of the default roles
• split the micro calls into request and response
• added details about bundles (below the protobuf message)
• added a short paragraph on values (at the bottom)

[refs]

User stories:

• As an admin I want to be able to assign and manage roles to users.
• As an admin I want to be able to define roles on a per extension base:
  • i.e: I want to create a new role only valid for the XXXXXX extension.

Open questions:

• If we decide to create a superset of roles on top of Reva grants we need to clearly define how are we going to handle them:
  • do ocis-settings roles take precedence?
    • this would mean if user A shares a folder with user B with RW permission but we have a role on the files app that states user B has only R permissions, which one takes precedence?
  • mapping Reva grants translates into glue code and defining which combination of grant permissions constitute a R only on ocis-settings.

[refs]

@kulmann ☝️

[refs]

• Can any extension create as many roles as it wants?
• We need to validate extension name
• When fetching values:
  • user value present, system value not: return user value
  • user value not present, system value present: return system value
  • user value present, system value present: return user value (user takes precedence)

[butonic]

@refs @kulmann reading the draft I stumbled over

... (since a user with the ADMIN role contains the role USER) ...

This implies either role inheritance or that a user can have multiple roles. Can you clarify the text?

[refs]

@butonic that's correct. I thought of role inheritance as well, which with this model is a bit hard to map but it was something that was mentioned and I remembered it, therefore added to the doc. It is another point that we'd need to discuss for the MVP.

[kulmann]

For the mvp I‘d advise against role inheritance. A user can have as many roles as you want - data model wise. As long as we’re still learning about requirements it makes sense to compose each of the default roles with their respective full set of permissions. For the UI we agreed to only allow single role assignment.

Having multiple roles only makes sense then when we‘re coming up with e.g. group roles. Which is technically possible already.

[phil-davis]

@kulmann @refs this is an old issue that was transferred from the archived ocis-settings repo a few weeks ago.
Please close if no longer relevant.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 10 days if no further activity occurs. Thank you for your contributions.

[refs]

@kulmann @refs this is an old issue that was transferred from the archived ocis-settings repo a few weeks ago.
Please close if no longer relevant.

This one is still relevant 👍

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 10 days if no further activity occurs. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 10 days if no further activity occurs. Thank you for your contributions.