Skip to content

Commit 2bc1a19

Browse files
darrelmillerdarrelmiller
committed
First crack at permissions spec
1 parent fcf1ec0 commit 2bc1a19

File tree

1 file changed

+283
-0
lines changed

1 file changed

+283
-0
lines changed

‎specs/permissions.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# Permissions for HTTP APIs
2+
3+
## Abstract
4+
This document defines a "permission" object and "permissions" document that describes identifiers that can be used by security claims to grant access to HTTP resources.
5+
6+
## Introduction
7+
8+
## Notational Conventions
9+
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.
10+
11+
## <a name="permissionsObject"></a> Permissions JSON Object
12+
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.
13+
14+
```json
15+
{
16+
  "permissions": {
17+
    "PrintSettings.Read.All": {
18+
      "schemes": {
19+
        "DelegatedWork": {
20+
          "type": "DelegatedWork",
21+
          "description": "Allow signed in user to read print settings",
22+
        }
23+
      },
24+
      "pathSets": [
25+
        {
26+
          "schemes": ["DelegatedWork"],
27+
          "methods": ["GET"],
28+
          "paths": {
29+
            "/print/settings": {}
30+
          }
31+
        }
32+
      ]
33+
    }
34+
}
35+
```
36+
In this example, the claim "PrintSettings.Read.All" is required when using the "DelegatedWork" security scheme to access the resource "/print/settings" using the "GET" method.
37+
38+
### permissions
39+
The "permissions" member is a JSON object whose members permission objects. The key of each member is the claim identifier used for the [Permission Object](#permissionObject)
40+
41+
42+
## <a name="permissionObject"></a>Permission Object
43+
44+
### note
45+
The "note" member is a freeform string that provides additional details at about the permission that cannot be determined from the other members of the permission object.
46+
47+
### alsoRequires
48+
The "alsoRequires" member is logical expression of permissions that must be presented as claims alongside the current permission.
49+
50+
```
51+
(User.Read | User.Read.All) & Group.Read
52+
```
53+
54+
### implicit
55+
The "implicit" member is a boolean value that indicates that the current permission object is implied. The default value is "false". This member us usually set to "true" in combination with a "alsoRequires" expression.
56+
57+
> Note: This member enables support for the Microsoft Graph create subscription endpoint and the Search query endpoint.
58+
59+
### schemes
60+
The "schemes" member is a REQUIRED JSON object whose members are [Scheme objects](#schemeObject) supported by the permission. The key of each member is an identifier of the scheme and the value is a [Scheme object](#schemeObject) that contains descriptions of the permission within the scheme.
61+
62+
### pathSets
63+
The "pathSets" member is a REQUIRED JSON Array. Each element of the array is a [pathSet object](#pathSetObject).
64+
65+
### isHidden
66+
The "isHidden" member is a boolean value that indicates if a permission should be publicly usable in the API.
67+
68+
### requiredEnvironments
69+
The "requiredEnvironments" member is an array of strings that identifies the deployment environments in which the permission SHOULD be supported. When this member is not present, support for all environments is implied.
70+
71+
### privilegeLevel
72+
The "privilegeLevel" member value provides a hint as to the risks of consenting this permissions. Valid values include: low, medium and high.
73+
74+
### appIdForConditionalAccessChecks
75+
TBD
76+
77+
### ownerEmail
78+
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.
79+
80+
## <a name="pathSetObject"></a>PathSet Object
81+
A pathSet object identifies a set of paths that are accessible via the identified HTTP methods and schemes. Ideally, a permission object contains a single pathSet object. This indicates that all paths protected by the permission support the same HTTP methods and and schemes. In practice there are cases where support is not uniform. Distinct pathSet objects can be created to separate the paths with varying support.
82+
83+
> Note: The design chosen was intentional to encourage permission creators to ensure support for methods and schemes is as consistent as possible. This produces a better developer experience for API consumers.
84+
85+
```json
86+
      "pathSets": [
87+
        {
88+
          "schemes": ["DelegatedWork"],
89+
          "methods": ["GET"],
90+
          "paths": {
91+
            "/print/settings": {}
92+
          }
93+
        },
94+
        {
95+
          "schemes": ["Application"],
96+
          "methods": ["GET,POST"],
97+
          "paths": {
98+
            "/print/settings": {}
99+
          }
100+
        }
101+
      ]
102+
```
103+
104+
### schemes
105+
The "schemes" member is a REQUIRED array of strings that reference the schemes defined in the [permission object](#permissionObject) that are supported by the paths in this pathSet object.
106+
107+
### methods
108+
The "methods" member is a REQUIRED array of strings that represent the HTTP methods supported by the paths in this pathSet object.
109+
110+
### paths
111+
The "paths" member is a REQUIRED object whose keys contain a simplified URI template to identify the resources protected by this permission object.
112+
113+
## <a name="schemeObject"></a>Scheme Object
114+
The scheme object has members that describe the permission within the context of the scheme. Additional members provide behavioral constraints of the permission when used with the scheme.
115+
116+
```json
117+
"schemes": {
118+
"DelegatedWork": {
119+
"adminDisplayName": "Read and write app activity to users'activity feed",
120+
"adminDescription": "Allows the app to read and report the signed-in user's activity in the app.",
121+
"consentDisplayName": "Read and write app activity to users'activity feed",
122+
"consentDescription": "Allows the app to read and report the signed-in user's activity in the app.",
123+
"requiresAdminConsent": true
124+
},
125+
"DelegatedPersonal": {
126+
"type": "DelegatedPersonal",
127+
"consentDisplayName": "Read and write app activity to users'activity feed",
128+
"consentDescription": "Allows the app to read and report the signed-in user's activity in the app."
129+
},
130+
"Application": {
131+
"type": "Application",
132+
"adminDisplayName": "Read and write app activity to users' activity feed",
133+
"adminDescription": "Allows the app to read and report the signed-in user's activity in the app.",
134+
}
135+
```
136+
### adminDisplayName
137+
The "adminDisplayName" member is a string that provides a short permission name that considers the current scheme and the perspective of a resource administrator.
138+
139+
### adminDescription
140+
The "adminDescription" member is a string that describes the permission considering the current scheme from the perspective of a resource administrator.
141+
142+
### consentDisplayName
143+
The "consentDisplayName" member is a REQUIRED string that provides a short permission name that considers the current scheme and the perspective of the user consenting an application.
144+
145+
### consentDescription
146+
The "consentDescription" member is a REQUIRED string that describes the permission considering the current scheme from the perspective of the user consenting an application.
147+
148+
### requiresAdminConsent
149+
The "requiresAdminConsent" member is a boolean value with a default value of false. When true, this permission can only be consented by an adminstrator.
150+
151+
## <a name="pathObject"></a>Path Object
152+
The path object contains properties that affect how the permission object controls access to resource identified by the key of the path object.
153+
154+
```json
155+
"paths": {
156+
"/me/activities/{id}": {
157+
"leastPrivilegePath": ["DelegateedWork", "DelegatedPersonal"],
158+
"includedProperties": ["id","displayName"],
159+
"excludedProperties": ["cost"]
160+
}
161+
```
162+
### leastPrivilegePath
163+
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.
164+
165+
### includedProperties
166+
The "includedProperties" member is an array of strings that identify properties of the resource representation returned by the path, that are accessible with the permission.
167+
168+
### excludedProperties
169+
The "includedProperties" member is an array of strings that identify properties of the resource representation returned by the path, that are not accessible with the permission.
170+
171+
## Appendix A. JSON Schema for HTTP Problem
172+
```json
173+
{
174+
"$schema": "http://json-schema.org/draft-07/schema",
175+
"title": "Schema for OAuth Permissions",
176+
"type": "object",
177+
"properties": {
178+
"additionalProperties": false,
179+
"permissions": {
180+
"title": "Map of permission name to definition",
181+
"additionalProperties": false,
182+
"type": "object",
183+
"patternProperties": {
184+
"[\\w]+\\.[\\w]+[\\.[\\w]+]?": {
185+
"type": "object",
186+
"title": "Permission definition",
187+
"additionalProperties": false,
188+
"properties": {
189+
"note": {
190+
"type": "string"
191+
},
192+
"alsoRequires": {
193+
"type": "string",
194+
"pattern": "[\\w]+\\.[\\w]+[\\.[\\w]+]?"
195+
},
196+
"schemes": {
197+
"type": "object",
198+
"patternProperties": {
199+
".*": {
200+
"$ref": "#/definitions/scheme"
201+
}
202+
}
203+
}
204+
},
205+
"pathSets": {
206+
"type": "array",
207+
"items": {
208+
"$ref": "#/definitions/pathSet"
209+
}
210+
}
211+
}
212+
}
213+
}
214+
}
215+
}
216+
},
217+
"definitions": {
218+
"schemeTypes": {
219+
"type": "string",
220+
"enum": [
221+
"delegated-work",
222+
"delegated-personal",
223+
"application",
224+
"resource-specific-consent"
225+
]
226+
},
227+
"pathSet": {
228+
"type": "object",
229+
"additionalProperties": false,
230+
"properties": {
231+
"schemes": {
232+
"type": "array",
233+
"items": {
234+
"$ref": "#/definitions/schemeTypes"
235+
}
236+
},
237+
"methods": {
238+
"type": "array",
239+
"items": {
240+
"type": "string",
241+
"enum": ["GET","PUT","POST","DELETE","PATCH","HEAD","OPTIONS","<WriteMethods>","<ReadMethods>"
242+
]
243+
}
244+
},
245+
"paths": {
246+
"type": "object",
247+
"patternProperties": {
248+
".*": {
249+
"$ref": "#/definitions/path"
250+
}
251+
}
252+
}
253+
}
254+
},
255+
"path": {
256+
"type": "object",
257+
"properties": {
258+
"excludeProperties": {
259+
"type": "array",
260+
"items": {
261+
"type": "string"
262+
}
263+
}
264+
},
265+
"scheme": {
266+
"type": "object",
267+
"properties": {
268+
"requiresAdminConsent": {
269+
"type": "boolean"
270+
},
271+
"type": {
272+
"$ref": "#/definitions/schemeTypes"
273+
},
274+
"description": {
275+
"type": "string"
276+
},
277+
"consentDescription": {
278+
"type": "string"
279+
}
280+
}
281+
}
282+
}
283+
```

0 commit comments

Comments
 (0)