SALES: 1-800-867-1380

Role

Updated: August 15, 2013

Applies To: Windows Azure AD Graph.

Overview

This topic provides descriptions of the properties of the Role entity.

Windows Azure AD Graph exposes metadata that describes the directory as an Entity Data Model (EDM) using Conceptual Schema Definition Language (CSDL). You can view the metadata exposed for your tenant by performing an HTTP GET from the following URL: https://graph.windows.net/yourTenantDomain/$metadata?api-version=2013-04-05. Replace yourTenantDomain with the domain of your tenant; for example, https://graph.windows.net/contoso.onmicrosoft.com/$metadata?api-version=2013-04-05. For more information about the EDM and CSDL, see Entity Data Model.

Properties

The Role entity type is defined as follows:

Namespace: Microsoft.WindowsAzure.ActiveDirectory

Base type: DirectoryObject

Type Properties

Name Type Notes Read/Write Key Description

description

Edm.String

R

An optional description for the role.

displayName

Edm.String

R

The display name for the role.

isSystem

Edm.Boolean

R

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

objectId

Edm.String

Immutable, not nullable, unique

R

Yes

The unique identifier for the role. Inherited from DirectoryObject.

objectType

Edm.String

R

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

roleDisabled

Edm.Boolean

Required

R

true if the role is disabled; otherwise, false.

Navigation Properties

Name From From Multiplicity To To Multiplicity Description

members

Role

*

DirectoryObject

(User and ServicePrincipal are supported on reads; only User is supported on writes.)

*

Users and service principals that are members of this role. Inherited from DirectoryObject.

HTTP Methods: GET, POST (User only), DELETE (User only)

noteNote
Role also inherits the manager, directReports, and memberOf navigation properties from DirectoryObject; however, none of these properties are valid for 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.

Addressing

The following list shows how to address the role resource set, which spans all the roles in the directory; an individual role; and the navigation properties of a role. The examples in the list use the tenant domain to address the tenant. For other ways of addressing the tenant, see Addressing Entities and Operations in the Graph.

  • Resource Set: https://graph.windows.net/<tenantDomain>/roles?api-version=<version>. For example, https://graph.windows.net/contoso.onmicrosoft.com/roles?api-version=2013-04-05.

  • Role: https://graph.windows.net/<tenantDomain>/roles/<objectId>?api-version=<version>. For example, https://graph.windows.net/contoso.onmicrosoft.com/roles/12345678-9abc-def0-1234-56789abcde?api-version=2013-04-05.

  • Navigation Property: https://graph.windows.net/<tenantDomain>/roles/<objectId>/$links/<property name>?api-version=<version>. For example, https://graph.windows.net/contoso.onmicrosoft.com/roles/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=2013-04-05.

noteNote
Remove the “$links” segment of the navigation property URI 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. Roles or their navigation properties can also be addressed as generic directory objects by replacing “roles” with “directoryObjects” in the URI.

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

Supported Operations and Permissions

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), and Delete (DELETE).

The service principal that represents an application must be in an administrator role that has permissions to modify role objects to send POST or DELETE requests. It must be in a role that has permissions to read role objects to send GET requests. For more information about administrator roles in Windows Azure AD Graph, see Windows Azure AD Graph and Role-Based Access Control.

Remarks

  • Roles cannot be added or deleted using Windows Azure AD Graph. Updates are only supported on the member property (add or remove).

  • Reading the members of a role returns both service principals and users; however, only users can be added or deleted from membership in a role with Windows Azure AD Graph.

  • Query filter expressions are not supported on roles.

For more information operations on roles including examples, see Operations on Roles.

See Also

Concepts

DirectoryObject

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft