Export (0) Print
Expand All

DirectoryRole

Updated: November 19, 2014

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.

ImportantImportant
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:

Declared Properties

Name Type Read (GET) Description

description

Edm.String

Yes

An optional description for the directory role.

displayName

Edm.String

Yes

The display name for the directory role.

isSystem

Edm.Boolean

Yes

true if the role is a system role; otherwise, false.

objectId

Edm.String

Yes

The unique identifier for the directory role. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.

objectType

Edm.String

Yes

A string that identifies the object type. For directory roles the value is always “DirectoryRole”. Inherited from DirectoryObject.

noteNote
In versions prior to 1.5, the value will be “Role”.

roleDisabled

Edm.Boolean

Yes

true if the directory role is disabled; otherwise, false.

Notes: required.

roleTemplateId

String

Yes

Navigation Properties

Name From Multiplicity To To Multiplicity Description

members

*

DirectoryObject

(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)

ownedObjects

*

DirectoryObject

*

Directory objects that are owned by the directory role. Requires version 2013-11-08 or newer. Inherited from DirectoryObject.

HTTP Methods: GET

noteNote
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.

 

Artifact URL fragment Example

Resource set (all roles)

/directoryRoles

https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles?api-version=1.5.

Individual role

/directoryRoles/{objectId}

https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/12345678-9abc-def0-1234-56789abcde?api-version=1.5

Navigation property

/directoryRoles/{objectId}/$(links)/{property-name}

https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=1.5

noteNote
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.

noteNote
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.

For more comprehensive information about querying directory objects, see Azure AD Graph API Common Queries and Azure AD Graph API Differential Query.

The following operations are supported on roles (the HTTP method used for each is in parentheses):

  • Read (GET)

The following operations are supported on role navigation properties:

  • Read (GET)

  • 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.

See Also

Concepts

DirectoryObject

Show:
© 2014 Microsoft