add feedback from Jackson

Author: omondiatieno

articles/active-directory/develop/Delegated-access.md

@@ -58,8 +58,8 @@ For client app authorization, OneDrive will check whether the client making the
 
 | GET /drives/{id}/files/{id} | Client app granted `Files.Read` scope for Alice | Client app not granted `Files.Read` scope for Alice |
 | ----- | ----- | ----- |
-| The document is in Alice’s OneDrive | 200 – Access granted | Unauthorized. Alice (or her admin) hasn’t allowed this client to read her files. |
-| The document is in another user’s OneDrive* | Unauthorized. Alice doesn’t have rights to read this file. Even though the client has been granted `Files.Read` it should be denied when acting on Alice’s behalf. | 403 – Unauthorized. Alice doesn’t have rights to read this file, and the client isn’t allowed to read files she has access to either. | 
+| The document is in Alice’s OneDrive | 200 – Access granted | 403 - Unauthorized. Alice (or her admin) hasn’t allowed this client to read her files. |
+| The document is in another user’s OneDrive* | 403 - Unauthorized. Alice doesn’t have rights to read this file. Even though the client has been granted `Files.Read` it should be denied when acting on Alice’s behalf. | 403 – Unauthorized. Alice doesn’t have rights to read this file, and the client isn’t allowed to read files she has access to either. | 
 
 The example given is simplified to illustrate delegated authorization. The production OneDrive service supports many other access scenarios, such as shared files.
 

articles/active-directory/develop/TOC.yml

@@ -33,16 +33,16 @@
     - name: Permissions and access
       displayName: Access control
       items:
-        - name: "Authorization options: ACLs, RBAC, ABAC"
-          href: authorization-basics.md
-        - name: RBAC for app developers
-          href: custom-rbac-for-developers.md
         - name: Permissions and consent overview
           href: permissions-consent-overview.md
         - name: Delegated access
           href: delegated-access.md
         - name: Scopes and permissions
           href: scopes-oidc.md
+        - name: "Authorization options: ACLs, RBAC, ABAC"
+          href: authorization-basics.md
+        - name: RBAC for app developers
+          href: custom-rbac-for-developers.md
         - name: Requesting permissions through consent
           href: consent-types-developer.md
         - name: Application consent experiences

articles/active-directory/develop/application-consent-experience.md

@@ -50,27 +50,27 @@ The following diagram and table provide information about the building blocks of
 ## Common scenarios and consent experiences
 
 The following section describes the common scenarios and the expected consent experience for each of them.
-### App requires a permission within the user's scope of authority
+### App requires a permission that the user has the right to grant
 
 In this consent scenario, the user accesses an app that requires a permission set that is within the user's scope of authority. The user is directed to the user consent flow.
 
-Admins will see an additional control on the traditional consent prompt that will allow them consent on behalf of the entire tenant. The control will be defaulted to off, so only when admins explicitly check the box will consent be granted on behalf of the entire tenant. The check box will only show for the Global Admin role, so Cloud Admin and App Admin won't see this checkbox.
+Admins will see an additional control on the traditional consent prompt that will allow to give consent on behalf of the entire tenant. The control will be defaulted to off, so only when admins explicitly check the box will consent be granted on behalf of the entire tenant. The check box will only show for the Global Admin role, so Cloud Admin and App Admin won't see this checkbox.
 
 :::image type="content" source="./media/application-consent-experience/consent_prompt_1a.png" alt-text="Consent prompt for scenario 1a":::
 
 Users will see the traditional consent prompt.
 
 :::image type="content" source="./media/application-consent-experience/consent_prompt_1b.png" alt-text="Screenshot that shows the traditional consent prompt.":::
 
-### App requires a permission outside of the user's scope of authority
+### App requires a permission that the user has no right to grant
 
 In this consent scenario, the user accesses an app that requires at least one permission that is outside the user's scope of authority.
 
 Admins will see an additional control on the traditional consent prompt that will allow them consent on behalf of the entire tenant.
 
 :::image type="content" source="./media/application-consent-experience/consent_prompt_1a.png" alt-text="Consent prompt for scenario 1a":::
 
-Non-admin users will be blocked from granting consent to the application, and they'll be told to ask their admin for access to the app.
+Non-admin users will be blocked from granting consent to the application, and they'll be told to ask their admin for access to the app. If admin consent workflow is enabled in the user's tenant, non-admin users are able to submit a request for admin approval from the consent prompt. For more information on admin consent workflow, see [Admin consent workflow](../manage-apps/admin-consent-workflow-overview.md)
 
 :::image type="content" source="./media/application-consent-experience/consent_prompt_2b.png" alt-text="Screenshot of the consent prompt telling the user to ask an admin for access to the app.":::
 
@@ -88,7 +88,7 @@ Non-admin users will be blocked from granting consent to the application, and th
 
 ### Admin consent through the Azure portal
 
-In this scenario, an administrator consents to an application's delegated permissions on behalf of all the users in the tenant. The Administrator grants consent through the **API permissions** page of the application registration in the [Azure portal](https://portal.azure.com).
+In this scenario, an administrator consents to all of the permissions that an application requests, which can include delegated permissions on behalf of all users in the tenant. The Administrator grants consent through the **API permissions** page of the application registration in the [Azure portal](https://portal.azure.com).
 
  :::image type="content" source="./media/consent-framework/grant-consent.png" alt-text="Grant permissions for explicit admin consent" lightbox="./media/consent-framework/grant-consent.png":::
 

articles/active-directory/develop/consent-types-developer.md

@@ -13,10 +13,10 @@ ms.date: 10/17/2022
 ms.author: jomondi
 ms.reviewer: jawoods, ludwignick, phsignor
 ---
-# Requesting for permissions through consent
+# Requesting permissions through consent
 
 
-Applications in Microsoft identity platform rely on consent in order to gain access to necessary resources or APIs. There are consent types that your application may need to know about in order to be successful. If you're defining permissions, you'll also need to understand how your users will consent to these permissions for your application or API to access their data. 
+Applications in the Microsoft identity platform rely on consent in order to gain access to necessary resources or APIs. Different types of consent are better for different application scenarios. Choosing the best approach to consent for your app will help it be more successful with users and organizations. 
 
 In this article, you'll learn about the different types of consent and how to request permissions for your application through consent.
 
@@ -26,11 +26,7 @@ In the static user consent scenario, you must specify all the permissions it nee
 
 Static permissions also enable administrators to consent on behalf of all users in the organization.
 
-While static permissions of the application defined in the Azure portal keep the code nice and simple, it presents some possible issues for developers:
-
-- The application needs to request all the permissions it would ever need upon the user's first sign-in. This can lead to a long list of permissions that discourages end users from approving the app's access on initial sign-in.
-
-- The application needs to know all of the resources it would ever access ahead of time. It's difficult to create apps that could access an arbitrary number of resources.
+While relying on static consent and a single permissions list keeps the code nice and simple, it also means that your app will request all of the permissions it might ever need up front. This can discourage users and admins from approving your app's access request.
 
 ## Incremental and dynamic user consent
 
@@ -97,7 +93,7 @@ Some organizations may change the default user consent policy for the tenant. Wh
 
 Application permissions always require admin consent. Application permissions don't have a user context and the consent grant isn't done on behalf of any specific user. Instead, the client application is granted permissions directly, these types of permissions are used only by daemon services and other non-interactive applications that run in the background. Administrators need to configure the permissions upfront and [grant admin consent](../manage-apps/grant-admin-consent.md) through the Azure portal. 
 
-### Admin consent Multi-tenant applications
+### Admin consent for Multi-tenant applications
 
 In case the application requesting the permission is a multi-tenant application, its application registration only exists in the tenant where it was created, therefore permissions can't be configured in the local tenant. If the application requests permissions that require admin consent, the administrator needs to consent on behalf of the users. To consent to these permissions, the administrators need to log in to the application themselves, so the admin consent sign-in experience is triggered. To learn how to set up the admin consent experience for multi-tenant applications, see [Enable multi-tenant log-ins](howto-convert-app-to-be-multi-tenant.md#understand-user-and-admin-consent)
 

articles/active-directory/develop/permissions-consent-overview.md

@@ -30,23 +30,23 @@ As an application developer, you must identify how your application will access
 
 In this access scenario, a user has signed into a client application. The client application accesses the resource on behalf of the user. Delegated access requires delegated permissions. Both the client and the user must be authorized separately to make the request. For more information about the delegated access scenario, see [delegated access scenario](delegated-access.md).
 
-For the client app, the correct delegated permissions must be granted. Delegated permissions can also be referred to as scopes. Scopes are permissions of a given resource that the client application exercises on behalf of a user. They're strings that represent what the application wants to do on behalf of the user. For more information about scopes, see [scopes and permissions](v2-permissions-and-consent.md#scopes-and-permissions).
+For the client app, the correct delegated permissions must be granted. Delegated permissions can also be referred to as scopes. Scopes are permissions for a given resource that represent what a client application can access on behalf of the user.For more information about scopes, see [scopes and permissions](v2-permissions-and-consent.md#scopes-and-permissions).
 
-For the user, the authorization relies on the privileges that the user has been granted for them to access the resource. For example, the user could be authorized to access directory resources by [Azure Active Directory (Azure AD) role-based access control (RBAC)](../roles/custom-overview.md) or to access mail and calendar resources by [Exchange Online RBAC](/exchange/permissions-exo/permissions-exo).
+For the user, the authorization relies on the privileges that the user has been granted for them to access the resource. For example, the user could be authorized to access directory resources by [Azure Active Directory (Azure AD) role-based access control (RBAC)](../roles/custom-overview.md) or to access mail and calendar resources by Exchange Online RBAC. For more information on RBAC for applications, see [RBAC for applications](custom-rbac-for-developers.md)
 
 ### App-only access (Access without a user)
 
 In this access scenario, the application acts on its own with no user signed in. Application access is used in scenarios such as automation, and backup. This scenario includes apps that run as background services or daemons. It's appropriate when it's undesirable to have a specific user signed in, or when the data required can't be scoped to a single user.
 
-App-only access may require application permissions but that isn't the only way for granting app-only access. Application permissions can be referred to as app roles. When app roles are granted to other applications, they're called applications permissions. The appropriate application permissions or app roles must be granted to the application for it to access the resource. For more information about assigning app roles to applications, see [App roles for applications](howto-add-app-roles-in-azure-ad-apps.md).
+App-only access uses app roles instead of delegated scopes. When granted through consent, app roles may also be called applications permissions. For app-only access, the client app must be granted appropriate app roles of the resource app it's calling in order to access the requested data. For more information about assigning app roles to client applications, see [Assigning app roles to applications](howto-add-app-roles-in-azure-ad-apps.md#assign-app-roles-to-applications).
 
 ## Types of permissions
 
-**Delegated permissions** are used in the delegated access scenario. They're permissions that allow the application to act on a user's behalf. The application will never be able to access anything users themselves couldn't access
+**Delegated permissions** are used in the delegated access scenario. They're permissions that allow the application to act on a user's behalf. The application will never be able to access anything the signed in user themselves couldn't access.
 
 For example, imagine an application that has been granted the Files.Read.All delegated permission on behalf of Tom, the user. The application will only be able to read files that Tom can personally access.
 
-**Application permissions** are used in the app-only access scenario, without a signed-in user present. The application will be able to access any data that the permission is associated with. For example, an application granted the Files.Read.All application permission will be able to read any file in the tenant.  Only an administrator or owner of the service principal can consent to application permissions.
+**Application permissions**, sometimes called app roles are used in the app-only access scenario, without a signed-in user present. The application will be able to access any data that the permission is associated with. For example, an application granted the Files.Read.All application permission will be able to read any file in the tenant.  Only an administrator or owner of the service principal can consent to application permissions.
 
 There are other ways in which applications can be granted authorization for app-only access. For example, an application can be assigned an Azure AD RBAC role.
 
@@ -57,14 +57,14 @@ There are other ways in which applications can be granted authorization for app-
 | Types of apps | Web / Mobile / single-page app (SPA) | Web / Daemon |
 | Access context | Get access on behalf of a user | Get access without a user |
 | Who can consent | <li> Users can consent for their data <li> Admins can consent for all users | Only admin can consent |
-| Other names | <li> Scopes <li>OAuth2 permissions | <li> App roles <li>App-only permissions |
+| Other names | <li> Scopes <li>OAuth2 permission scopes | <li> App roles <li>App-only permissions |
 | Result of consent (specific to Microsoft Graph)  | [oAuth2PermissionGrant](/graph/api/resources/oauth2permissiongrant) | [appRoleAssignment](/graph/api/resources/approleassignment) |
 
 ## Consent
 One way that applications are granted permissions is through consent. Consent is a process where users or admins authorize an application to access a protected resource. For example, when a user attempts to sign into an application for the first time, the application can request permission to see the user's profile and read the contents of the user's mailbox. The user sees the list of permissions the app is requesting through a consent prompt. Other scenarios where users may see a consent prompt include:
 
-- When previously granted consent is revoked
-- When the application is coded to specifically prompt for consent during every sign-in
+- When previously granted consent is revoked.
+- When the application is coded to specifically prompt for consent during every sign-in.
 - When the application uses incremental or dynamic consent to ask for some permissions upfront and more permission later as needed. 
 
 The key details of a consent prompt are the list of permissions the application requires and the publisher information. For more information about the consent prompt and the consent experience for both admins and end-users, see [application consent experience](application-consent-experience.md).
@@ -75,7 +75,7 @@ User consent happens when a user attempts to sign into an application. The user
 
 ### Administrator consent
 
-Depending on the permissions they require, some applications might require an administrator to be the one who grants consent. Application permissions can only be consented to by an administrator. Administrators can grant consent for themselves or for the entire organization. For more information about user and admin consent, see [user and admin consent overview](../manage-apps/consent-and-permissions-overview.md)
+Depending on the permissions they require, some applications might require an administrator to be the one who grants consent. For example, application permissions and many high-privilege delegated permissions can only be consented to by an administrator. Administrators can grant consent for themselves or for the entire organization. For more information about user and admin consent, see [user and admin consent overview](../manage-apps/consent-and-permissions-overview.md)
 
 ### Preauthorization