Important: Update to deviceRegistrationPolicy Resource Type for MS Graph Beta API Version
We have an important update to provide on MS Graph Device Registration Policy resource type currently in preview and available in beta API version. We are making some changes to resource type properties that introduce breaking changes. These changes are expected to happen in the week of September 25, 2023. To ensure continued support and functionality, and minimize impact, it’s very important that all customers take note of these changes and prioritize modifying their applications that depend on this resource type accordingly.
Why and when are we making this change?
Before we make the devcieRegistrationPolicy resource type generally available in our v1.0 API version, we need to align to MS Graph REST API best practices and design patterns. This change will be made to beta endpoint in the week of September 25, 2023, and then generally available to v1.0 endpoint later this year.
What are the Required Actions?
- If you’re using Entra ID portal to configure device registration policy settings then no action is required.
- If you’re crafting your own MS Graph API requests to configure deviceRegistrationPolicy resource type, then you need to immediately update your application to start configuring the resource type with both the new and deprecated properties.
- Once the deviceRegistrationPolicy resource type with new properties is deployed in the week of September 25, 2023, verify using GET call that you see the new properties and their values as being configured by your application.
- At a later point in time of convenience, remove the deprecated properties from your application.
What are the updates to MS Graph deviceRegistrationPolicy resource type?
- The "multiFactorAuthConfiguration" property is changing from an integer to a string value. The old integer value of “0” represented "notRequired" and “1” represented "required". The new string property will now support the values of "notRequired" and "required".
- The "appliesTo", "allowedUsers" and "allowedGroups" properties within "azureADJoin" and "azureADRegistration" are being deprecated. Instead, these will be replaced by the "allowedToJoin" and "allowedToRegister" properties, which are of the type microsoft.graph.deviceRegistrationMembership and contain one of the following values for "@odata.type":
- "#microsoft.graph.allDeviceRegistrationMembership": Indicates that all users are allowed to join or register devices.
- "#microsoft.graph.noDeviceRegistrationMembership": Indicates that no users are allowed to join or register devices.
- "#microsoft.graph.enumeratedDeviceRegistrationMembership": Indicates that a selected group or users and groups are allowed to join or register devices. Only for this value, the "allowedToJoin" or "allowedToRegister" values contain two additional properties, "users" and "groups", each being an array of user and group IDs which are allowed to join or register devices.
- The changes will be deployed to MS Graph beta endpoint the week of September 25, 2023, at which point the deprecated properties of the resource type will stop working.
- Customers should prepare to update their applications and start using the new properties of the resource type as soon as possible.
What happens to applications if they don’t use the new properties of deviceRegistrationPolicy resource type the week of September 25, 2023?
The applications will encounter an error (Bad Request) as new properties will be expected when configuring the deviceRegistrationPolicy resource type.
Can I do something now to prepare my application for this change without waiting until the week of September 25, 2023?
We recommend you modify your application immediately to configure deviceRegistrationPolicy resource type with both new and deprecated properties. The resource type available in beta endpoint today will honor both the deprecated and new properties. It will stop honoring deprecated properties during the week of September 25, 2023. Here’s an example of how you’ll use PUT to configure both new and deprecated properties.
{
"@odata.context": https://graph.microsoft.com/beta/$metadata#policies/deviceRegistrationPolicy/$entity,
"multiFactorAuthConfiguration": "notRequired",
"id": "deviceRegistrationPolicy",
"displayName": "Device Registration Policy",
"description": "Tenant-wide policy that manages initial provisioning controls using quota restrictions, additional authentication and authorization checks",
"userDeviceQuota": 20,
"azureADRegistration": {
"isAdminConfigurable": false,
"allowedToRegister": {
"@odata.type": "#microsoft.graph.allDeviceRegistrationMembership"
},
"appliesTo": "1",
"allowedUsers": [],
"allowedGroups": []
},
"azureADJoin": {
"isAdminConfigurable": true,
"allowedToJoin": {
"@odata.type": "#microsoft.graph.enumeratedDeviceRegistrationMembership",
"users": [
"a6aebac8-1faf-4ebd-9a68-727fa53376f4"
],
"groups": []
},
"appliesTo": "2",
"allowedUsers": [
"a6aebac8-1faf-4ebd-9a68-727fa53376f4"
],
"allowedGroups": [],
},
"localAdminPassword": {
"isEnabled": true
}
}
Notes:
- "multiFactorAuthConfiguration" should always be sent as a string value ("required" or "notRequired").
- users and groups list are only needed when you set microsoft.graph.deviceRegistrationMembership data type to enumerated.
When should I remove configuring old properties from my application?
If you follow our above recommendation to configure deviceRegistrationPolicy resource type with both new and deprecated properties, you can remove deprecated properties at any future time of convenience. Once the deviceRegistrationPolicy resource type is deployed with the new properties during the week of September 25, 2023, deprecated properties will be ignored by the resourceType.
Can I selectively configure the new properties from my application?
Not currently. The API supports PUT operation for update, which means you need to configure all properties of deviceRegistrationPolicy resource type.
What will the GET call return?
The deviceRegistrationPolicy resource type will return the deprecated properties until the week of September 25, 2023, after which the resource type will return the new properties.
Best regards,
Sandeep Deo (@MsftSandeep)
Principal Product Manager
Microsoft Identity Division
Learn more about Microsoft Entra:
- See recent Microsoft Entra blogs
- Dive into Microsoft Entra technical documentation
- Join the conversation on the Microsoft Entra discussion space and Twitter
- Learn more about Microsoft Security
Published on:
Learn moreRelated posts
Engage the Copilot in Viva Engage!
Did you know that you can use Copilot in Viva Engage to create more engaging posts, and get personalized suggestions how to improve your post?...
Retirement of the SharePoint SendEmail API
Retirement of the SharePoint SendEmail API from SharePoint Online - impacting both REST and CSOM API surfaces. The post Retirement of the Shar...
Microsoft Teams: Automatic location updates with building details for BYOD rooms and bookable desks
Microsoft Teams is set to roll out automatic location updates with building details for bookable desks and BYOD (bring your own device) rooms....
Microsoft 365: Create full-workload backup policies for Microsoft 365 Backup
Microsoft 365 Backup just got easier with the new feature. With this update, it is possible to automatically backup all Exchange or OneDrive u...
Microsoft 365: Multi-admin change notifications for Microsoft 365 Backup
This post highlights a new feature for Microsoft 365 Backup that allows a set of pre-defined administrators to receive email notifications for...
Microsoft 365: Perform granular file-level restore using Microsoft 365 Backup
The Microsoft 365 Backup now offers an enhanced feature that allows users to perform file-level restore at a granular level. Users can search ...
Microsoft Teams: Town halls now available in GCC-High
If you're a part of a GCC-High organization, Microsoft Teams now offers a new way for you to conduct large-scale events with ease: town halls....
Microsoft Teams: Town halls in GCC-High (Premium)
Microsoft Teams has introduced town hall capabilities for large-scale events across an organization with GCC-High premium features. This allow...
Microsoft 365: Create Dynamic rule-based backup policies for Microsoft 365 Backup
Microsoft 365 brings forth an innovative solution to streamline backup policies by offering rule-based policies that adapt to dynamic membersh...
Microsoft 365: Dedicated Backup Administrator Role for Microsoft 365 Backup
Microsoft 365 now has a dedicated Backup Administrator role specifically designed to manage administration tasks related to M365 Backup. This ...