Operations on directory roles | Graph API reference
Applies to: Graph API | Azure Active Directory
This topic discusses how to perform operations on Azure AD directory roles using the Azure Active Directory (AD) Graph API. Directory roles (DirectoryRole) carry specific sets of rights within the directory. Azure AD grants the users and service principals that are members of a directory role the rights associated with that role. Azure AD directory roles are also known as administrator roles. For more information about directory (administrator) roles, see Assigning administrator roles in Azure AD.
This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see directoryRole resource type.
Importante
We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.
With the Graph API, you can read the properties of directory roles, query members of a directory role, and add and delete members to and from a directory role. Directory Roles may have users and service principals as members. Adding groups to directory roles is not currently supported.
In versions prior to 1.5 all directory roles are present in the tenant by default. In versions 1.5 and newer, only the Company Administrators directory role is present by default. To access and assign members to another directory role, you must first activate it by using its corresponding directory role template (DirectoryRoleTemplate). For more information, see Activate a directory role.
The Graph API is an OData 3.0 compliant REST API that provides programmatic access to directory objects in Azure Active Directory, such as users, groups, organizational contacts, and applications.
Performing REST operations on directory roles
To perform operations on directory roles with the Graph API, you send HTTP requests with a supported method (GET, POST, PATCH, PUT, or DELETE) to an endpoint that targets the directoryRoles resource collection, a specific directory role, a navigation property of a directory role, or a function or action that can be called on a directory role.
Graph API requests use the following basic URL:
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}[odata_query_parameters]
Importante
Requests sent to the Graph API must be well-formed, target a valid endpoint and version of the Graph API, and carry a valid access token obtained from Azure AD in their Authorization header. For more detailed information about creating requests and receiving responses with the Graph API, see Operations Overview.
You specify the {resource_path} differently depending on whether you are targeting the collection of all directory roles in your tenant, an individual directory role, or a navigation property of a specific directory role.
/directoryRolestargets the directoryRoles resource collection. You can use this resource path to read all directory roles in your tenant and, in version 1.5 and newer, to activate a directory role in your tenant./directoryRoleTemplatestargets the directoryRoleTemplates resource collection. You can use this resource path to read all directory role templates available in your tenant. In version 1.5 and newer, you use directory role templates to activate a directory roles in your tenant./directoryRoles/{object_id}targets an individual directory role in your tenant. You specify the target role with its object ID (GUID). You can use this resource path to get the declared properties of a specified directory role./directoryRoles/{object_id}/memberstargets the members navigation property of a directory role. You can use it to return the users and service principals that are members of the specified directory role. Note: This form of addressing is only available for reads./directoryRoles/{object_id}/$links/memberstargets the members navigation property of a directory role. You can use this form of addressing to both read and modify the members of the role. On reads, the users and service principals referenced by the property are returned as one or more links in the response body. On writes, the users and service principals are specified as one or more links in the request body.
For example, the following request returns a a collection of links to the members of the specified directory role:
GET https://graph.windows.net/myorganization/directoryRoles/ffffffff-ffff-ffff-ffff-ffffffffffff/$links/members?api-version=1.6
Basic operations on directory roles
You can perform the following basic operations on directory roles and directory role templates.
- Read the properties of all directory roles or an individual role.
- Read the properties of all directory role templates or an individual template (version 1.5 and newer).
- Activate a directory role using a POST request (version 1.5 and newer).
The following topics show you how.
Get directory roles
Gets the collection directory roles that are activated in the tenant. (For versions prior to 1.5, all directory roles were activated by default.)
On success, returns the collection of DirectoryRole objects that are activated; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
GET https://graph.windows.net/myorganization/directoryRoles?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| Query | |||
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
Response
Status Code:200
Content-Type: application/json
{
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRole",
"value": [
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "02618ff0-e643-450d-b9b2-2f812364eb2c",
"deletionTimestamp": null,
"description": "Helpdesk Administrator has access to perform common helpdesk related tasks.",
"displayName": "Helpdesk Administrator",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "729827e3-9c14-49f7-bb1b-9608f156bbb8"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "044ca859-dc72-47cb-b466-7f6e78398979",
"deletionTimestamp": null,
"description": "Allows access read tasks and a subset of write tasks in the directory.",
"displayName": "Directory Writers",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "9360feb5-f418-4baa-8175-e2a00bac4301"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "44261f4c-b686-44c1-8997-310171ed4ca8",
"deletionTimestamp": null,
"description": "Allows access to various read only tasks in the directory. ",
"displayName": "Directory Readers",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8",
"deletionTimestamp": null,
"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"
}
]
}
Response List
| Status Code | Description |
|---|---|
| 200 | OK. Indicates success. The results are returned in the response body. |
Code Samples
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;
namespace CSHttpClientSample
{
static class Program
{
static void Main()
{
MakeRequest();
Console.WriteLine("Hit ENTER to exit...");
Console.ReadLine();
}
static async void MakeRequest()
{
var client = new HttpClient();
var queryString = HttpUtility.ParseQueryString(string.Empty);
/* OAuth2 is required to access this API. For more information visit:
https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */
// Specify values for the following required parameters
queryString["api-version"] = "1.6";
// Specify values for path parameters (shown as {...})
var uri = "https://graph.windows.net/myorganization/directoryRoles?" + queryString;
var response = await client.GetAsync(uri);
if (response.Content != null)
{
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);
}
}
}
}
@ECHO OFF
REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/directoryRoles?api-version=1.6&"^
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample {
public static void main(String[] args) {
HttpClient httpclient = HttpClients.createDefault();
try
{
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/directoryRoles");
// Specify values for the following required parameters
builder.setParameter("api-version", "1.6");
URI uri = builder.build();
HttpGet request = new HttpGet(uri);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null) {
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
$(function() {
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
var params = {
// Specify values for the following required parameters
'api-version': "1.6",
};
$.ajax({
// Specify values for path parameters (shown as {...})
url: 'https://graph.windows.net/myorganization/directoryRoles?' + $.param(params),
type: 'GET',
})
.done(function(data) {
alert("success");
})
.fail(function() {
alert("error");
});
});
</script>
</body>
</html>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
NSString* path = @"https://graph.windows.net/myorganization/directoryRoles";
NSArray* array = @[
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"GET"];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if(nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if(nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);
$query_params = array(
// Specify values for the following required parameters
'api-version' => '1.6',
);
$request = new Http_Request2('https://graph.windows.net/myorganization/directoryRoles');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
$url = $request->getUrl();
$url->setQueryVariables($query_params);
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = httplib.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoles?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.parse.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = http.client.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoles?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://graph.windows.net/myorganization/directoryRoles')
uri.query = URI.encode_www_form({
# Specify values for the following required parameters
'api-version' => '1.6',
})
request = Net::HTTP::Get.new(uri.request_uri)
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
Get a directory role
Gets a specified directory role. Specify the directory role by its object ID (GUID).
On success, returns the DirectoryRole object for the specified role; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
GET https://graph.windows.net/myorganization/directoryRoles/{object_id}?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| URL | ---- | ----- | ----- |
| object_id | string | cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8 | The object ID (GUID) of the target directory role. |
| Query | ---- | ----- | ----- |
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
GET https://graph.windows.net/myorganization/directoryRoles/cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8?api-version=1.6
Response
Status Code:200
Content-Type: application/json
{
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRole/@Element",
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8",
"deletionTimestamp": null,
"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"
}
Response List
| Status Code | Description |
|---|---|
| 200 | OK. Indicates success. The results are returned in the response body. |
Code Samples
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;
namespace CSHttpClientSample
{
static class Program
{
static void Main()
{
MakeRequest();
Console.WriteLine("Hit ENTER to exit...");
Console.ReadLine();
}
static async void MakeRequest()
{
var client = new HttpClient();
var queryString = HttpUtility.ParseQueryString(string.Empty);
/* OAuth2 is required to access this API. For more information visit:
https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */
// Specify values for the following required parameters
queryString["api-version"] = "1.6";
// Specify values for path parameters (shown as {...})
var uri = "https://graph.windows.net/myorganization/directoryRoles/{object_id}?" + queryString;
var response = await client.GetAsync(uri);
if (response.Content != null)
{
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);
}
}
}
}
@ECHO OFF
REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/directoryRoles/{object_id}?api-version=1.6&"^
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample {
public static void main(String[] args) {
HttpClient httpclient = HttpClients.createDefault();
try
{
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/directoryRoles/{object_id}");
// Specify values for the following required parameters
builder.setParameter("api-version", "1.6");
URI uri = builder.build();
HttpGet request = new HttpGet(uri);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null) {
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
$(function() {
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
var params = {
// Specify values for the following required parameters
'api-version': "1.6",
};
$.ajax({
// Specify values for path parameters (shown as {...})
url: 'https://graph.windows.net/myorganization/directoryRoles/{object_id}?' + $.param(params),
type: 'GET',
})
.done(function(data) {
alert("success");
})
.fail(function() {
alert("error");
});
});
</script>
</body>
</html>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
NSString* path = @"https://graph.windows.net/myorganization/directoryRoles/{object_id}";
NSArray* array = @[
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"GET"];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if(nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if(nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);
$query_params = array(
// Specify values for the following required parameters
'api-version' => '1.6',
);
$request = new Http_Request2('https://graph.windows.net/myorganization/directoryRoles/{object_id}');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
$url = $request->getUrl();
$url->setQueryVariables($query_params);
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = httplib.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoles/{object_id}?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.parse.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = http.client.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoles/{object_id}?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://graph.windows.net/myorganization/directoryRoles/{object_id}')
uri.query = URI.encode_www_form({
# Specify values for the following required parameters
'api-version' => '1.6',
})
request = Net::HTTP::Get.new(uri.request_uri)
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
Get directory role templates
Gets the collection of directory role templates that are available in the tenant. In version 1.5 and newer, directory role templates are used to activate directory roles. Not available in versions prior to 1.5.
On success, returns the collection of DirectoryRoleTemplate objects for the tenant; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
GET https://graph.windows.net/myorganization/directoryRoleTemplates?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| Query | |||
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
Response
Status Code:200
Content-Type: application/json
{
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRoleTemplate",
"value": [
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "729827e3-9c14-49f7-bb1b-9608f156bbb8",
"deletionTimestamp": null,
"description": "Helpdesk Administrator has access to perform common helpdesk related tasks.",
"displayName": "Helpdesk Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "f023fd81-a637-4b56-95fd-791ac0226033",
"deletionTimestamp": null,
"description": "Service Support Administrator has access to perform common support tasks.",
"displayName": "Service Support Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "b0f54661-2d74-4c50-afa3-1ec803f12efe",
"deletionTimestamp": null,
"description": "Billing Administrator has access to perform common billing related tasks.",
"displayName": "Billing Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "b5468a13-3945-4a40-b0b1-5d78c2676bbf",
"deletionTimestamp": null,
"description": "Allows access and management of users mailboxes.",
"displayName": "Mailbox Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "4ba39ca4-527c-499a-b93d-d9b492c50246",
"deletionTimestamp": null,
"description": "Allows ability to perform tier1 support tasks.",
"displayName": "Partner Tier1 Support"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "e00e864a-17c5-4a4b-9c06-f5b95a8d5bd8",
"deletionTimestamp": null,
"description": "Allows ability to perform tier2 support tasks.",
"displayName": "Partner Tier2 Support"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b",
"deletionTimestamp": null,
"description": "Allows access to various read only tasks in the directory. ",
"displayName": "Directory Readers"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "29232cdf-9323-42fd-ade2-1d097af3e4de",
"deletionTimestamp": null,
"description": "Exchange Service Administrator.",
"displayName": "Exchange Service Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "75941009-915a-4869-abe7-691bff18279e",
"deletionTimestamp": null,
"description": "Lync Service Administrator.",
"displayName": "Lync Service Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
"deletionTimestamp": null,
"description": "User Account Administrator has access to perform common user management related tasks.",
"displayName": "User Account Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "9360feb5-f418-4baa-8175-e2a00bac4301",
"deletionTimestamp": null,
"description": "Allows access read tasks and a subset of write tasks in the directory.",
"displayName": "Directory Writers"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "62e90394-69f5-4237-9190-012177145e10",
"deletionTimestamp": null,
"description": "Company Administrator role has full access to perform any operation in the company scope.",
"displayName": "Company Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "a0b1b346-4d3e-4e8b-98f8-753987be4970",
"deletionTimestamp": null,
"description": "Every user is implicitly considered to be a member of the User Role.",
"displayName": "User"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "d65e02d2-0214-4674-8e5d-766fb330e2c0",
"deletionTimestamp": null,
"description": "Allows creation of new email verified users.",
"displayName": "Email Verified User Creator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "eb1d8c34-acf5-460d-8424-c1f1a6fbdb85",
"deletionTimestamp": null,
"description": "Allows access manage AdHoc license.",
"displayName": "AdHoc License Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "f28a1f50-f6e7-4571-818b-6a12f2af6b6c",
"deletionTimestamp": null,
"description": "SharePoint Service Administrator.",
"displayName": "SharePoint Service Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "d405c6df-0af8-4e3b-95e4-4d06e542189e",
"deletionTimestamp": null,
"description": "Device Users",
"displayName": "Device Users"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "9f06204d-73c1-4d4c-880a-6edb90606fd8",
"deletionTimestamp": null,
"description": "Device Administrators",
"displayName": "Device Administrators"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "9c094953-4995-41c8-84c8-3ebb9b32c93f",
"deletionTimestamp": null,
"description": "Device Join",
"displayName": "Device Join"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "c34f683f-4d5a-4403-affd-6615e00e3a7f",
"deletionTimestamp": null,
"description": "Workplace Device Join",
"displayName": "Workplace Device Join"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "17315797-102d-40b4-93e0-432062caca18",
"deletionTimestamp": null,
"description": "Compliance administrator.",
"displayName": "Compliance Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "d29b2b05-8046-44ba-8758-1e26182fcf32",
"deletionTimestamp": null,
"description": "Directory Synchronization Accounts",
"displayName": "Directory Synchronization Accounts"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "2b499bcd-da44-4968-8aec-78e1674fa64d",
"deletionTimestamp": null,
"description": "Allows access to read and edit device properties. ",
"displayName": "Device Managers"
}
]
}
Response List
| Status Code | Description |
|---|---|
| 200 | OK. Indicates success. The results are returned in the response body. |
Code Samples
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;
namespace CSHttpClientSample
{
static class Program
{
static void Main()
{
MakeRequest();
Console.WriteLine("Hit ENTER to exit...");
Console.ReadLine();
}
static async void MakeRequest()
{
var client = new HttpClient();
var queryString = HttpUtility.ParseQueryString(string.Empty);
/* OAuth2 is required to access this API. For more information visit:
https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */
// Specify values for the following required parameters
queryString["api-version"] = "1.6";
// Specify values for path parameters (shown as {...})
var uri = "https://graph.windows.net/myorganization/directoryRoleTemplates?" + queryString;
var response = await client.GetAsync(uri);
if (response.Content != null)
{
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);
}
}
}
}
@ECHO OFF
REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/directoryRoleTemplates?api-version=1.6&"^
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample {
public static void main(String[] args) {
HttpClient httpclient = HttpClients.createDefault();
try
{
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/directoryRoleTemplates");
// Specify values for the following required parameters
builder.setParameter("api-version", "1.6");
URI uri = builder.build();
HttpGet request = new HttpGet(uri);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null) {
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
$(function() {
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
var params = {
// Specify values for the following required parameters
'api-version': "1.6",
};
$.ajax({
// Specify values for path parameters (shown as {...})
url: 'https://graph.windows.net/myorganization/directoryRoleTemplates?' + $.param(params),
type: 'GET',
})
.done(function(data) {
alert("success");
})
.fail(function() {
alert("error");
});
});
</script>
</body>
</html>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
NSString* path = @"https://graph.windows.net/myorganization/directoryRoleTemplates";
NSArray* array = @[
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"GET"];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if(nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if(nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);
$query_params = array(
// Specify values for the following required parameters
'api-version' => '1.6',
);
$request = new Http_Request2('https://graph.windows.net/myorganization/directoryRoleTemplates');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
$url = $request->getUrl();
$url->setQueryVariables($query_params);
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = httplib.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoleTemplates?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.parse.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = http.client.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoleTemplates?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://graph.windows.net/myorganization/directoryRoleTemplates')
uri.query = URI.encode_www_form({
# Specify values for the following required parameters
'api-version' => '1.6',
})
request = Net::HTTP::Get.new(uri.request_uri)
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
Activate a directory role
Activates a directory role in the tenant. Available in version 1.5 and newer only. The request body contains the object ID of the directory role template for the directory role you want to activate.
Note: In versions prior to 1.5 all directory roles are present in the tenant by default. In versions 1.5 and newer, only the Company Administrators directory role is present by default. To access and assign members to another directory role, you must first activate it with its corresponding directory role template (DirectoryRoleTemplate).
The following table shows the properties that are required when you activate a directory role.
| Required parameter | Type | Description |
|---|---|---|
| roleTemplateId | string | The objectId of the DirectoryRoleTemplate that the role is based on. |
On success, returns the newly created DirectoryRole; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
POST https://graph.windows.net/myorganization/directoryRoles?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| Query | |||
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
| Body | ----- | ----- | ------ |
| Content-Type: application/json | ----- | ----- | ------ |
{
"roleTemplateId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
}
Response
Status Code:201
Content-Type: application/json
{
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRole/@Element",
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "ebabdd59-04ba-46f0-bd7f-bef08fe8fa9b",
"deletionTimestamp": null,
"description": "Allows access to various read only tasks in the directory. ",
"displayName": "Directory Readers",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
}
Response List
| Status Code | Description |
|---|---|
| 201 | Created. Indicates success. The newly activated directory role is returned in the response body. |
Operations on directory role navigation properties
Navigation properties represent relationships between an instance of an entity and other objects in the directory. Directory roles expose only a single navigation property, the members property. This property contains users and service principals that have been added to the directory role. You can read (GET), add (POST), and delete (DELETE) members from the directory role by targeting the members property.
Get a directory role's members
Gets the directory role's members from the members navigation property.
On success, returns a collection of links to the Users, and ServicePrincipals that are members of the directory role; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
Note: You can remove the "$links" segment from the URL to return DirectoryObjects for the users and service principals instead of links.
GET https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| URL | |||
| object_id | string | cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8 | The object ID (GUID) of the target directory role |
| Query | |||
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
GET https://graph.windows.net/myorganization/directoryRoles/cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8/$links/members?api-version=1.6
Response
Status Code:200
Content-Type: application/json
{
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/members",
"value": [
{
"url": "https://graph.windows.net/myorganization/directoryObjects/f19096bf-a58c-46ba-9ffd-0344f1daecf8/Microsoft.DirectoryServices.User"
}
]
}
Response List
| Status Code | Description |
|---|---|
| 200 | OK. Indicates success. A collection of links to the directory role members is returned. |
Code Samples
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;
namespace CSHttpClientSample
{
static class Program
{
static void Main()
{
MakeRequest();
Console.WriteLine("Hit ENTER to exit...");
Console.ReadLine();
}
static async void MakeRequest()
{
var client = new HttpClient();
var queryString = HttpUtility.ParseQueryString(string.Empty);
/* OAuth2 is required to access this API. For more information visit:
https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks */
// Specify values for the following required parameters
queryString["api-version"] = "1.6";
// Specify values for path parameters (shown as {...})
var uri = "https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members?" + queryString;
var response = await client.GetAsync(uri);
if (response.Content != null)
{
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);
}
}
}
}
@ECHO OFF
REM OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
REM Specify values for path parameters (shown as {...}), values for query parameters
curl -v -X GET "https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members?api-version=1.6&"^
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample {
public static void main(String[] args) {
HttpClient httpclient = HttpClients.createDefault();
try
{
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
URIBuilder builder = new URIBuilder("https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members");
// Specify values for the following required parameters
builder.setParameter("api-version", "1.6");
URI uri = builder.build();
HttpGet request = new HttpGet(uri);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null) {
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!DOCTYPE html>
<html>
<head>
<title>JSSample</title>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>
<script type="text/javascript">
$(function() {
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
var params = {
// Specify values for the following required parameters
'api-version': "1.6",
};
$.ajax({
// Specify values for path parameters (shown as {...})
url: 'https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members?' + $.param(params),
type: 'GET',
})
.done(function(data) {
alert("success");
})
.fail(function() {
alert("error");
});
});
</script>
</body>
</html>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
// Specify values for path parameters (shown as {...})
NSString* path = @"https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members";
NSArray* array = @[
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"GET"];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if(nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if(nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the pecl_http package. (for more information: http://pecl.php.net/package/pecl_http)
require_once 'HTTP/Request2.php';
$headers = array(
);
$query_params = array(
// Specify values for the following required parameters
'api-version' => '1.6',
);
$request = new Http_Request2('https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setHeader($headers);
// OAuth2 is required to access this API. For more information visit:
// https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
$url = $request->getUrl();
$url->setQueryVariables($query_params);
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = httplib.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoles/{object_id}/$links/members?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
headers = {
}
params = urllib.parse.urlencode({
# Specify values for the following required parameters
'api-version': '1.6',
})
try:
conn = http.client.HTTPSConnection('graph.windows.net')
# Specify values for path parameters (shown as {...}) and request body if needed
conn.request("GET", "/myorganization/directoryRoles/{object_id}/$links/members?%s" % params, "", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members')
uri.query = URI.encode_www_form({
# Specify values for the following required parameters
'api-version' => '1.6',
})
request = Net::HTTP::Get.new(uri.request_uri)
# OAuth2 is required to access this API. For more information visit: https://msdn.microsoft.com/en-us/office/office365/howto/common-app-authentication-tasks
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body
Add directory role members
Adds one or more members to a directory role through the members navigation property. You can add users or service principals. The request body contains one or more links to the Users and ServicePrincipals to add.
On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
POST https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| URL | |||
| object_id | string | cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8 | The object ID (GUID) of the target directory role. |
| Query | |||
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
| Body | ----- | ----- | ------ |
| Content-Type: application/json | ----- | ----- | ------ |
{
"url": "https://graph.windows.net/myorganization/directoryObjects/3eb6055a-baeb-44d4-a1ea-2fee86d8891b"
}
POST https://graph.windows.net/myorganization/directoryRoles/cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8/$links/members?api-version=1.6
Response
Status Code:204
Content-Type: application/json
none
Response List
| Status Code | Description |
|---|---|
| 204 | No Content. Indicates success. No response body is returned. |
Delete a directory role member
Deletes a specified member from a directory role through the members navigation property. Specify the object ID of the User or ServicePrincipal to delete in the terminal URL segment.
On success, no response body is returned; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.
DELETE https://graph.windows.net/myorganization/directoryRoles/{object_id}/$links/members/{member_id}?api-version
Parameters
| Parameter | Type | Value | Notes |
|---|---|---|---|
| URL | |||
| object_id | string | cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8 | The object ID (GUID) of the target directory role. |
| member_id | string | 3eb6055a-baeb-44d4-a1ea-2fee86d8891b | The object ID (GUID) of the member to be removed. Can be a user or a service principal. |
| Query | ----- | ----- | ------ |
| api-version | string | 1.6 | The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required. |
DELETE https://graph.windows.net/myorganization/directoryRoles/cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8/$links/members/3eb6055a-baeb-44d4-a1ea-2fee86d8891b?api-version=1.6
Response
Status Code:204
Content-Type: application/json
none
Response List
| Status Code | Description |
|---|---|
| 204 | No Content. Indicates success. No response body is returned. |
Functions and actions on directory roles
You can call any of the following functions for directory roles.
Get all group and directory role memberships (transitive)
You can call the getMemberObjects function to return all of the groups and directory roles that a user, contact, group, or service principal is a member of. The check is transitive for groups (directory roles cannot have groups or other directory roles as members).
Get objects from a list of object IDs
Call the getObjectsByObjectIds function on the directory service to return the directory objects specified in a list of object IDs. You can also specify which resource collections (users, groups, etc.) should be searched by specifying the optional types parameter. For example, you could use this function to find the directory roles in the list of object IDs returned by the getMemberObjects function above.
Additional Resources
- Learn more about Graph API supported features, capabilities, and preview features in Graph API concepts
{
"swagger": "2.0",
"info": {
"title": "DirectoryRoles"
},
"paths": {
"/directoryRoles": {
"get": {
"parameters": [
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
}
],
"responses": {
"200": {
"description": "OK. Indicates success. The results are returned in the response body.",
"examples": {
"application/json": {
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRole",
"value": [
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "02618ff0-e643-450d-b9b2-2f812364eb2c",
"deletionTimestamp": null,
"description": "Helpdesk Administrator has access to perform common helpdesk related tasks.",
"displayName": "Helpdesk Administrator",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "729827e3-9c14-49f7-bb1b-9608f156bbb8"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "044ca859-dc72-47cb-b466-7f6e78398979",
"deletionTimestamp": null,
"description": "Allows access read tasks and a subset of write tasks in the directory.",
"displayName": "Directory Writers",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "9360feb5-f418-4baa-8175-e2a00bac4301"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "44261f4c-b686-44c1-8997-310171ed4ca8",
"deletionTimestamp": null,
"description": "Allows access to various read only tasks in the directory. ",
"displayName": "Directory Readers",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8",
"deletionTimestamp": null,
"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"
}
]
}
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Contacts.Read</i></b> or <b><i>Contacts.Write</i></b></p>",
"summary": "You can get a collection of directory roles from your tenant.",
"operationId": "get directory roles"
},
"post": {
"parameters": [
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
},
{
"in": "body",
"description": "The request body, not a real parameter",
"name": "bodyparam",
"required": false,
"schema": {
"$ref": "#/definitions/directoryRole",
"example": {
"roleTemplateId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
}
}
}
],
"responses": {
"201": {
"description": "Created. Indicates success. The newly activated directory role is returned in the response body.",
"examples": {
"application/json": {
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRole/@Element",
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "ebabdd59-04ba-46f0-bd7f-bef08fe8fa9b",
"deletionTimestamp": null,
"description": "Allows access to various read only tasks in the directory. ",
"displayName": "Directory Readers",
"isSystem": true,
"roleDisabled": false,
"roleTemplateId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
}
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Directory.Write</i></b></p>",
"summary": "Activate a directory role in the tenant.",
"operationId": "activate directory role"
}
},
"/directoryRoleTemplates": {
"get": {
"parameters": [
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
}
],
"responses": {
"200": {
"description": "OK. Indicates success. The results are returned in the response body.",
"examples": {
"application/json": {
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRoleTemplate",
"value": [
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "729827e3-9c14-49f7-bb1b-9608f156bbb8",
"deletionTimestamp": null,
"description": "Helpdesk Administrator has access to perform common helpdesk related tasks.",
"displayName": "Helpdesk Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "f023fd81-a637-4b56-95fd-791ac0226033",
"deletionTimestamp": null,
"description": "Service Support Administrator has access to perform common support tasks.",
"displayName": "Service Support Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "b0f54661-2d74-4c50-afa3-1ec803f12efe",
"deletionTimestamp": null,
"description": "Billing Administrator has access to perform common billing related tasks.",
"displayName": "Billing Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "b5468a13-3945-4a40-b0b1-5d78c2676bbf",
"deletionTimestamp": null,
"description": "Allows access and management of users mailboxes.",
"displayName": "Mailbox Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "4ba39ca4-527c-499a-b93d-d9b492c50246",
"deletionTimestamp": null,
"description": "Allows ability to perform tier1 support tasks.",
"displayName": "Partner Tier1 Support"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "e00e864a-17c5-4a4b-9c06-f5b95a8d5bd8",
"deletionTimestamp": null,
"description": "Allows ability to perform tier2 support tasks.",
"displayName": "Partner Tier2 Support"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b",
"deletionTimestamp": null,
"description": "Allows access to various read only tasks in the directory. ",
"displayName": "Directory Readers"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "29232cdf-9323-42fd-ade2-1d097af3e4de",
"deletionTimestamp": null,
"description": "Exchange Service Administrator.",
"displayName": "Exchange Service Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "75941009-915a-4869-abe7-691bff18279e",
"deletionTimestamp": null,
"description": "Lync Service Administrator.",
"displayName": "Lync Service Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
"deletionTimestamp": null,
"description": "User Account Administrator has access to perform common user management related tasks.",
"displayName": "User Account Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "9360feb5-f418-4baa-8175-e2a00bac4301",
"deletionTimestamp": null,
"description": "Allows access read tasks and a subset of write tasks in the directory.",
"displayName": "Directory Writers"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "62e90394-69f5-4237-9190-012177145e10",
"deletionTimestamp": null,
"description": "Company Administrator role has full access to perform any operation in the company scope.",
"displayName": "Company Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "a0b1b346-4d3e-4e8b-98f8-753987be4970",
"deletionTimestamp": null,
"description": "Every user is implicitly considered to be a member of the User Role.",
"displayName": "User"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "d65e02d2-0214-4674-8e5d-766fb330e2c0",
"deletionTimestamp": null,
"description": "Allows creation of new email verified users.",
"displayName": "Email Verified User Creator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "eb1d8c34-acf5-460d-8424-c1f1a6fbdb85",
"deletionTimestamp": null,
"description": "Allows access manage AdHoc license.",
"displayName": "AdHoc License Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "f28a1f50-f6e7-4571-818b-6a12f2af6b6c",
"deletionTimestamp": null,
"description": "SharePoint Service Administrator.",
"displayName": "SharePoint Service Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "d405c6df-0af8-4e3b-95e4-4d06e542189e",
"deletionTimestamp": null,
"description": "Device Users",
"displayName": "Device Users"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "9f06204d-73c1-4d4c-880a-6edb90606fd8",
"deletionTimestamp": null,
"description": "Device Administrators",
"displayName": "Device Administrators"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "9c094953-4995-41c8-84c8-3ebb9b32c93f",
"deletionTimestamp": null,
"description": "Device Join",
"displayName": "Device Join"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "c34f683f-4d5a-4403-affd-6615e00e3a7f",
"deletionTimestamp": null,
"description": "Workplace Device Join",
"displayName": "Workplace Device Join"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "17315797-102d-40b4-93e0-432062caca18",
"deletionTimestamp": null,
"description": "Compliance administrator.",
"displayName": "Compliance Administrator"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "d29b2b05-8046-44ba-8758-1e26182fcf32",
"deletionTimestamp": null,
"description": "Directory Synchronization Accounts",
"displayName": "Directory Synchronization Accounts"
},
{
"odata.type": "Microsoft.DirectoryServices.DirectoryRoleTemplate",
"objectType": "RoleTemplate",
"objectId": "2b499bcd-da44-4968-8aec-78e1674fa64d",
"deletionTimestamp": null,
"description": "Allows access to read and edit device properties. ",
"displayName": "Device Managers"
}
]
}
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Contacts.Read</i></b> or <b><i>Contacts.Write</i></b></p>",
"summary": "You can get a collection of directory roles from your tenant.",
"operationId": "get directory role templates"
}
},
"/directoryRoles/{object_id}": {
"get": {
"parameters": [
{
"in": "path",
"description": "The object ID (GUID) of the target directory role.",
"name": "object_id",
"required": true,
"type": "string",
"default": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8"
},
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
}
],
"responses": {
"200": {
"description": "OK. Indicates success. The directory role is returned in the response body.",
"examples": {
"application/json": {
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.DirectoryRole/@Element",
"odata.type": "Microsoft.DirectoryServices.DirectoryRole",
"objectType": "Role",
"objectId": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8",
"deletionTimestamp": null,
"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"
}
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Contacts.Read</i></b> or <b><i>Contacts.Write</i></b></p>",
"summary": "Get a specified directory role.",
"operationId": "get directory role by id"
}
},
"/directoryRoles/{object_id}/$links/members": {
"get": {
"parameters": [
{
"in": "path",
"description": "The object ID (GUID) of the target directory role.",
"name": "object_id",
"required": true,
"type": "string",
"default": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8"
},
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
}
],
"responses": {
"200": {
"description": "OK. Indicates success. A collection of links to the directory role members is returned.",
"examples": {
"application/json": {
"odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/$links/members",
"value": [
{
"url": "https://graph.windows.net/myorganization/directoryObjects/f19096bf-a58c-46ba-9ffd-0344f1daecf8/Microsoft.DirectoryServices.User"
}
]
}
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Contacts.Read</i></b> or <b><i>Contacts.Write</i></b></p>",
"summary": "Gets the members of the directory role by link.",
"operationId": "get directory role members links"
},
"post": {
"parameters": [
{
"in": "path",
"description": "The object ID (GUID) of the target directory role.",
"name": "object_id",
"required": true,
"type": "string",
"default": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8"
},
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
},
{
"in": "body",
"description": "The request body contains one or more links to users or service principals to add to the directory role.",
"name": "bodyparam",
"required": true,
"schema": {
"required": [ "url" ],
"properties": {
"url": {
"type": "string"
}
},
"example": {
"url": "https://graph.windows.net/myorganization/directoryObjects/3eb6055a-baeb-44d4-a1ea-2fee86d8891b"
}
}
}
],
"responses": {
"204": {
"description": "No Content. Indicates success. No response body is returned.",
"examples": {
"application/json": "none"
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Contacts.Write</i></b></p>",
"summary": "Add members to a directory role.",
"operationId": "add directory role members"
}
},
"/directoryRoles/{object_id}/$links/members/{member_id}": {
"delete": {
"parameters": [
{
"in": "path",
"description": "The object ID (GUID) of the target directory role.",
"name": "object_id",
"required": true,
"type": "string",
"default": "cb5d9ae9-6e2c-41a0-9194-0d4aef426ba8"
},
{
"in": "path",
"description": "The object ID (GUID) of the member to be removed. Can be a user or a service principal.",
"name": "member_id",
"required": true,
"type": "string",
"default": "3eb6055a-baeb-44d4-a1ea-2fee86d8891b"
},
{
"in": "query",
"description": "The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.",
"name": "api-version",
"required": true,
"type": "string",
"default": "1.6"
}
],
"responses": {
"204": {
"description": "No Content. Indicates success. No response body is returned.",
"examples": {
"application/json": "none"
}
}
},
"description": "<p><i>Required scope</i>: <b><i>Contacts.Write</i></b></p>",
"summary": "Delete a user or service principal from the directory role.",
"operationId": "delete directory role member"
}
}
},
"host": "graph.windows.net",
"basePath": "/myorganization",
"schemes": [ "https" ],
"definitions": {
"directoryRole": {
"required": [
"roleTemplateId"
],
"properties": {
"objectType": {
"type": "string",
"readOnly": "true"
},
"objectId": {
"type": "string",
"readOnly": "true"
},
"deletionTimestamp": {
"type": "date-time",
"readOnly": "true"
},
"description": {
"type": "string",
"readOnly": "true"
},
"displayName": {
"type": "string",
"readOnly": "true"
},
"isSystem": {
"type": "boolean",
"readOnly": "true"
},
"roleDisabled": {
"type": "boolean",
"readOnly": "true"
},
"roleTemplateId": {
"type": "string",
"required": "true"
}
}
},
"directoryRoleTemplate": {
"properties": {
"objectType": {
"type": "string",
"readOnly": "true"
},
"objectId": {
"type": "string",
"readOnly": "true"
},
"deletionTimestamp": {
"type": "date-time",
"readOnly": "true"
},
"description": {
"type": "string",
"readOnly": "true"
},
"displayName": {
"type": "string",
"readOnly": "true"
}
}
}
}
}