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? 

1. If you’re using Entra ID portal to configure device registration policy settings then no action is required. 
2. 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. 
3. 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.  
4. 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