Skip to content

Commit

Permalink
add role management
Browse files Browse the repository at this point in the history 
Signed-off-by: Jörn Friedrich Dreyer <jfd@butonic.de>
  • Loading branch information
@butonic
butonic committed Oct 4, 2023
1 parent fa49d5f commit ea9fd26
Showing 1 changed file with 264 additions and 0 deletions.
264 changes: 264 additions & 0 deletions api/openapi-spec/v1.0.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ servers:
description: ownCloud Infinite Scale Latest
- url: https://localhost:9200/graph/v1.0
description: ownCloud Infinite Scale Development Setup
# commented for now because it is unrelated to the PR but allows describing and linking to external docs
# tags:
# - name: roleManagement
# description: Manage roles and permissions
# externalDocs:
# url: https://owncloud.dev/ocis/roles-and-permissions
paths:
'/me':
get:
Expand Down Expand Up @@ -1986,6 +1992,125 @@ paths:
$ref: '#/components/schemas/application'
default:
$ref: '#/components/responses/error'
/roleManagement/permissions/roleDefinitions:
get:
tags:
- roleManagement
summary: List roleDefinitions
operationId: ListPermissionRoleDefinitions
description: |
Get a list of `unifiedRoleDefinition` objects for the permissions provider. This list determines the roles that can be selected when creating sharing invites.
responses:
'200':
description: A list of permission roles than can be used when sharing with users or groups.
content:
application/json:
schema:
$ref: '#/components/schemas/unifiedRoleDefinition'
example:
value:
- id: 7ccc2a61-9615-4063-a80a-eb7cd8e59d8
description: "Allows reading the shared file or folder"
displayName: Viewer
rolePermissions:
- allowedResourceActions:
- libre.graph/driveItem/basic/read
- libre.graph/driveItem/permissions/read
- libre.graph/driveItem/upload/create
condition: "@Subject.objectId Any_of @Resource.grantee"
- id: a1c6f73e-482e-4078-a629-bbecb205abb
description: "Allows reading and writing the shared file or folder"
displayName: Editor
rolePermissions:
- allowedResourceActions:
- libre.graph/driveItem/standard/allTasks
condition: "@Subject.objectId Any_of @Resource.grantee"
- id: dfa16e02-3d88-45d8-8894-5b33a7df637
description: "Allows managing a space"
displayName: Manager
rolePermissions:
- allowedResourceActions:
- libre.graph/drive/standard/allTasks
condition: "@Subject.objectId Any_of @Resource.grantee"
- id: 4916f47e-66d5-49bb-9ac9-748ad00334b
description: "Allows creating new files"
displayName: File Drop
rolePermissions:
- allowedResourceActions:
libre.graph/driveItem/upload/create
condition: "@Subject.objectId Any_of @Resource.grantee"
default:
$ref: '#/components/responses/error'
/roleManagement/permissions/roleDefinitions/{role-id}:
get:
tags:
- roleManagement
summary: Get unifiedRoleDefinition
operationId: GetPermissionRoleDefinition
description: |
Read the properties and relationships of a `unifiedRoleDefinition` object.
parameters:
- name: role-id
in: path
description: 'key: id of roleDefinition'
required: true
schema:
type: string
x-ms-docs-key-type: roleDefinition
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/unifiedRoleDefinition'
examples:
Viewer:
value:
id: read
description: "Allows reading the shared file or folder"
displayName: Viewer
#isBuiltIn: true
#isEnabled: true
rolePermissions:
- allowedResourceActions:
- libre.graph/driveItem/basic/read
condition: "@Subject.objectId Any_of @Resource.grantee"
Editor:
value:
id: write
description: "Allows reading and writing the shared file or folder"
displayName: Editor
#isBuiltIn: true
#isEnabled: true
rolePermissions:
- allowedResourceActions:
- libre.graph/driveItem/standard/allTasks
condition: "@Subject.objectId Any_of @Resource.grantee"
Manager:
value:
id: owner
description: "Allows managing a space"
displayName: Manager
#isBuiltIn: true
#isEnabled: true
rolePermissions:
- allowedResourceActions:
- libre.graph/drive/standard/allTasks
condition: "@Subject.objectId Any_of @Resource.grantee"
File Drop:
value:
id: a-u-u-id or uniquerolename?
description: "Allows creating new files"
displayName: File Drop
#isBuiltIn: false
#isEnabled: false
rolePermissions:
- allowedResourceActions:
- libre.graph/driveItem/standard/create
condition: "@Subject.objectId Any_of @Resource.grantee"
default:
$ref: '#/components/responses/error'
components:
schemas:
entity:
Expand Down Expand Up @@ -2753,6 +2878,145 @@ components:
type: array
items:
type: string
unifiedRoleDefinition:
type: object
description: |
A role definition is a collection of permissions in libre graph listing the operations that can be performed
and the resources against which they can performed.
properties:
description:
description: The description for the unifiedRoleDefinition.
#description: The description for the unifiedRoleDefinition. Read-only when **isBuiltIn** is `true`.
type: string
displayName:
description: The display name for the unifiedRoleDefinition. Required. Supports $filter (`eq`, `in`).
#description: The display name for the unifiedRoleDefinition. Read-only when **isBuiltIn** is `true`. Required. Supports $filter (`eq`, `in`).
type: string
id:
description: The unique identifier for the role definition. Key, not nullable, Read-only. Inherited from entity. Supports $filter (`eq`, `in`).
type: string
# isBuiltIn:
# description: Flag indicating whether the role definition is part of the default set included in libre graph or a custom definition. Read-only. Supports $filter (`eq`, `in`).
# type: boolean
# isEnabled:
# description: Flag indicating whether the role is enabled for assignment. If `false` the role is not available for assignment. Read-only when **isBuiltIn** is `true`.
# type: boolean
# leaving this out as it is already deprecated in msgraph and I do not think we need it right now
#resourceScopes:
# type: string
# description: |
# List of the scopes or permissions the role definition applies to. Currently only / is supported.
# Read-only when isBuiltIn is true. DO NOT USE. This will be deprecated soon. Attach scope to role assignment.
rolePermissions:
description: List of permissions included in the role.
#description: List of permissions included in the role. Read-only when **isBuiltIn** is `true`.
type: array
items:
$ref: '#/components/schemas/unifiedRolePermission'
# templateId:
# description: |
# Custom template identifier that can be set when isBuiltIn is `false` but is read-only when isBuiltIn is `true`.
# This identifier is typically used if one needs an identifier to be the same across different directories.
# type: string
# version:
# description: Indicates version of the role definition. Read-only when **isBuiltIn** is `true`.
# type: string
unifiedRolePermission:
type: object
description: |
Represents a collection of allowed resource actions and the conditions that must be met for the action to be allowed.
Resource actions are tasks that can be performed on a resource. For example, an application resource may support
create, update, delete, and reset password actions.
properties:
allowedResourceActions:
description: |
Set of tasks that can be performed on a resource. Required.
The following is the schema for resource actions:
```
{Namespace}/{Entity}/{PropertySet}/{Action}
```
For example: `libre.graph/applications/credentials/update`
* *{Namespace}* - The services that exposes the task. For example, all tasks in libre graph use the namespace `libre.graph`.
* *{Entity}* - The logical features or components exposed by the service in libre graph. For example, `applications`, `servicePrincipals`, or `groups`.
* *{PropertySet}* - Optional. The specific properties or aspects of the entity for which access is being granted.
For example, `libre.graph/applications/authentication/read` grants the ability to read the reply URL, logout URL,
and implicit flow property on the **application** object in libre graph. The following are reserved names for common property sets:
* `allProperties` - Designates all properties of the entity, including privileged properties.
Examples include `libre.graph/applications/allProperties/read` and `libre.graph/applications/allProperties/update`.
* `basic` - Designates common read properties but excludes privileged ones.
For example, `libre.graph/applications/basic/update` includes the ability to update standard properties like display name.
* `standard` - Designates common update properties but excludes privileged ones.
For example, `libre.graph/applications/standard/read`.
* *{Actions}* - The operations being granted. In most circumstances, permissions should be expressed in terms of CRUD operations or allTasks. Actions include:
* `create` - The ability to create a new instance of the entity.
* `read` - The ability to read a given property set (including allProperties).
* `update` - The ability to update a given property set (including allProperties).
* `delete` - The ability to delete a given entity.
* `allTasks` - Represents all CRUD operations (create, read, update, and delete).
Following the CS3 API we can represent the CS3 permissions by mapping them to driveItem properties or relations like this:
| [CS3 ResourcePermission](https://cs3org.github.io/cs3apis/#cs3.storage.provider.v1beta1.ResourcePermissions) | action | comment |
| ------------------------------------------------------------------------------------------------------------ | ------ | ------- |
| `stat` | `libre.graph/driveItem/basic/read` | `basic` because it does not include versions or trashed items |
| `get_quota` | `libre.graph/driveItem/quota/read` | read only the `quota` property |
| `get_path` | `libre.graph/driveItem/path/read` | read only the `path` property |
| `move` | `libre.graph/driveItem/path/update` | allows updating the `path` property of a CS3 resource |
| `delete` | `libre.graph/driveItem/standard/delete` | `standard` because deleting is a common update operation |
| `list_container` | `libre.graph/driveItem/children/read` | |
| `create_container` | `libre.graph/driveItem/children/create` | |
| `initiate_file_download` | `libre.graph/driveItem/content/read` | `content` is the property read when initiating a download |
| `initiate_file_upload` | `libre.graph/driveItem/upload/create` | `uploads` are a separate property. postprocessing creates the `content` |
| `add_grant` | `libre.graph/driveItem/permissions/create` | |
| `list_grant` | `libre.graph/driveItem/permissions/read` | |
| `update_grant` | `libre.graph/driveItem/permissions/update` | |
| `remove_grant` | `libre.graph/driveItem/permissions/delete` | |
| `deny_grant` | `libre.graph/driveItem/permissions/deny` | uses a non CRUD action `deny` |
| `list_file_versions` | `libre.graph/driveItem/versions/read` | `versions` is a `driveItemVersion` collection |
| `restore_file_version` | `libre.graph/driveItem/versions/update` | the only `update` action is restore |
| `list_recycle` | `libre.graph/driveItem/deleted/read` | reading a driveItem `deleted` property implies listing |
| `restore_recycle_item` | `libre.graph/driveItem/deleted/update` | the only `update` action is restore |
| `purge_recycle` | `libre.graph/driveItem/deleted/delete` | allows purging deleted `driveItems` |
Managing drives would be a different entity. A space manager role could be written as `libre.graph/drive/permission/allTasks`.
# microsoft.directory namespace has these built in roles and permissions: https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference
type: array
items:
type: string
condition:
description: |
Optional constraints that must be met for the permission to be effective. Not supported for custom roles.
Conditions define constraints that must be met. For example, a requirement that the principal be an owner of the target resource.
The following are the supported conditions:
* Self: `@Subject.objectId == @Resource.objectId`
* Owner: `@Subject.objectId Any_of @Resource.owners`
* Grantee: `@Subject.objectId Any_of @Resource.grantee` - does not exist in MS Graph, but we use it to express permissions on shared resources.
The following is an example of a role permission with a condition that the principal be the owner of the target resource.
```json
"rolePermissions": [
{
"allowedResourceActions": [
"libre.graph/applications/basic/update",
"libre.graph/applications/credentials/update"
],
"condition": "@Subject.objectId Any_of @Resource.owners"
}
]
```
Conditions aren't supported for custom roles.
type: string
# excludedResourceActions:
# description: Set of tasks that may not be performed on a resource. Not yet supported.
# type: array
# items:
# type: string
odata.error:
required:
- error
Expand Down

0 comments on commit ea9fd26

Please sign in to comment.