Operations on policy | Graph API reference

Article
10/21/2021

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.

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see policy resource type.

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.

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

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	85d03130-ed36-49ae-ac48-ad23dded599e	The policy object ID.
Query
api-version	string	1.6	Specifies the version of the Graph API to target. Required.

GET https://graph.windows.net/myorganization/policies/85d03130-ed36-49ae-ac48-ad23dded599e?api-version=1.6

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 Code	Description
200	OK. 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.

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

Parameters

Parameter	Type	Value	Notes
Query
api-version	string	1.6	The 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" }`

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 Code	Description
201	Created. Indicates success. Returns policy object in the response body.

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

Parameters

Parameter	Type	Value	Notes
Query
api-version	string	1.6	The 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" }`

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 Code	Description
201	Created. 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.

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

Parameters

Parameter	Type	Value	Notes
Query
api-version	string	1.6	Specifies the version of the Graph API to target. Required.

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 Code	Description
200	OK. 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.

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

Parameters

Parameter	Type	Value	Notes
URL
policy_id	string	85d03130-ed36-49ae-ac48-ad23dded599e	The policy object ID.
Query
api-version	string	1.6	The version of the Graph API to target. Required.
Body
Content-Type: application/json `{ "displayName": "MyTokenLifetimePolicy" }`

PATCH https://graph.windows.net/myorganization/policies/{object_id}?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 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.

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

Parameters

Parameter	Type	Value	Notes
URL
policy_id	string	85d03130-ed36-49ae-ac48-ad23dded599e	The policy object ID.
Query
api-version	string	1.6	The version of the Graph API to target. Required.

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

Response

Status Code:204

Content-Type: application/json

none

Response List

Status Code	Description
204	No Content. Indicates success.

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.

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

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	9bf0e152-cb65-4740-807f-0f9068b1e274	The object id of the application or service principal (not the appid property).
Query
api-version	string	1.6	The 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" }`

POST https://graph.windows.net/myorganization/applications/9bf0e152-cb65-4740-807f-0f9068b1e274/$links/policies?api-version=1.6

Response

Status Code:204

Content-Type: application/json

none

Response List

Status Code	Description
204	No Content. Indicates success.

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

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	9bf0e152-cb65-4740-807f-0f9068b1e274	The object id of the service principal.
Query
api-version	string	1.6	The 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" }`

POST https://graph.windows.net/myorganization/serviceprincipals/9bf0e152-cb65-4740-807f-0f9068b1e274/$links/policies?api-version=1.6

Response

Status Code:204

Content-Type: application/json

none

Response List

Status Code	Description
204	No 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.

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

Parameters

Parameter	Type	Value	Notes
URL
policy_id	string	85d03130-ed36-49ae-ac48-ad23dded599e	The policy object ID.
Query
api-version	string	1.6	Specifies the version of the Graph API to target. Required.

GET https://graph.windows.net/myorganization/policies/85d03130-ed36-49ae-ac48-ad23dded599e/appliesTo?api-version=1.6

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 Code	Description
200	OK. 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.

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

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	08e89827-27e1-4b28-af9d-748e228c5c2f	The object id of the application or service principal (not the appid property).
Query
api-version	string	1.6	The version of the Graph API to target. Required.

GET https://graph.windows.net/myorganization/applications/08e89827-27e1-4b28-af9d-748e228c5c2f/policies?api-version=1.6

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 Code	Description
200	OK. Indicates success. Policy assigned to the application is returned in the response body.

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

Parameters

Parameter	Type	Value	Notes
URL
object_id	string	9bf0e152-cb65-4740-807f-0f9068b1e274	The object id of the application or service principal (not the appid property).
Query
api-version	string	1.6	The version of the Graph API to target. Required.

GET https://graph.windows.net/myorganization/serviceprincipals/9bf0e152-cb65-4740-807f-0f9068b1e274/policies?api-version=1.6

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 Code	Description
200	OK. 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

Partager via

Operations on policy | Graph API reference

Performing REST operations on policy

Get policy

Create a policy

List policies

Update policy

Delete policy

Operations on policy navigation properties

Assign a policy

List applications and service principals with specific policy assigned

List policies assigned to application or service principal

Additional Resources

Ressources supplémentaires