Managing Azure AD Device registration policy with the Graph API

Microsoft has been slowly but surely adding Graph API endpoints that allow us to query and control different policy settings exposed in the various sections of the Azure AD blade. I blogged previously about the endpoint to control the Security defaults feature (/policies/identitySecurityDefaultsEnforcementPolicy endpoint), as well as some of the settings covered by the /policies/authorizationPolicy endpoint. An important policy that has no analog in the Azure AD blade just yet, can also be found under the /policies root, giving us the ability to assert control on the credentials methods for various applications and service principals.

A recent addition to the /policies root is the deviceRegistrationPolicy endpoint. As the name suggests, it allows us to query and manage the settings relating to the device registration policy, which you can find under the Azure AD blade > Devices > Device settings. Here’s what we can currently see/control:

  • id – basically the object name, read-only.
  • displayName – the name of the policy, also read-only.
  • description – some additional details on what the policy does, again read-only.
  • azureADJoin – the set of restrictions we can configure for Azure AD Join scenarios (more on them later).
  • azureADRegistration – the set of restrictions we can configure for Azure AD Device registration scenarios (more on them later).
  • multiFactorAuthConfiguration – controls the value of the “Require Multi-Factor Authentication to register or join devices with Azure AD” setting. Possible values include “1” (MFA is required) or “0” (MFA is notRequired).
  • userDeviceQuota – controls the number of devices an individual user can have in Azure AD.

And here is how the policy looks like when queried via the Graph explorer:

As you can see from the above, not all settings currently available in the Azure AD blade are exposed here. For example, Enterprise State Roaming and the Device local administrator controls. Those however can be considered separate policies and will likely be covered by other endpoints, or might as well be added to the current policy in the future. In any case, the Graph API endpoints are not intended to be 1:1 replacement for what we see in the Azure AD blade UI.

If you need to make any changes to the policy, a PUT request needs to be made against the /policies/deviceRegistrationPolicy endpoint, with the payload provided as JSON. Most of the controls are self-explanatory, but in case you want to configure restrictions on who can join or register devices, you’ll have to provide values for the corresponding azureAdJoinPolicy or azureADRegistrationPolicy resource types in your JSON. Both have very similar structure, as can be seen from the above screenshot or the documentation articles:

 "azureADJoin": {
"appliesTo": "1",
"isAdminConfigurable": true,
"allowedUsers": [],
"allowedGroups": []
}

"azureADRegistration": {
"appliesTo": "1",
"isAdminConfigurable": false,
"allowedUsers": [],
"allowedGroups": []
}

 

The appliesTo property represents the scoping controls for the policy. Possible values are: 0 (no one is allowed, “None” in the Azure AD blade), 1 (everyone is allowed, “All” in the Azure AD blade), 2 (selected users/groups are allowed, “Selected” in the Azure AD blade), and 3 (unknownFutureValue). Should you go for the “selected” scenario, you are required to provide values for the user or group objects that will be allowed to join/register devices, in the allowedUsers or allowedGroups properties correspondingly. Lastly, if Office 365 MDM or Intune is in use in the tenant, the azureADRegistrationPolicy controls will be “locked”, with the isAdminConfigurableĀ  value set to 0 (“false”).

And that’s it, in a nutshell. One important thing to note is, that at least for the time being, the endpoint seems to only support delegate permissions, more specifically Policy.ReadWrite.DeviceConfiguration. Hopefully support for application permissions will be added once this is released to GA.

This entry was posted in Azure AD, Graph API, Microsoft 365, Office 365. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.