Table of contents

Operations on policy | Graph API reference

Pat Altimore|Last Updated: 3/28/2018
|
3 Contributors

Applies to: Graph API | Azure Active Directory

Policies are custom rules that can be enforced on applications, service principals, groups, or the entire organization they are assigned to. There are currently only two types of policies available:

  • Token Lifetime Policy: specifies the lifetime duration of tokens issued for applications and service principals.
  • Token Issuance Policy: specifies characteristics of SAML tokens issued by Azure AD.
Important

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.

Performing REST operations on policy

To perform operations on organizational policy with the Graph API, you send HTTP requests with a supported method (GET, POST, PATCH, PUT, or DELETE) to an endpoint that targets the policies resource collection, a specific policy, a navigation property of a policy, or a function or action that can be called on a policy.

Graph API requests use the following basic URL:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}[odata_query_parameters]
Important

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 policies in your tenant, an individual policy, or a navigation property of a specific policy.

  • /policies targets the policy resource collection. You can use this resource path to read all policy or a filtered list of policies in your tenant.
  • /policies/{object_id} targets an individual policy in your tenant. You specify the target policy with its object ID (GUID). You can use this resource path to get the declared properties of a policy. For policies that are not synced from an on-premises directory, you can use this resource path to modify the declared properties of a policy, or to delete a policy.
  • /policies/{object_id}/{nav_property} targets the specified navigation property of a policy. You can use it to return the object or objects referenced by the target navigation property of the specified policy. Note: This form of addressing is only available for reads.
  • /policies/{object_id}/$links/{nav_property} targets the specified navigation property of a policy. You can use this form of addressing to both read and modify a navigation property. On reads, the objects referenced by the property are returned as one or more links in the response body.

Get policy

Retrieve the properties of a policy.

On success, returns the details of the policy; otherwise, the response body contains error details. For more information about errors, see Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/policies/{object_id}?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe policy object ID.
Query
api-versionstringSpecifies the version of the Graph API to target. Required.

Requested URL

GET https://graph.windows.net/myorganization/policies/{object_id}?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Policy/@Element",
  "value": [
    {
      "alternativeIdentifier": null,
      "definition": [
        "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
      ],
      "deletionTimestamp": null,
      "displayName": "CustomTokenLifetimePolicy",
      "isTenantDefault": false,
      "objectId": "67efc1a7-5774-4ad4-bda4-672fffdb4d40",
      "objectType": "Policy",
      "keyCredentials": [],
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "type": "TokenLifetimePolicy"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. The policy is returned in the response body.

Create a policy

Create a new policy object by specifying display name, policy type, and policy description.

On success, returns the policy object in the response body; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

POST https://graph.windows.net/myorganization/policies?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstringThe version of the Graph API to target. Required.
Body
Content-Type: application/json
{
  "displayName": "CustomTokenLifetimePolicy",
  "definition": [
    "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
  ],
  "type": "TokenLifetimePolicy"
}

Requested URL

POST https://graph.windows.net/myorganization/policies?api-version

Response

Status Code:201
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Policy",
  "value": [
    {
      "alternativeIdentifier": null,
      "definition": [
        "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
      ],
      "deletionTimestamp": null,
      "displayName": "CustomTokenLifetimePolicy",
      "isTenantDefault": false,
      "objectId": "67efc1a7-5774-4ad4-bda4-672fffdb4d40",
      "objectType": "Policy",
      "keyCredentials": [],
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "type": "TokenLifetimePolicy"
    }
  ]
}

Response List

Status CodeDescription
201Created. Indicates success. Returns policy object in the response body.

Request

POST https://graph.windows.net/myorganization/policies?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstringThe version of the Graph API to target. Required.
Body
Content-Type: application/json
{
  "displayName": "CustomTokenIssuancePolicy",
  "definition": [
    "{ \"TokenIssuancePolicy\":{\"TokenResponseSigningPolicy\":\"TokenOnly\",\"SamlTokenVersion\":\"1.1\",\"SigningAlgorithm\":\"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256\",\"Version\":1}}"
  ],
  "type": "TokenIssuancePolicy"
}

Requested URL

POST https://graph.windows.net/myorganization/policies?api-version

Response

Status Code:201
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Policy",
  "value": [
    {
      "alternativeIdentifier": null,
      "definition": [
        "{ \"TokenIssuancePolicy\":{\"TokenResponseSigningPolicy\":\"TokenOnly\",\"SamlTokenVersion\":\"1.1\",\"SigningAlgorithm\":\"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256\",\"Version\":1}}"
      ],
      "deletionTimestamp": null,
      "displayName": "CustomTokenIssuancePolicy",
      "isTenantDefault": false,
      "objectId": "76c1a417-c023-49fa-9893-1db93e2672a4",
      "objectType": "Policy",
      "keyCredentials": [],
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "type": "TokenIssuancePolicy"
    }
  ]
}

Response List

Status CodeDescription
201Created. Indicates success. Returns policy object in the response body.

List policies

Retrieve all policy objects in the directory.

On success, returns a collection of policy objects; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/policies?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstringSpecifies the version of the Graph API to target. Required.

Requested URL

GET https://graph.windows.net/myorganization/policies?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Policy",
  "value": [
    {
      "alternativeIdentifier": null,
      "definition": [
        "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
      ],
      "deletionTimestamp": null,
      "displayName": "CustomTokenLifetimePolicy",
      "isTenantDefault": false,
      "objectId": "67efc1a7-5774-4ad4-bda4-672fffdb4d40",
      "objectType": "Policy",
      "keyCredentials": [],
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "type": "TokenLifetimePolicy"
    },
    {
      "alternativeIdentifier": null,
      "definition": [
        "{ \"TokenIssuancePolicy\":{\"TokenResponseSigningPolicy\":\"TokenOnly\",\"SamlTokenVersion\":\"1.1\",\"SigningAlgorithm\":\"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256\",\"Version\":1}}"
      ],
      "deletionTimestamp": null,
      "displayName": "CustomTokenIssuancePolicy",
      "isTenantDefault": false,
      "objectId": "76c1a417-c023-49fa-9893-1db93e2672a4",
      "objectType": "Policy",
      "keyCredentials": [],
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "type": "TokenIssuancePolicy"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. The results are returned in the response body.

Update policy

Update properties in a preexisting policy.

On success, no content is returned; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

PATCH https://graph.windows.net/myorganization/policies/{object_id}?api-version

Parameters

ParameterTypeValueNotes
URL
policy_idstringThe policy object ID.
Query
api-versionstringThe version of the Graph API to target. Required.
Body
Content-Type: application/json
{
  "displayName": "MyTokenLifetimePolicy"
}

Requested URL

PATCH https://graph.windows.net/myorganization/policies/{object_id}?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

Delete policy

Delete a policy.

On success, no content is returned; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

DELETE https://graph.windows.net/myorganization/policies/{object_id}?api-version

Parameters

ParameterTypeValueNotes
URL
policy_idstringThe policy object ID.
Query
api-versionstringThe version of the Graph API to target. Required.

Requested URL

DELETE https://graph.windows.net/myorganization/policies/{object_id}?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success.

Operations on policy navigation properties

Relationships between a policy and other objects in the directory such as applications or service principals are exposed through navigation properties. You can read and, in some cases, modify these relationships by targeting these navigation properties in your requests.

Assign a policy

Assigns a policy to an application or service principal.

On success, returns the policy object for the new policy; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

POST https://graph.windows.net/myorganization/applications/{object_id}/$links/policies?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object id of the application or service principal (not the appid property).
Query
api-versionstringThe version of the Graph API to target. Required.
Body
Content-Type: application/json
{
  "url": "https://graph.windows.net/myorganization/policies/092a6e8a-e25d-42b8-8151-c105445150ee"
}

Requested URL

POST https://graph.windows.net/myorganization/applications/{object_id}/$links/policies?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success.

Request

POST https://graph.windows.net/myorganization/serviceprincipals/{object_id}/$links/policies?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object id of the service principal.
Query
api-versionstringThe version of the Graph API to target. Required.
Body
Content-Type: application/json
{
  "url": "https://graph.windows.net/myorganization/policies/092a6e8a-e25d-42b8-8151-c105445150ee"
}

Requested URL

POST https://graph.windows.net/myorganization/serviceprincipals/{object_id}/$links/policies?api-version

Response

Status Code:204
Content-Type:
  • application/json

Response List

Status CodeDescription
204No Content. Indicates success.

List applications and service principals with specific policy assigned

Retrieve the application and service principal objects with the specified policy assigned.

On success, returns the application and service principal objects for the policy in the response body; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/policies/{policy_id}/appliesTo?api-version

Parameters

ParameterTypeValueNotes
URL
policy_idstringThe policy object ID.
Query
api-versionstringSpecifies the version of the Graph API to target. Required.

Requested URL

GET https://graph.windows.net/myorganization/policies/{policy_id}/appliesTo?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Application",
      "objectType": "Application",
      "objectId": "ee24265c-66f8-49d2-a27d-51682f341034",
      "deletionTimestamp": null,
      "addIns": [],
      "appId": "d36c7e02-000d-4649-b711-6f3f3d17fc69",
      "appRoles": [],
      "availableToOtherTenants": true,
      "displayName": "My App",
      "errorUrl": null,
      "groupMembershipClaims": null,
      "homepage": null,
      "identifierUris": [],
      "keyCredentials": [],
      "knownClientApplications": [],
      "logoutUrl": null,
      "oauth2AllowImplicitFlow": false,
      "oauth2AllowUrlPathMatching": false,
      "oauth2Permissions": [],
      "oauth2RequirePostResponse": false,
      "passwordCredentials": [],
      "publicClient": true,
      "recordConsentConditions": null,
      "replyUrls": [],
      "requiredResourceAccess": [],
      "samlMetadataUrl": null
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. Object IDs are returned in the response body for which the policy applies to.

List policies assigned to application or service principal

Retrieve the policy objects assigned to an application or service principal.

On success, returns the application or service principal objects for the policy in the response body; otherwise, a code and associated message is returned with the error. For more information about errors, see Error Codes and Error Handling.

Request

GET https://graph.windows.net/myorganization/applications/{object_id}/policies?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object id of the application or service principal (not the appid property).
Query
api-versionstringThe version of the Graph API to target. Required.

Requested URL

GET https://graph.windows.net/myorganization/applications/{object_id}/policies?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/AltimoreBreweryNSausageCo.onmicrosoft.com/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "objectType": "Policy",
      "objectId": "85d03130-ed36-49ae-ac48-ad23dded599f",
      "deletionTimestamp": null,
      "alternativeIdentifier": null,
      "definition": [
        "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
      ],
      "displayName": "CustomTokenLifetimePolicy",
      "isTenantDefault": false,
      "keyCredentials": [],
      "type": "TokenLifetimePolicy"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. Policy assigned to the application is returned in the response body.

Request

GET https://graph.windows.net/myorganization/serviceprincipals/{object_id}/policies?api-version

Parameters

ParameterTypeValueNotes
URL
object_idstringThe object id of the application or service principal (not the appid property).
Query
api-versionstringThe version of the Graph API to target. Required.

Requested URL

GET https://graph.windows.net/myorganization/serviceprincipals/{object_id}/policies?api-version

Response

Status Code:200
Content-Type:
  • application/json
{
  "odata.metadata": "https://graph.windows.net/AltimoreBreweryNSausageCo.onmicrosoft.com/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Policy",
      "objectType": "Policy",
      "objectId": "85d03130-ed36-49ae-ac48-ad23dded599f",
      "deletionTimestamp": null,
      "alternativeIdentifier": null,
      "definition": [
        "{\"TokenLifetimePolicy\":{\"Version\":1,\"AccessTokenLifetime\":\"8:00:00\"}}"
      ],
      "displayName": "CustomTokenLifetimePolicy",
      "isTenantDefault": false,
      "keyCredentials": [],
      "type": "TokenLifetimePolicy"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. Policy assigned to the application is returned in the response body.

Additional Resources

  • Learn more about Graph API supported features, capabilities, and preview features in Graph API concepts

2
[Application]: ./entity-and-complex-type-reference.md#application-entity [AppRoleAssignment]: ./entity-and-complex-type-reference.md#approleassignment-entity [Contact]: ./entity-and-complex-type-reference.md#contact-entity [Contract]: ./entity-and-complex-type-reference.md#contract-entity [Device]: ./entity-and-complex-type-reference.md#device-entity [DirectoryLinkChange]: ./entity-and-complex-type-reference.md#directorylinkchange-entity [DirectoryObject]: ./entity-and-complex-type-reference.md#directoryobject-entity [DirectoryRole]: ./entity-and-complex-type-reference.md#directoryrole-entity [DirectoryRoleTemplate]: ./entity-and-complex-type-reference.md#directoryroletemplate-entity [Domain (preview)]: ./entity-and-complex-type-reference.md#domain-entity [DomainDnsRecord]: ./entity-and-complex-type-reference.md#domaindnsrecord-entity [DomainDnsCnameRecord]: ./entity-and-complex-type-reference.md#domaindnscnamerecord-entity [DomainDnsMxRecord]: ./entity-and-complex-type-reference.md#domaindnsmxrecord-entity [DomainDnsSrvRecord]: ./entity-and-complex-type-reference.md#domaindnssrvrecord-entity [DomainDnsTxtRecord]: ./entity-and-complex-type-reference.md#domaindnstxtrecord-entity [DomainDnsUnavailableRecord]: ./entity-and-complex-type-reference.md#domaindnsunavailablerecord-entity [ExtensionProperty]: ./entity-and-complex-type-reference.md#extensionproperty-entity [Group]: ./entity-and-complex-type-reference.md#group-entity [OAuth2PermissionGrant]: ./entity-and-complex-type-reference.md#oAuth2permissiongrant-entity [ServicePrincipal]: ./entity-and-complex-type-reference.md#serviceprincipal-entity [SubscribedSku]: ./entity-and-complex-type-reference.md#subscribedsku-entity [TenantDetail]: ./entity-and-complex-type-reference.md#tenantdetail-entity [User]: ./entity-and-complex-type-reference.md#user-entity

© 2018 Microsoft