Table of contents

Administrative units (preview) | Graph API concepts

Bryan Lamos|Last Updated: 8/29/2016
|
2 Contributors

Applies to: Graph API | Azure Active Directory (AD)

Overview and prerequisites

An Administrative Unit provides a conceptual container for User and Group directory objects, enabling permissions to be delegated at a finer granularity (ie: departmental, regional, etc.), to administrative roles scoped to the Administrative Unit. This topic provides descriptions of the declared properties and navigation properties exposed by the AdministrativeUnit entity, as well as the operations and functions that can be called on the administrativeUnits OData resource.

Important

Azure AD Graph API functionality is also available through Microsoft Graph, a unified API that also includes APIs from other Microsoft services like Outlook, OneDrive, OneNote, Planner, and Office Graph, all accessed through a single endpoint with a single access token. Note that administrative units are not currently supported in Microsoft Graph; you will need to use Azure AD Graph API for this feature.

Familiarity with Azure AD authentication and application configuration is necessary before using the Administrative Unit Preview. If you are unfamiliar with the concepts associated with Azure AD authentication, and/or the configuration steps required to allow an application to access your tenant, please review Authentication Scenarios for Azure AD, particularly the section titled Basics of Registering an Application in Azure AD which links to a more detailed Integrating Applications with Azure Active Directory article.

Please refer to the main Azure Active Directory Graph API article on Azure.com and the following list of Graph API articles for additional important and helpful information before proceeding to the sections below:

  1. Azure AD Graph API Versioning

    Important: The Administrative Unit feature is available in Preview only at this time. In order to use preview features, please be sure to set the api-version query string parameter to “beta”, ie: https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

    You can create and use administrative units only if you enable Azure Active Directory Premium. For more information, see Getting started with Azure Active Directory Premium

  2. Quickstart for the Azure AD Graph API on Azure.com

  3. Graph API Operations overview

  4. Supported queries, filters, and paging options

Namespace and Inheritance

Namespace: Microsoft.DirectoryServices

Base type: DirectoryObject

Properties

The AdministrativeUnit entity supports the following properties:

Declared Properties

NameTypeCreate(POST)Read(GET)Update(PATCH)Description
descriptionEdm.StringOptionalOptionalAn optional description for the administrative unit.
displayNameEdm.StringRequiredFilterableOptionalDisplay name for the administrative unit.
NameFrom MultiplicityToTo MultiplicityDescription
members*User or Group*Members assigned to the Administrative Unit, which can be Users or Groups. Inherited from DirectoryObject.
scopedAdministrators*ScopedRoleMembership*Administrators assigned to given Role(s), which are scoped to an Administrative Unit.

Note: Although the DirectoryObject entity also supports other navigation properties, including memberOf, owners, and ownedObjects, these properties are not valid for Administrative Unit. If a request for any of these properties is sent, a 400 Bad Request response is returned with a corresponding error message.

Addressing

Addressing can span a collection of administrative units in the directory, an individual administrative unit, or related resources available via the supported navigation properties of an administrative unit. 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.

ArtifactURL fragmentExample
Resource set (all administrative units)/administrativeUnitshttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta
Single resource (ie: one administrative unit)/administrativeUnits/{objectId}https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde?api-version=beta
Related resources via a Navigation property/administrativeUnits/{objectId}/$links/{property-name}https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=beta

Note: See the Navigation Properties section above for the list of valid navigation properties that can be used in place of {property-name}. Remove the “$links” segment from the resource path portion of the URI, to return the actual objects referenced by a navigation property rather than links to them. You may also address an administrative unit using generic directory objects, by replacing “administrativeUnits” with “directoryObjects” in the resource path portion of the URI.

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

Supported Operations – administrativeUnits

This section defines the operations supported on an administrativeUnits resource set. As mentioned earlier, it’s important to review the topics in the Overview and Prerequisites section first to understand some of the Graph API basics that apply to all entities, such as correctly formatting URLs, addressing entities and operations, using versioning, and more.

For each of the operations listed below:

  • The principal that performs the operation must be in an administrator role that has privileges to modify administrativeUnits resources using PATCH, POST, or DELETE requests, and privileges to read objects using GET requests.

  • As appropriate, replace the placeholder strings “contoso.onmicrosoft.com” with the domain of your Azure Active Directory tenant, and {objectId} with the ID of the resource type as determined in the URL.

  • Each request must include the following HTTP Request headers in the table below.

Request HeaderDescription
AuthorizationRequired. A bearer token issued by Azure Active Directory. See Authentication Scenarios for Azure AD for more information.
Content-TypeRequired. The media type of the content in the request body, e.g.: application/json.
Content-LengthRequired. The length of the request in bytes.


The first four operations listed below are used to manage the creation, retrieval, updating, and deletion of AdministrativeUnit entities. The operations following these use the members and scopedAdministrators navigation properties, to manage the User/Group members of the AdminstrativeUnit, and the set of scoped administrators (via the ScopedRoleMembership entity) that have administrative control of the AdministrativeUnit, respectively.

Create an administrative unit

Used to create a new AdministrativeUnit.

HTTP MethodRequest URI
POSThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

The request body specifies the required displayName and optional description properties:

{
  "displayName":"Central Region",
  "description":"Administrators responsible for the Central region."
}

See the HTTP Response Reference section below for response code definitions. The response body will appear similar to the one below.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}

Get administrative unit(s)

Used to retrieve a specific AdministrativeUnit by {objectId}, a subset by filtering on the displayName property (see Supported Queries, Filters, and Paging Options in Azure AD Graph API), or the list of all available ones. The Request/Response examples below show queries for a specific administrative unit and for all administrative units, respectively.

HTTP MethodRequest URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. The response body will appear similar to one of the ones below.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}
{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
      "deletionTimestamp":null,
      "displayName":"Central Region",
      "description":"Administrators responsible for the Central region."
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"455b7304-b245-4d58-95c4-1797c32c80db",
      "deletionTimestamp":null,
      "displayName":"East Coast Region",
      "description":"East Coast Two"
      }
   ]
}

Update an administrative unit

Used to update one or more of the properties in an AdministrativeUnit.

HTTP MethodRequest URI
PATCHhttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta

The request body specifies one or both of the AdministrativeUnit properties:

{ 
  "displayName":"Central Region Administrators"
}

See the HTTP Response Reference section below for response code definitions. There is no OData response in the response body.

Delete an administrative unit

Used to delete an AdministrativeUnit, as specified by the {objectId}.

HTTP MethodRequest URI
DELETEhttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. There is no OData response in the response body.

The following operations are implemented via the members navigation property, which provides management of the user/group members of an AdminstrativeUnit. Recall from earlier, the $links resource segment allows you to traverse or modify the association (aka: link) between two resources, such as between an administrativeUnit and a User or Group resource.

Add member(s) to an administrative unit

Used to add user or group resource members to an AdministrativeUnit.

HTTP MethodRequest URI
POSThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/?api-version=beta

In this example the request body specifies the URL to the desired member that we want to add to the administrativeUnit, which is a users resource in this example. It’s also valid to use directoryObjects as the type resource segment, in place of users, as the User entity is inherited from the DirectoryObject entity. The same is true when using the groups resource segment.

{
  "url":" https://graph.windows.net/contoso.onmicrosoft.com/users/a1daa894-ff32-4839-bb6a-d7a4210fc96a"
}

See the HTTP Response Reference section below for response code definitions. There is no OData response in the response body.

Get member(s) of an administrative unit

Used to retrieve user or group resource members from an administrativeUnit. Note that you can retrieve members using either form of the GET operations listed below. The first returns the URL/link to the member(s), the second returns the properties for the member(s). In both cases, the {memberObjectId} segment is optional, depending on whether you want the set of members returned, or a specific one.

HTTP MethodRequest URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{memberObjectId}?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/members/{memberObjectId}?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. The first example below shows the response body for an operation using the $links segment for all members (ie: {memberObjectId} is not specified), where there are two types of resources, a User and a Group. The second shows the response for the same example, without the $links segment.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/members",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a1daa894-ff32-4839-bb6a-d7a4210fc96a/Microsoft.DirectoryServices.User"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a0ab9340-2b20-4b3f-8672-bf1a2f141f91/Microsoft.DirectoryServices.Group"
      }
   ]
}
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.User",
      "objectType":"User",
      "objectId":"a1daa894-ff32-4839-bb6a-d7a4210fc96a",
      "deletionTimestamp":null,
      "acceptedAs":null,
      "acceptedOn":null,
      "accountEnabled":true,
      "alternativeSecurityIds":[],
      "alternativeSignInNames":[admin@contoso.com],
      "alternativeSignInNamesInfo":[],
      "appMetadata":null,
      "assignedLicenses":[],
      "assignedPlans":[],
      "city":"Redmond",
      "cloudSecurityIdentifier":"S-1-12-6-2715461780-1211760434-2765580987-1791561505",
      "companyName":null,
      "country":null,
      "creationType":null,
      "department":null,
      "dirSyncEnabled":null,
      "displayName":"Jon Doe",
      "extensionAttribute1":null,
      "extensionAttribute2":null,
      "extensionAttribute3":null,
      "extensionAttribute4":null,
      "extensionAttribute5":null,
      "extensionAttribute6":null,
      "extensionAttribute7":null,
      "extensionAttribute8":null,
      "extensionAttribute9":null,
      "extensionAttribute10":null,
      "extensionAttribute11":null,
      "extensionAttribute12":null,
      "extensionAttribute13":null,
      "extensionAttribute14":null,
      "extensionAttribute15":null,
      "facsimileTelephoneNumber":null,
      "givenName":"Jon",
      "immutableId":null,
      "invitedOn":null,
      "inviteReplyUrl":[],
      "inviteResources":[],
      "inviteTicket":[],
      "isCompromised":null,
      "jobTitle":null,
      "jrnlProxyAddress":null,
      "lastDirSyncTime":null,
      "mail":null,
      "mailNickname":"admin",
      "mobile":null,
      "netId":"100300008001EE6E",
      "onPremisesSecurityIdentifier":null,
      "otherMails":[jon@doe.com],
      "passwordPolicies":null,
      "passwordProfile":null,
      "physicalDeliveryOfficeName":null,
      "postalCode":"98052",
      "preferredLanguage":"en-US",
      "primarySMTPAddress":null,
      "provisionedPlans":[],
      "provisioningErrors":[],
      "proxyAddresses":[],
      "releaseTrack":null,
      "searchableDeviceKey":[],
      "selfServePasswordResetData":null,
      "sipProxyAddress":null,
      "smtpAddresses":[],
      "state":"WA",
      "streetAddress":
      "One Microsoft Way",
      "surname":"Doe",
      "telephoneNumber":"(123) 456-7890",
      "usageLocation":"US",
      "userPrincipalName":admin@constoso.com,
      "userState":null,
      "userStateChangedOn":null,
      "userType":"Member"      
      },
      { 
      "odata.type":"Microsoft.DirectoryServices.Group",
      "objectType":"Group",
      "objectId":"a0ab9340-2b20-4b3f-8672-bf1a2f141f91",
      "deletionTimestamp":null,
      "appMetadata":null,
      "cloudSecurityIdentifier":"S-1-12-6-2695598912-1262431008-448754310-2434733103",
      "description":null,
      "dirSyncEnabled":null,
      "displayName":"Group for users in Central Region Administrative Unit",
      "exchangeResources":[],
      "groupType":null,
      "isPublic":null,
      "lastDirSyncTime":null,
      "licenseAssignment":[],
      "mail":null,
      "mailEnabled":false,
      "mailNickname":"CentralUsers",
      "onPremisesSecurityIdentifier":null,
      "provisioningErrors":[],
      "proxyAddresses":[],
      "securityEnabled":true,
      "sharepointResources":[],
      "targetAddress":null,
      "wellKnownObject":null     
      }
   ]
}

Delete member(s) from an administrative unit

Used to delete user or group resource members from an administrativeGroup resource. Because members is a multi-value navigation property, you must include the {objectId} of the member/link in the request URL, which you wish to delete.

HTTP MethodRequest URI
DELETEhttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. There is no OData response in the response body.

Administrators are assigned to an administrative unit by placing them in a role that has been scoped to that administrative unit. The remaining operations in this section are implemented via the scopedAdministrators navigation property, which provides management of the set administrators that have administrative control of an AdministrativeUnit, via a scoped role.

Add a scoped-role administrator to an administrative unit

Used to add an administrator to a role that will be scoped to an administrativeUnit, via the ScopedRoleMembership entity and the scopedAdministrators navigation property. In this example, the operation does two things:

  1. Populates a new ScopedRoleMembership item (which is NOT an addressable OData resource), which establishes a relationship between an AdministrativeUnit, a DirectoryRole scoped to the administrative unit, and an administrator User.

  2. Establishes a navigation property association/link between the AdministrativeUnit and the new ScopedRoleMembership item.

HTTP MethodRequest URI
POSThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators?api-version=beta

The request body specifies the following properties from the ScopedRoleMembership entity:

  • roleObjectId – objectId of the desired DirectoryRole. Note: currently only the HelpDeskAdministrators and UserAccountAdministrator roles are valid.

  • roleMemberInfo – a structure which identifies the administrative User:objectId – objectId of the administrative User.

  • objectId – objectId of the administrative User.

{
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "roleMemberInfo":{
      "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f"}
}

See the HTTP Response Reference section below for response code definitions. The response body will appear similar to the one below.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
   "roleMemberInfo":{"objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
      "displayName":"Bryan",
      "userPrincipalName":BryanL@contoso.com
      }
}

Get a scoped-role administrator of an administrative unit

Used to get the list of administrators in scoped roles for an administrativeUnit resource, as ScopedRoleMembership entities. Note that the {scopedRoleMemberId} segment is optional, depending on whether you want the set of members, or a specific one.

HTTP MethodRequest URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. The response body below is for a query for all members.

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }            
   ]
}

Delete a scoped-role administrator from an administrative unit.

Used to delete a ScopedRoleMembership from an administrativeUnit resource, specified by the {scopedRoleMemberId} segment.

HTTP MethodRequest URI
DELETEhttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. There is no OData response in the response body.

Supported Operations – users and groups

This section defines the newly supported operations on users and groups resources, which provide support for administrativeUnit resources.

You can check the full GA documentation for the User and Group entities and for operations on users and groups.

For each of the operations listed below:

  • The principal that performs the operation must have privileges to read objects using GET requests.

  • As appropriate, replace the placeholder strings “contoso.onmicrosoft.com” with the domain of your Azure Active Directory tenant, and {objectId} with the ID of the resource type as determined in the URL.

  • Each request must include the following HTTP Request headers:

    Request HeaderDescription
    AuthorizationRequired. A bearer token issued by Azure Active Directory. See Authentication Scenarios for Azure AD for more information.
    Content-TypeRequired. The media type of the content in the request body, e.g.: application/json.
    Content-LengthRequired. The length of the request in bytes.

Get administrative unit(s) to which a user or group belongs

The Preview enables retrieval of administrativeUnits membership for users and groups resources, via the memberOf navigation property on the DirectoryObject entity. Specify the “users” resource segment to retrieve membership for users resources, or “groups” for groups resources. Specify the “$links” resource segment to retrieve the resource URLs/links, or omit to retrieve the properties.

HTTP MethodRequest URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/$links/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/$links/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/memberOf?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. The first example below shows the response body for a users resource with the $links segment, which has membership in two types of resources: a DirectoryRole and an AdministrativeUnit. The second shows the response for the same example, without the $links segment.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/memberOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/cbf54c29-6184-484d-92d6-d6af32f896a2/Microsoft.DirectoryServices.DirectoryRole"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/3cc09cfd-5423-4002-85b8-070d60a63fe2/Microsoft.DirectoryServices.AdministrativeUnit"
      }
   ]
}
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.DirectoryRole",
      "objectType":"Role",
      "objectId":"cbf54c29-6184-484d-92d6-d6af32f896a2",
      "deletionTimestamp":null,
      "cloudSecurityIdentifier":"S-1-12-6-3421850665-1213030788-2950092434-2727802930",
      "description":"Company Administrator role has full access to perform any operation in the company scope.",
      "displayName":"Company Administrator",
      "isSystem":true,
      "roleDisabled":false,
      "roleTemplateId":"62e90394-69f5-4237-9190-012177145e10"
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "deletionTimestamp":null,
      "displayName":"Central Region Administrators",
      "description":"Administrators responsible for the Central Region"
      }    
   ]  
}

Get administrative unit(s) of which a user is an administrator

Used to retrieve the adminstrativeUnits resource(s) of which a user is an administrator, via the scopedAdministratorOf navigation property on the User entity. Note that you can use either form of the GET operations listed below. The first retrieves the resource URLs/link, the second returns the properties.

HTTP MethodRequest URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/$links/scopedAdministratorOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/scopedAdministratorOf?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. The first example below shows the response body for an operation using the $links segment. The second shows the response for the same example, without the $links segment.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/scopedAdministratorOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/scopedRoleMemberships/kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU"
      }
   ]
}
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#scopedRoleMemberships",
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }
   ]  
}

Supported Operations – directoryRoles

This section defines the newly supported operations on directoryRoles resources that provide specific support for administrativeUnits resources.

You can check the full GA documentation for more information about the DirectoryRole entity and related operations****.

For each of the operations listed below:

  • The principal that performs the operation must have privileges to read objects using GET requests.

  • As appropriate, replace the placeholder strings “contoso.onmicrosoft.com” with the domain of your Azure Active Directory tenant, and {objectId} with the ID of the resource type as determined in the URL.

  • Each request must include the following HTTP Request headers:Request HeaderDescriptionAuthorizationRequired. A bearer token issued by Azure Active Directory. See Authentication Scenarios for Azure AD for more information.Content-TypeRequired. The media type of the content in the request body, e.g.: application/json.Content-LengthRequired. The length of the request in bytes.

Request HeaderDescription
AuthorizationRequired. A bearer token issued by Azure Active Directory. See Authentication Scenarios for Azure AD for more information.
Content-TypeRequired. The media type of the content in the request body, e.g.: application/json.
Content-LengthRequired. The length of the request in bytes.

Get administrative unit administrators scoped to a specific role

Administrators are assigned to an administrative unit by placing them in a role that has been scoped to that administrative unit. This operation allows you to retrieve those “scoped role membership(s)” for an administrator, as a set of scopedRoleMemberships resources. Note that only a” HelpDeskAdministrators” or “UserAccountAdministrator” role {objectId} is valid. Also note that the {scopedRoleMemberId} segment is optional, depending on whether you want all scopedRoleMembership resources for a specific role, or a specific one.

HTTP MethodRequest URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

There is no request body.

See the HTTP Response Reference section below for response code definitions. The response body below is for a query for all administrators of a particular administrative unit, scoped to the Helpdesk Administrator role.

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":[
   {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
      {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
      }
   ]
}

HTTP Response Reference

Below is the list of possible HTTP response codes:

HTTP Status CodeOData Error CodeDescription
200/OKn/aNormal response for a successful query. The response body will contain the data that matches the filters specified in the query parameters.
201/Createdn/aNormal response for a successful POST/create operation. The response body will contain the data as populated in the new resource.
204/No Contentn/aNormal response for a successful PATCH/update or DELETE operation on a resource, or POST on a linked resource. The response body will not contain an OData response.
400/BadRequestRequest_BadRequestThis is a generic error message for an invalid or missing header, parameter, or request body data. You will also see this error if attempting to add a linked resource that already exists.
401/UnauthorizedAuthorizationErrorThis will be displayed when the user is not authorized to view the content. Please see the main AD Graph REST article for additional details on securing your calls, and obtaining and specifying a secure access token.
404/Not FoundRequest_ResourceNotFoundThis will be displayed when the resource you are attempting to access does not exist.
405/Method not allowedRequest_BadRequestThis will be displayed when you are attempting an operation meant for a specific resource, but are not providing the correct resource ID in the request URL.

Additional resources

© 2017 Microsoft