Breaking change: policy API update in Microsoft Graph beta

Microsoft identity platform team

September 5th, 2019 0

By the end of September, we plan to make some changes to the Azure Active Directory (Azure AD) policy API. Currently, there’s a single policy resource type, which contains:

a type property indicating the actual policy type, and
a definition string collection property which contains the JSON formatted policy definition. The schema for the definition is dependent on the policy type and is only discoverable through documentation.

The breaking change will replace the existing policies collection with a policies URL segment. Under the policies segment we will group multiple typed policy resources. See below for more details.

Why the change?

We want to make it easier for developers to discover all policies in one place as we introduce more Azure AD and identity policies. Some of these policies are already in Microsoft Graph beta. So, we’re introducing a new policies segment to group all our typed policies underneath. See the following example that shows the policy resource before and after the change.

Example

Policy resource before the change

Currently to list policies, the request and response would look something like this:

Request

GET https://graph.microsoft.com/beta/policies

Response

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#policies",
  "values": [
      {
          "id": "guid1",
          "displayName":"usertokens",
          "isOrganizationDefault": true,
          "definition": ["JSON policy definition1"],
          "type": "TokenLifetimePolicy"
      },
      {
          "id": "guid2",
          "displayName":"accesstokens",
          "isOrganizationDefault": false,
          "definition": ["JSON policy definition2]",
          "type": "TokenLifetimePolicy"
      }
  ]
}

After the change

Different typed policies will now be grouped under a /policies segment. policies will no longer be a collection of policy instances. For each type of policy, there will now be a new typed policy resource. For example, there is a TokenLifetimePolicy type as part of the existing policy resource; after the change there will be a new tokenLifetimePolicy resource type. Putting this all together:

Request

GET https://graph.microsoft.com/beta/policies/tokenLifetimePolicies

Response

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#policies/tokenLifetimePolicies",
  "values": [
      {
          "id": "guid1",
          "displayName":"usertokens",
          "isOrganizationDefault": true,
          "definition": ["JSON policy definition1"]
      },
      {
          "id": "guid2",
          "displayName":"accesstokens",
          "isOrganizationDefault": false,
          "definition": ["JSON policy definition2"]
      }
  ]
}

Other fully schematized policies will start to show up under the /policies segment too:

Tell us what you think

We welcome your feedback. If you have further questions, you can reach out to us on StackOverflow.

-The Microsoft identity platform team