Merge pull request #25613 from microsoftgraph/directoryPermissions

Update notes for directory permissions

Author: Lauragra

includes/permissions-notes/directory.accessasuser.all.md

@@ -5,34 +5,6 @@ ms.localizationpriority: high
 <!-- markdownlint-disable MD002 MD041 -->
 
 > [!CAUTION]
-> Directory permissions provide the highest level of privilege for accessing directory resources such as [user](/graph/api/resources/user), [group](/graph/api/resources/group), and [device](/graph/api/resources/device) in an organization.
+> Directory permissions grant broad access to directory (Microsoft Entra ID) resources such as [user](/graph/api/resources/user), [group](/graph/api/resources/group), and [device](/graph/api/resources/device) in an organization. Whenever possible, choose permissions specific to these resources and avoid using directory permissions.
 >
-> They also exclusively control access to other directory resources like [organizational contacts](/graph/api/resources/orgcontact) and [schema extensions](/graph/api/resources/schemaextension), as well as many directory resources including administrative units, directory roles, directory settings, and policies.
-
-<!--
-
-This section doesn't look correct; for example, you can create aapps using Directory.ReadWrite.All; Maybe it's out of date?
-
-
-The _Directory.ReadWrite.All_ permission grants the following privileges:
-
-- Full read of all directory resources (both declared properties and navigation properties)
-- Create and update users
-- Disable and enable users (but not Company Administrator)
-- Set user alternative security ID (but not administrators)
-- Create and update groups
-- Manage group memberships
-- Update group owner
-- Manage license assignments
-- Define schema extensions on applications
-- Manage directory settings
-- Manage admin consent workflow configuration (but not whether admin consent is required or who is authorized to grant admin consent)
-
-And **doesn't grant* the following privileges:
-
-- To reset user passwords.
-- Updating another user's **businessPhones**, **mobilePhone**, or **otherMails** property is only allowed on users who are non-administrators or assigned one of the following roles: Directory Readers, Guest Inviter, Message Center Reader and Reports Reader. For more details, see Helpdesk (Password) Administrator in [Azure AD available roles](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#available-roles).  This is the case for apps granted either the User.ReadWrite.All or Directory.ReadWrite.All delegated or application permissions.
-- Deleting resources (including users or groups).
-- Specifically excludes create or update for resources not listed above. This includes: application, oAuth2PermissionGrant, appRoleAssignment, device, servicePrincipal, organization, domains, and so on.
-
--->
+> Directory permissions might be deprecated in the future.

includes/permissions-notes/directory.read.all.md

@@ -5,10 +5,10 @@ ms.localizationpriority: high
 <!-- markdownlint-disable MD002 MD041 -->
 
 > [!CAUTION]
-> Directory permissions provide the highest level of privilege for accessing directory resources such as [user](/graph/api/resources/user), [group](/graph/api/resources/group), and [device](/graph/api/resources/device) in an organization.
->
-> They also exclusively control access to other directory resources like: [organizational contacts](/graph/api/resources/orgcontact?view=graph-rest-beta&preserve-view=true) and [schema extensions](/graph/api/resources/schemaextension?view=graph-rest-beta&preserve-view=true), as well as many directory resources including administrative units, directory roles, directory settings, and policies.
+> Directory permissions grant broad access to directory (Microsoft Entra ID) resources such as [user](/graph/api/resources/user), [group](/graph/api/resources/group), and [device](/graph/api/resources/device) in an organization. Whenever possible, choose permissions specific to these resources and avoid using directory permissions.
+> 
+> Directory permissions might be deprecated in the future.
 
-Before December 3rd, 2020, when the application permission *Directory.Read.All* was granted, the [Directory Readers](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#directory-readers-permissions) directory role was also assigned to the app's service principal. This directory role isn't removed automatically when the associated application permissions are revoked. To remove an application's access to read or write to the directory, customers must also remove any directory roles that were granted to the application.
+Before December 3rd, 2020, when the application permission *Directory.Read.All* was granted, the [Directory Readers](/entra/identity/role-based-access-control/permissions-reference#directory-writers) directory role was also assigned to the app's service principal. This directory role isn't removed automatically when the associated application permissions are revoked. To remove an application's access to read or write to the directory, customers must also remove any directory roles that were granted to the application.
 
 A service update disabling this behavior began rolling out on December 3rd, 2020. Deployment to all customers completed on January 11th, 2021. Directory roles are no longer automatically assigned when application permissions are granted.

includes/permissions-notes/directory.readwrite.all.md

@@ -4,11 +4,11 @@ ms.localizationpriority: high
 
 <!-- markdownlint-disable MD002 MD041 -->
 
-*Directory permissions are **not recommended** for use and might be deprecated in the future.*
-
 > [!CAUTION]
-> Directory.ReadWrite.All grants access that is broadly equivalent to a global tenant admin. Apps that are granted Directory.ReadWrite.All can manage the full range of directory resources, and they can manage authorization for *other* apps and users to access resources across the organization. This includes directory resources like [users](/graph/api/resources/user), [groups](/graph/api/resources/group), [applications](/graph/api/resources/application), and [devices](/graph/api/resources/device), and nondirectory resources in Exchange, SharePoint, Teams, and other services.
+> Directory permissions grant broad access to directory (Microsoft Entra ID) resources such as [user](/graph/api/resources/user), [group](/graph/api/resources/group), and [device](/graph/api/resources/device) in an organization. Whenever possible, choose permissions specific to these resources and avoid using directory permissions.
+> 
+> Directory permissions might be deprecated in the future.
 
-Before December 3rd, 2020, when the application permission *Directory.ReadWrite.All* was granted, the [Directory Writers](/azure/active-directory/users-groups-roles/directory-assign-admin-roles#directory-writers-permissions) directory role was also assigned. This directory role isn't removed automatically when the associated application permissions are revoked. To remove an application's access to read or write to the directory, customers must also remove any directory roles that were granted to the application.
+Before December 3rd, 2020, when the application permission *Directory.ReadWrite.All* was granted, the [Directory Writers](/entra/identity/role-based-access-control/permissions-reference#directory-writers) directory role was also assigned. This directory role isn't removed automatically when the associated application permissions are revoked. To remove an application's access to read or write to the directory, customers must also remove any directory roles that were granted to the application.
 
 A service update disabling this behavior began rolling out on December 3rd, 2020. Deployment to all customers completed on January 11, 2021. Directory roles are no longer automatically assigned when application permissions are granted.