Specification for Graph Permissions Model #190

darrelmiller · 2022-07-27T02:29:38Z

No description provided.

specs/permissions.md

PetRich-MSFT · 2022-07-27T17:48:04Z

specs/permissions.md

+```json
+"paths": {
+  "/me/activities/{id}": {
+    "leastPrivilegePath": ["DelegateedWork", "DelegatedPersonal"],


Suggested change

"leastPrivilegePath": ["DelegateedWork", "DelegatedPersonal"],

"leastPrivilegePath": ["DelegatedWork", "DelegatedPersonal"],

PetRich-MSFT · 2022-07-27T17:50:33Z

specs/permissions.md

+(User.Read | User.Read.All) & Group.Read
+```
+
+### includedProperties


May want to call out the behavior when includeProperties and excludeProperties are not specified. I assume includeProperties defaults to all properties if not specified, and excludeProperties defaults to no properties if not specified

PetRich-MSFT · 2022-07-27T17:52:53Z

specs/permissions.md

+### methods
+The "methods" member is a REQUIRED array of strings that represent the HTTP methods supported by the paths in this pathSet object.
+
+### paths


Should provide an example of how the URI template works

PetRich-MSFT · 2022-07-27T17:55:19Z

specs/permissions.md

+The "methods" member is a REQUIRED array of strings that represent the HTTP methods supported by the paths in this pathSet object.
+
+### paths
+The "paths" member is a REQUIRED object whose keys contain a simplified URI template to identify the resources protected by this permission object.


How do we distinguish between Read and Read.All for paths permissions?

Read and Read.All is a convention that Microsoft Graph has that indicates whether you can access any resource of the specified type, or just "yours". It is a scoping mechanism that is opaque to this spec. The model this spec describes currently does not have the capability to map permissions to caller identity. At this time we are only trying to map claims to a URI template that we are primarily using to verify a user has consented an application to access data. If you have any ideas how to describe user authZ as well, I am all ears.

PetRich-MSFT · 2022-07-27T17:57:57Z

specs/permissions.md

+TBD
+
+### ownerEmail
+The "ownerEmail" member is a REQUIRED string that provides a contact mechanism for communicating with the owner of the permission. It is important that owners of permissions are aware when new paths are added to an existing permission.


Suggestion: Require this to be a DL/Mail enabled security group

specs/permissions.md

PetRich-MSFT · 2022-07-27T18:00:56Z

specs/permissions.md

+```
+
+### leastPrivilegePath
+The "leastPrivilegePath" member is an array of strings that identify the schemes for which this permission is the least privilege permission for accessing the path.


Question: can this not be derived automatically based on the set of paths and the privilegeLevel property?

That is what I originally thought and then someone convinced me that is not the case. Let me try and remember what the reasoning was. Nope, can't remember. I will go back to the person and get them to remind me and I'll update this doc. Thanks for the call out.

Co-authored-by: Peter Richards <[email protected]>

darrelmiller · 2022-09-01T14:32:00Z

Add a provisioningInfo object. It will contain internal information:
owner (description, _
deploymentEnvironments
resourceAppId
privileged
hidden

Add Id into the main part of the spec.

…/msgraph-metadata into dm/permissionspec

wandeg · 2022-09-06T11:41:22Z

specs/permissions.md

+## Introduction
+Protecting data in HTTP APIs from unauthorized access is critical. One technique to do this is by associating permissions with resources and requiring API callers to present a bearer token that can prove what permissions have been consented to the caller. This document describes a JSON based document format that can store the relationships between permission and resource.
+
+In this design, the permission is the primary concept and the resources that are controlled are associated to the permission. The relationship is many-to-many and so could be modelled in an inverted way with resources being assigned the permissions. However, the permission centric view was chosen to emphasise to the author of the permission the scope of control being assigned to the permission.  It is the opposite view to how this information will often be used in tooling. Tooling will need to invert the model to identify what permissions could be used to access a resource. The trade-off is the tooling writers will need to do more for the benefit of permission authors. Application users and administrators are increasingly asking for the ability to consent to more fine-grained permissions that are limited in the number of resources they can access via a single permission. This limits the ability of applications performing unintended or malicious actions on behalf of users. Models that present a resource centric view of permissions obscure the total scope of the permission and lead to the creation of permissions that create unnecessary risk.   


Suggested change

In this design, the permission is the primary concept and the resources that are controlled are associated to the permission. The relationship is many-to-many and so could be modelled in an inverted way with resources being assigned the permissions. However, the permission centric view was chosen to emphasise to the author of the permission the scope of control being assigned to the permission. It is the opposite view to how this information will often be used in tooling. Tooling will need to invert the model to identify what permissions could be used to access a resource. The trade-off is the tooling writers will need to do more for the benefit of permission authors. Application users and administrators are increasingly asking for the ability to consent to more fine-grained permissions that are limited in the number of resources they can access via a single permission. This limits the ability of applications performing unintended or malicious actions on behalf of users. Models that present a resource centric view of permissions obscure the total scope of the permission and lead to the creation of permissions that create unnecessary risk.

In this design, the permission is the primary concept and the resources that are controlled are associated to the permission. The relationship is many-to-many and so could be modelled in an inverted way with resources being assigned the permissions. However, the permission centric view was chosen to emphasise to the author of the permission the scope of control being assigned to the permission. It is the opposite view to how this information will often be used in tooling. Tooling will need to invert the model to identify what permissions could be used to access a resource. The trade-off is the tooling writers will need to do more for the benefit of permission authors. Application users and administrators are increasingly asking for the ability to consent to more fine-grained permissions that are limited in the number of resources they can access via a single permission. This limits the ability of applications performing unintended or malicious actions on behalf of users. Models that present a resource centric view of permissions obscure the total scope of the permission and lead to the creation of permissions that create unnecessary risk.

Minor: spacing

wandeg · 2022-09-06T11:46:22Z

specs/permissions.md

+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
+
+## <a name="permissionsObject"></a> Permissions JSON Object
+The canonical model for a permissions document is a JSON [JSON] object. When serialized in a JSON document, that format is identified with the "application/permissions+json" media type.


Should we have a url for [JSON]?

wandeg · 2022-09-06T13:05:35Z

specs/permissions.md

+The relationship between a permission and the resources it controls have a number of attributes including the HTTP method being granted, the type of security scheme being used, and properties of the resource being protected.  Ideally these relationships would be consistent for all resources controlled by a permission.  However, in reality that is not always the case. This model enables modelling the paths as sets of paths that do behave consistently and a permission can have multiple sets of paths. This approach minimizes the duplication of relationship attributes and encourages consistency in relationship design due to the overhead of managing distinct path sets. 
+
+## Notational Conventions
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.


Should we have urls to the RFCs provided here?

Corrected two grammatical error for ease of readability.

Update permissions.md

darrelmiller added 4 commits July 26, 2022 22:28

First crack at permissions spec

2bc1a19

Tried to fix JSON formatting

fd5f461

Tried to fix JSON formatting again

95a3711

Updated with diagram

fb5ed70

darrelmiller force-pushed the dm/permissionspec branch from 197254c to fb5ed70 Compare July 27, 2022 15:01

PetRich-MSFT reviewed Jul 27, 2022

View reviewed changes

specs/permissions.md Outdated Show resolved Hide resolved

PetRich-MSFT reviewed Jul 27, 2022

View reviewed changes

specs/permissions.md Outdated Show resolved Hide resolved

PetRich-MSFT reviewed Jul 27, 2022

View reviewed changes

darrelmiller and others added 4 commits July 27, 2022 14:16

renamed leastPrivilegedPath

e382eee

Added introduction

f6a3f96

Update specs/permissions.md

d684ba9

Co-authored-by: Peter Richards <[email protected]>

Update specs/permissions.md

e16b7cd

Co-authored-by: Peter Richards <[email protected]>

darrelmiller added 2 commits September 2, 2022 16:17

Updated to add provisioningInfo object

052d84d

Merge branch 'dm/permissionspec' of https://github.com/microsoftgraph…

0b7c116

…/msgraph-metadata into dm/permissionspec

wandeg reviewed Sep 6, 2022

View reviewed changes

njaci1 and others added 2 commits February 7, 2023 12:33

Update permissions.md

ae03c13

Corrected two grammatical error for ease of readability.

Merge pull request #268 from njaci1/patch-1

d710812

Update permissions.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Specification for Graph Permissions Model #190

Specification for Graph Permissions Model #190

darrelmiller commented Jul 27, 2022

PetRich-MSFT Jul 27, 2022

PetRich-MSFT Jul 27, 2022

PetRich-MSFT Jul 27, 2022

PetRich-MSFT Jul 27, 2022

darrelmiller Aug 14, 2022

PetRich-MSFT Jul 27, 2022

PetRich-MSFT Jul 27, 2022

darrelmiller Aug 14, 2022

darrelmiller commented Sep 1, 2022

wandeg Sep 6, 2022

wandeg Sep 6, 2022

wandeg Sep 6, 2022

	"leastPrivilegePath": ["DelegateedWork", "DelegatedPersonal"],
	"leastPrivilegePath": ["DelegatedWork", "DelegatedPersonal"],

Specification for Graph Permissions Model #190

Are you sure you want to change the base?

Specification for Graph Permissions Model #190

Conversation

darrelmiller commented Jul 27, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

darrelmiller commented Sep 1, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment