You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/active-directory/develop/v1-permissions-and-consent.md
+20-24Lines changed: 20 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ ms.workload: identity
14
14
ms.tgt_pltfrm: na
15
15
ms.devlang: na
16
16
ms.topic: article
17
-
ms.date: 06/25/2018
17
+
ms.date: 08/27/2018
18
18
ms.author: celested
19
19
ms.reviewer: jesakowi, justhu
20
20
ms.custom: aaddev
@@ -34,10 +34,10 @@ Effective permissions are the permissions that your app will have when making re
34
34
35
35
* For delegated permissions, the effective permissions of your app will be the least privileged intersection of the delegated permissions the app has been granted (through consent) and the privileges of the currently signed-in user. Your app can never have more privileges than the signed-in user. Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. For more information about administrator roles, see [Assigning administrator roles in Azure AD](../users-groups-roles/directory-assign-admin-roles.md).
36
36
For example, assume your app has been granted the `User.ReadWrite.All` delegated permission in Microsoft Graph. This permission nominally grants your app permission to read and update the profile of every user in an organization. If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.
37
-
* For application permissions, the effective permissions of your app are the full level of privileges implied by the permission. For example, an app that has the `User.ReadWrite.All` application permission can update the profile of every user in the organization.
37
+
* For application permissions, the effective permissions of your app are the full level of privileges implied by the permission. For example, an app that has the `User.ReadWrite.All` application permission can update the profile of every user in the organization.
38
38
39
39
## Permission attributes
40
-
Permissions in Azure AD have a number of properties that help users, administrators, or app developers make informed decisions about what the permission grants access to.
40
+
Permissions in Azure AD have a number of properties that help users, administrators, or app developers make informed decisions about what the permission grants access to.
41
41
42
42
> [!NOTE]
43
43
> You can view the permissions that an Azure AD Application or Service Principal exposes using the Azure portal, or PowerShell. Try this script to view the permissions exposed by Microsoft Graph.
@@ -51,27 +51,28 @@ Permissions in Azure AD have a number of properties that help users, administrat
| `ID` | Is a GUID value that uniquely identifies this permission. | 570282fd-fa5c-430d-a7fd-fc8dc98a9dca |
57
-
| `IsEnabled` | Indicates whether this permission is available for use. | true |
58
-
| `Type` | Indicates whether this permission requires user consent or admin consent. | User |
59
-
| `AdminConsentDescription` | Is a description that's shown to administrators during the admin consent experiences | Allows the app to read email in user mailboxes. |
60
-
| `AdminConsentDisplayName` | Is the friendly name that's shown to administrators during the admin consent experience. | Read user mail |
61
-
| `UserConsentDescription` | Is a description that's shown to users during a user consent experience. | Allows the app to read email in your mailbox. |
62
-
| `UserConsentDisplayName` | Is the friendly name that's shown to users during a user consent experience. | Read your mail |
63
-
| `Value` | Is the string that's used to identify the permission during OAuth 2.0 authorize flows. `Value` may also be combined with the App ID URI string in order to form a fully qualified permission name. | `Mail.Read` |
56
+
| `ID` | Is a GUID value that uniquely identifies this permission. | 570282fd-fa5c-430d-a7fd-fc8dc98a9dca |
57
+
| `IsEnabled` | Indicates whether this permission is available for use. | true |
58
+
| `Type` | Indicates whether this permission requires user consent or admin consent. | User |
59
+
| `AdminConsentDescription` | Is a description that's shown to administrators during the admin consent experiences | Allows the app to read email in user mailboxes. |
60
+
| `AdminConsentDisplayName` | Is the friendly name that's shown to administrators during the admin consent experience. | Read user mail |
61
+
| `UserConsentDescription` | Is a description that's shown to users during a user consent experience. | Allows the app to read email in your mailbox. |
62
+
| `UserConsentDisplayName` | Is the friendly name that's shown to users during a user consent experience. | Read your mail |
63
+
| `Value` | Is the string that's used to identify the permission during OAuth 2.0 authorize flows. `Value` may also be combined with the App ID URI string in order to form a fully qualified permission name. | `Mail.Read` |
64
64
65
65
## Types of consent
66
+
66
67
Applications in Azure AD rely on consent in order to gain access to necessary resources or APIs. There are a number of kinds of consent that your app may need to know about in order to be successful. If you are defining permissions, you will also need to understand how your users will gain access to your app or API.
67
68
68
69
* **Static user consent** - Occurs automatically during the [OAuth 2.0 authorize flow](v1-protocols-oauth-code.md#request-an-authorization-code) when you specify the resource that your app wants to interact with. In the static user consent scenario, your app must have already specified all the permissions it needs in the app's configuration in the Azure portal. If the user (or administrator, as appropriate) has not granted consent for this app, then Azure AD will prompt the user to provide consent at this time.
69
70
70
71
Learn more about registering an Azure AD app that requests access to a static set of APIs.
71
72
* **Dynamic user consent** - Is a feature of the v2 Azure AD app model. In this scenario, your app requests a set of permissions that it needs in the [OAuth 2.0 authorize flow for v2 apps](/azure/active-directory/develop/active-directory-v2-scopes#requesting-individual-user-consent). If the user has not consented already, they will be prompted to consent at this time. [Learn more about dynamic consent](/azure/active-directory/develop/active-directory-v2-compare#incremental-and-dynamic-consent).
72
73
73
-
> [!NOTE]
74
-
> Dynamic consent can be convenient, but presents a big challenge for permissions that require admin consent, since the admin consent experience doesn't know about those permissions at consent time. If you require admin privileged permissions, your app must register them in the Azure Portal.
74
+
> [!IMPORTANT]
75
+
> Dynamic consent can be convenient, but presents a big challenge for permissions that require admin consent, since the admin consent experience doesn't know about those permissions at consent time. If you require admin privileged permissions or if your app uses dynamic consent, you must register all of the permissions in the Azure portal (not just the subset of permissions that require admin consent). This enables tenant admins to consent on behalf of all their users.
75
76
76
77
* **Admin consent** - Is required when your app needs access to certain high-privilege permissions. Admin consent ensures that administrators have some additional controls before authorizing apps or users to access highly privileged data from the organization. [Learn more about how to grant admin consent](/azure/active-directory/develop/active-directory-v2-scopes#using-the-admin-consent-endpoint).
77
78
@@ -80,7 +81,7 @@ Applications in Azure AD rely on consent in order to gain access to necessary re
80
81
### Client best practices
81
82
82
83
- Only request for permissions that your app needs. Apps with too many permissions are at risk of exposing user data if they are compromised.
83
-
- Choose between delegated permissions and application permissions based on the scenario that your app supports.
84
+
- Choose between delegated permissions and application permissions based on the scenario that your app supports.
84
85
- Always use delegated permissions if the call is being made on behalf of a user.
85
86
- Only use application permissions if the app is non-interactive and not making calls on behalf of any specific user. Application permissions are highly privileged and should only be used when absolutely necessary.
86
87
- When using an app based on the v2.0 endpoint, always set the static permissions (those specified in your application registration) to be the superset of the dynamic permissions you request at runtime (those specified in code and sent as query parameters in your authorize request) so that scenarios like admin consent works correctly.
@@ -91,16 +92,11 @@ Applications in Azure AD rely on consent in order to gain access to necessary re
91
92
- Resources should explicitly define `Read` and `ReadWrite` permissions separately.
92
93
- Resources should mark any permissions that allow access to data across user boundaries as `Admin` permissions.
93
94
- Resources should follow the naming pattern `Subject.Permission[.Modifier]`, where:
94
-
- `Subject` corresponds with the type of data that is available,
95
-
- `Permission` corresponds to the action that a user may take upon that data, and
96
-
- `Modifier` is used optionally to describe specializations of another permission.
95
+
- `Subject` corresponds with the type of data that is available
96
+
- `Permission` corresponds to the action that a user may take upon that data
97
+
- `Modifier` is used optionally to describe specializations of another permission
97
98
98
-
For example:
99
+
For example:
99
100
* Mail.Read - Allows users to read mail.
100
101
* Mail.ReadWrite - Allows users to read or write mail.
101
102
* Mail.ReadWrite.All - Allows an administrator or user to access all mail in the organization.
0 commit comments