Updated: May 26, 2015
Important: the content in this topic may be out of date. See the new interactive Graph API documentation for the most up-to-date reference documentation for Azure AD Graph API. With the interactive documentation, you can try REST operations against a sample tenant from inside the documentation itself. Documentation updates are only being made in the interactive documentation, and this topic will be removed in the future.
Applies To: Azure AD Graph API
Represents an Azure Active Directory role. With the Graph API, you can assign users to Azure AD directory roles to grant them the permissions of the target role. You can read role objects and update the members navigation property of directory roles, but you cannot create or delete directory roles or update their declared properties. This topic provides descriptions of the properties and navigation properties exposed by the DirectoryRole entity type; as well as the operations that you can perform on them.
Beginning with Azure AD Graph API version 1.5, the Role entity type has been renamed to DirectoryRole.
Namespace: Microsoft.DirectoryServices for version 1.5 and newer, Microsoft.WindowsAzure.ActiveDirectory for versions prior to 1.5.
Base type: DirectoryObject
The DirectoryRole entity type has the following properties:
An optional description for the directory role.
The display name for the directory role.
true if the role is a system role; otherwise, false.
The unique identifier for the directory role. Inherited from DirectoryObject.
Notes: key, immutable, not nullable, unique.
A string that identifies the object type. For directory roles the value is always “DirectoryRole”. Inherited from DirectoryObject.
true if the directory role is disabled; otherwise, false.
(User and ServicePrincipal are supported on reads; only User is supported on writes.)
Users and service principals that are members of this directory role. Inherited from DirectoryObject.
HTTP Methods: GET, POST (User only), DELETE (User only)
Directory objects that are owned by the directory role. Requires version 2013-11-08 or newer. Inherited from DirectoryObject.
HTTP Methods: GET
DirectoryRole also inherits other navigation properties from DirectoryObject; however, none of these properties are valid for directory roles. If a request for any of these properties is sent, a 400 Bad Request response is returned.
For information about the primitive types exposed by the EDM, see Entity Data Model: Primitive Data Types.
The following table shows how to address the directory role resource set, which spans all the directory roles in the directory; an individual directory role; and the navigation properties of a directory role. The examples in the table use the tenant domain to address the tenant. For other ways of addressing the tenant, see Addressing Entities and Operations in the Graph API.
Resource set (all roles)
Remove the “$links” segment of the navigation property URL to return the objects referenced by a navigation property rather than links to them. This mode of addressing can be used for read operations only. Directory roles or their navigation properties can also be addressed as generic directory objects by replacing “directoryRoles” with “directoryObjects” in the URL.
Prior to version 1.5, directory roles are represented by the Role entity and are addressed by using the “roles” resource set. For example, the following URL returns all of the directory roles in the tenant using version 2013-11-08: https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles?api-version=2013-11-08.
The following operations are supported on roles (the HTTP method used for each is in parentheses):
The following operations are supported on role navigation properties:
Update (POST); members (only for users).
Delete (DELETE); members (only for users).
No functions or actions may be called on directory roles.
The principal must be in an administrator role that has permissions to modify directory role objects to send POST or DELETE requests. It must be in a role that has permissions to read directory role objects to send GET requests.
Directory roles cannot be added or deleted using the Graph API. Updates are supported on the members navigation property only. Both add and remove are supported on this property.
Reading the members of a directory role returns both service principals and users; however, only users can be added or deleted from membership in a directory role with the Graph API.
Query filter expressions are not supported on directory roles.
For more information about operations on directory roles including examples, see Operations on Roles.