Skip to content

Commit 36bd0fa

Browse files
butonicbutonic
authored
Merge pull request #117 from owncloud/role-management
add role management
2 parents fa49d5f + c275032 commit 36bd0fa

File tree

1 file changed

+278
-0
lines changed

1 file changed

+278
-0
lines changed

‎api/openapi-spec/v1.0.yaml

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ servers:
1111
description: ownCloud Infinite Scale Latest
1212
- url: https://localhost:9200/graph/v1.0
1313
description: ownCloud Infinite Scale Development Setup
14+
# commented for now because it is unrelated to the PR but allows describing and linking to external docs
15+
# tags:
16+
# - name: roleManagement
17+
# description: Manage roles and permissions
18+
# externalDocs:
19+
# url: https://owncloud.dev/ocis/roles-and-permissions
1420
paths:
1521
'/me':
1622
get:
@@ -1986,6 +1992,133 @@ paths:
19861992
$ref: '#/components/schemas/application'
19871993
default:
19881994
$ref: '#/components/responses/error'
1995+
/roleManagement/permissions/roleDefinitions:
1996+
get:
1997+
tags:
1998+
- roleManagement
1999+
summary: List roleDefinitions
2000+
operationId: ListPermissionRoleDefinitions
2001+
description: |
2002+
Get a list of `unifiedRoleDefinition` objects for the permissions provider. This list determines the roles that can be selected when creating sharing invites.
2003+
responses:
2004+
'200':
2005+
description: A list of permission roles than can be used when sharing with users or groups.
2006+
content:
2007+
application/json:
2008+
schema:
2009+
$ref: '#/components/schemas/unifiedRoleDefinition'
2010+
example:
2011+
value:
2012+
- id: 7ccc2a61-9615-4063-a80a-eb7cd8e59d8
2013+
description: "Allows reading the shared file or folder"
2014+
displayName: Viewer
2015+
rolePermissions:
2016+
- allowedResourceActions:
2017+
- libre.graph/driveItem/basic/read
2018+
- libre.graph/driveItem/permissions/read
2019+
- libre.graph/driveItem/upload/create
2020+
condition: "@Subject.objectId Any_of @Resource.grantee"
2021+
weight: 1
2022+
- id: a1c6f73e-482e-4078-a629-bbecb205abb
2023+
description: "Allows reading and writing the shared file or folder"
2024+
displayName: Editor
2025+
rolePermissions:
2026+
- allowedResourceActions:
2027+
- libre.graph/driveItem/standard/allTasks
2028+
condition: "@Subject.objectId Any_of @Resource.grantee"
2029+
weight: 2
2030+
- id: dfa16e02-3d88-45d8-8894-5b33a7df637
2031+
description: "Allows managing a space"
2032+
displayName: Manager
2033+
rolePermissions:
2034+
- allowedResourceActions:
2035+
- libre.graph/drive/standard/allTasks
2036+
condition: "@Subject.objectId Any_of @Resource.grantee"
2037+
weight: 3
2038+
- id: 4916f47e-66d5-49bb-9ac9-748ad00334b
2039+
description: "Allows creating new files"
2040+
displayName: File Drop
2041+
rolePermissions:
2042+
- allowedResourceActions:
2043+
libre.graph/driveItem/upload/create
2044+
condition: "@Subject.objectId Any_of @Resource.grantee"
2045+
weight: 4
2046+
default:
2047+
$ref: '#/components/responses/error'
2048+
/roleManagement/permissions/roleDefinitions/{role-id}:
2049+
get:
2050+
tags:
2051+
- roleManagement
2052+
summary: Get unifiedRoleDefinition
2053+
operationId: GetPermissionRoleDefinition
2054+
description: |
2055+
Read the properties and relationships of a `unifiedRoleDefinition` object.
2056+
parameters:
2057+
- name: role-id
2058+
in: path
2059+
description: 'key: id of roleDefinition'
2060+
required: true
2061+
schema:
2062+
type: string
2063+
x-ms-docs-key-type: roleDefinition
2064+
responses:
2065+
'200':
2066+
description: OK
2067+
content:
2068+
application/json:
2069+
schema:
2070+
$ref: '#/components/schemas/unifiedRoleDefinition'
2071+
examples:
2072+
Viewer:
2073+
value:
2074+
id: read
2075+
description: "Allows reading the shared file or folder"
2076+
displayName: Viewer
2077+
#isBuiltIn: true
2078+
#isEnabled: true
2079+
rolePermissions:
2080+
- allowedResourceActions:
2081+
- libre.graph/driveItem/basic/read
2082+
condition: "@Subject.objectId Any_of @Resource.grantee"
2083+
weight: 1
2084+
Editor:
2085+
value:
2086+
id: write
2087+
description: "Allows reading and writing the shared file or folder"
2088+
displayName: Editor
2089+
#isBuiltIn: true
2090+
#isEnabled: true
2091+
rolePermissions:
2092+
- allowedResourceActions:
2093+
- libre.graph/driveItem/standard/allTasks
2094+
condition: "@Subject.objectId Any_of @Resource.grantee"
2095+
weight: 2
2096+
Manager:
2097+
value:
2098+
id: owner
2099+
description: "Allows managing a space"
2100+
displayName: Manager
2101+
#isBuiltIn: true
2102+
#isEnabled: true
2103+
rolePermissions:
2104+
- allowedResourceActions:
2105+
- libre.graph/drive/standard/allTasks
2106+
condition: "@Subject.objectId Any_of @Resource.grantee"
2107+
weight: 3
2108+
File Drop:
2109+
value:
2110+
id: a-u-u-id or uniquerolename?
2111+
description: "Allows creating new files"
2112+
displayName: File Drop
2113+
#isBuiltIn: false
2114+
#isEnabled: false
2115+
rolePermissions:
2116+
- allowedResourceActions:
2117+
- libre.graph/driveItem/standard/create
2118+
condition: "@Subject.objectId Any_of @Resource.grantee"
2119+
weight: 4
2120+
default:
2121+
$ref: '#/components/responses/error'
19892122
components:
19902123
schemas:
19912124
entity:
@@ -2753,6 +2886,151 @@ components:
27532886
type: array
27542887
items:
27552888
type: string
2889+
unifiedRoleDefinition:
2890+
type: object
2891+
description: |
2892+
A role definition is a collection of permissions in libre graph listing the operations that can be performed
2893+
and the resources against which they can performed.
2894+
properties:
2895+
description:
2896+
description: The description for the unifiedRoleDefinition.
2897+
#description: The description for the unifiedRoleDefinition. Read-only when **isBuiltIn** is `true`.
2898+
type: string
2899+
displayName:
2900+
description: The display name for the unifiedRoleDefinition. Required. Supports $filter (`eq`, `in`).
2901+
#description: The display name for the unifiedRoleDefinition. Read-only when **isBuiltIn** is `true`. Required. Supports $filter (`eq`, `in`).
2902+
type: string
2903+
id:
2904+
description: The unique identifier for the role definition. Key, not nullable, Read-only. Inherited from entity. Supports $filter (`eq`, `in`).
2905+
type: string
2906+
# isBuiltIn:
2907+
# 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`).
2908+
# type: boolean
2909+
# isEnabled:
2910+
# 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`.
2911+
# type: boolean
2912+
# leaving this out as it is already deprecated in msgraph and I do not think we need it right now
2913+
#resourceScopes:
2914+
# type: string
2915+
# description: |
2916+
# List of the scopes or permissions the role definition applies to. Currently only / is supported.
2917+
# Read-only when isBuiltIn is true. DO NOT USE. This will be deprecated soon. Attach scope to role assignment.
2918+
rolePermissions:
2919+
description: List of permissions included in the role.
2920+
#description: List of permissions included in the role. Read-only when **isBuiltIn** is `true`.
2921+
type: array
2922+
items:
2923+
$ref: '#/components/schemas/unifiedRolePermission'
2924+
# templateId:
2925+
# description: |
2926+
# Custom template identifier that can be set when isBuiltIn is `false` but is read-only when isBuiltIn is `true`.
2927+
# This identifier is typically used if one needs an identifier to be the same across different directories.
2928+
# type: string
2929+
# version:
2930+
# description: Indicates version of the role definition. Read-only when **isBuiltIn** is `true`.
2931+
# type: string
2932+
weight:
2933+
description: |
2934+
When presenting a list of roles the weight can be used to order them in a meaningful way.
2935+
Lower weight gets higher precedence. So content with lower weight will come first. If set,
2936+
weights should be non-zero, as 0 is interpreted as an unset weight.
2937+
type: integer
2938+
unifiedRolePermission:
2939+
type: object
2940+
description: |
2941+
Represents a collection of allowed resource actions and the conditions that must be met for the action to be allowed.
2942+
Resource actions are tasks that can be performed on a resource. For example, an application resource may support
2943+
create, update, delete, and reset password actions.
2944+
properties:
2945+
allowedResourceActions:
2946+
description: |
2947+
Set of tasks that can be performed on a resource. Required.
2948+
2949+
The following is the schema for resource actions:
2950+
2951+
```
2952+
{Namespace}/{Entity}/{PropertySet}/{Action}
2953+
```
2954+
2955+
For example: `libre.graph/applications/credentials/update`
2956+
2957+
* *{Namespace}* - The services that exposes the task. For example, all tasks in libre graph use the namespace `libre.graph`.
2958+
* *{Entity}* - The logical features or components exposed by the service in libre graph. For example, `applications`, `servicePrincipals`, or `groups`.
2959+
* *{PropertySet}* - Optional. The specific properties or aspects of the entity for which access is being granted.
2960+
For example, `libre.graph/applications/authentication/read` grants the ability to read the reply URL, logout URL,
2961+
and implicit flow property on the **application** object in libre graph. The following are reserved names for common property sets:
2962+
* `allProperties` - Designates all properties of the entity, including privileged properties.
2963+
Examples include `libre.graph/applications/allProperties/read` and `libre.graph/applications/allProperties/update`.
2964+
* `basic` - Designates common read properties but excludes privileged ones.
2965+
For example, `libre.graph/applications/basic/update` includes the ability to update standard properties like display name.
2966+
* `standard` - Designates common update properties but excludes privileged ones.
2967+
For example, `libre.graph/applications/standard/read`.
2968+
* *{Actions}* - The operations being granted. In most circumstances, permissions should be expressed in terms of CRUD operations or allTasks. Actions include:
2969+
* `create` - The ability to create a new instance of the entity.
2970+
* `read` - The ability to read a given property set (including allProperties).
2971+
* `update` - The ability to update a given property set (including allProperties).
2972+
* `delete` - The ability to delete a given entity.
2973+
* `allTasks` - Represents all CRUD operations (create, read, update, and delete).
2974+
2975+
Following the CS3 API we can represent the CS3 permissions by mapping them to driveItem properties or relations like this:
2976+
| [CS3 ResourcePermission](https://cs3org.github.io/cs3apis/#cs3.storage.provider.v1beta1.ResourcePermissions) | action | comment |
2977+
| ------------------------------------------------------------------------------------------------------------ | ------ | ------- |
2978+
| `stat` | `libre.graph/driveItem/basic/read` | `basic` because it does not include versions or trashed items |
2979+
| `get_quota` | `libre.graph/driveItem/quota/read` | read only the `quota` property |
2980+
| `get_path` | `libre.graph/driveItem/path/read` | read only the `path` property |
2981+
| `move` | `libre.graph/driveItem/path/update` | allows updating the `path` property of a CS3 resource |
2982+
| `delete` | `libre.graph/driveItem/standard/delete` | `standard` because deleting is a common update operation |
2983+
| `list_container` | `libre.graph/driveItem/children/read` | |
2984+
| `create_container` | `libre.graph/driveItem/children/create` | |
2985+
| `initiate_file_download` | `libre.graph/driveItem/content/read` | `content` is the property read when initiating a download |
2986+
| `initiate_file_upload` | `libre.graph/driveItem/upload/create` | `uploads` are a separate property. postprocessing creates the `content` |
2987+
| `add_grant` | `libre.graph/driveItem/permissions/create` | |
2988+
| `list_grant` | `libre.graph/driveItem/permissions/read` | |
2989+
| `update_grant` | `libre.graph/driveItem/permissions/update` | |
2990+
| `remove_grant` | `libre.graph/driveItem/permissions/delete` | |
2991+
| `deny_grant` | `libre.graph/driveItem/permissions/deny` | uses a non CRUD action `deny` |
2992+
| `list_file_versions` | `libre.graph/driveItem/versions/read` | `versions` is a `driveItemVersion` collection |
2993+
| `restore_file_version` | `libre.graph/driveItem/versions/update` | the only `update` action is restore |
2994+
| `list_recycle` | `libre.graph/driveItem/deleted/read` | reading a driveItem `deleted` property implies listing |
2995+
| `restore_recycle_item` | `libre.graph/driveItem/deleted/update` | the only `update` action is restore |
2996+
| `purge_recycle` | `libre.graph/driveItem/deleted/delete` | allows purging deleted `driveItems` |
2997+
2998+
Managing drives would be a different entity. A space manager role could be written as `libre.graph/drive/permission/allTasks`.
2999+
3000+
# microsoft.directory namespace has these built in roles and permissions: https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference
3001+
type: array
3002+
items:
3003+
type: string
3004+
condition:
3005+
description: |
3006+
Optional constraints that must be met for the permission to be effective. Not supported for custom roles.
3007+
3008+
Conditions define constraints that must be met. For example, a requirement that the principal be an owner of the target resource.
3009+
The following are the supported conditions:
3010+
3011+
* Self: `@Subject.objectId == @Resource.objectId`
3012+
* Owner: `@Subject.objectId Any_of @Resource.owners`
3013+
* Grantee: `@Subject.objectId Any_of @Resource.grantee` - does not exist in MS Graph, but we use it to express permissions on shared resources.
3014+
3015+
The following is an example of a role permission with a condition that the principal be the owner of the target resource.
3016+
```json
3017+
"rolePermissions": [
3018+
{
3019+
"allowedResourceActions": [
3020+
"libre.graph/applications/basic/update",
3021+
"libre.graph/applications/credentials/update"
3022+
],
3023+
"condition": "@Subject.objectId Any_of @Resource.owners"
3024+
}
3025+
]
3026+
```
3027+
Conditions aren't supported for custom roles.
3028+
type: string
3029+
# excludedResourceActions:
3030+
# description: Set of tasks that may not be performed on a resource. Not yet supported.
3031+
# type: array
3032+
# items:
3033+
# type: string
27563034
odata.error:
27573035
required:
27583036
- error

0 commit comments

Comments
 (0)