add roleDefinitions

Signed-off-by: Jörn Friedrich Dreyer <jfd@butonic.de>

api/openapi-spec/v1.0.yaml

@@ -402,8 +402,8 @@ paths:
                 properties:
                   '@libre.graph.permissions.roles.allowedValues':
                     type: array
-                    #items:
-                      #TODO $ref: '#/components/schemas/sharingRole'
+                    items:
+                      $ref: '#/components/schemas/unifiedRoleDefinition'
                   value:
                     type: array
                     items:
@@ -2390,6 +2390,95 @@ paths:
                 $ref: '#/components/schemas/application'
         default:
           $ref: '#/components/responses/error'
+  # TODO hm the permissions segment is redundant when it comes to actual role definitions. that is part of the permission condition, is it not? ... hm
+  /roleManagement/permissions/roleDefinitions:
+    get:
+      tags:
+        - roleManagement
+      summary: List roleDefinitions
+      operationId: ListPermissionRoleDefinitions
+      description: |
+        Get a list of `unifiedRoleDefinition` objects for the permissions provider.
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/unifiedRoleDefinition'
+        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:
@@ -3254,6 +3343,116 @@ 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. Read-only when **isBuiltIn** is `true`.
+          type: string
+        displayName:
+          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. 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).
+          # 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