Understanding the Intune device object and User Principal Name

By Mark Stanfill - Sr. Support Escalation Engineer | Microsoft Intune

 

IT admins working with PowerShell scripts may encounter a common issue where the User Principal Name (UPN) value at the device level does not match the UPN in the portal. The Intune device object contains several fields related to the UPN of the device. These fields each refer to a user object, but the relationship is not always intuitive based on the name of the property alone. This article details why this is, how to correctly obtain the primary user value, and some common questions we receive regarding how to modify this field.

 

Relationship between Intune user and device objects and Azure Active Directory (Azure AD)

 

Intune device objects represent an instance of a /deviceManagement/managedDevices object (in other words, an oData type #microsoft.graph.managedDevice object). They are commonly queried using a URI in the following format, where {managedDeviceId} is the Intune device ID.

 

https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/{managedDeviceID}

 

 

 

Azure AD also has a device object. This is the base object that the Intune managedDevice class is derived from. Azure AD device objects are queried using the following URI:

 

https://graph.microsoft.com/v1.0/devices/{Azure AD_Object ID}

 

 

 

Both services have an "ID” attribute to uniquely identify objects. The Azure AD ID field refers to the object ID, while the Intune ID field is the Intune device ID.

 

Note that Intune never directly references the Azure AD device object. Any modifications in the Endpoint Manager admin center are replicated from Intune managedDevice to the Azure AD device object. Changes made in Azure AD are similarly replicated back to Intune to keep the two records in sync.

 

The Intune managedDevice object’s AzureADDeviceId attribute is a reference to the Azure AD device object’s ID attribute.

 

Example

For the purpose of this article, we will use a test tenant device example with the following attributes to illustrate how to interact with Intune managed devices:

• Intune device ID: e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx
• User ID: 3c2784cc-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Azure AD device ID: e2a083c9-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Azure AD object ID: c15ae6a3-xxxx-xxxx-xxxx-xxxxxxxxxxxx

 

Conventions used in this article: {userId} refers to the Azure AD user ID attribute of a user object. {managedDeviceId} refers to the Intune device ID, while {deviceId} refers to the Azure AD device object’s ID field. The Intune service does not have a separate object for users and, therefore, uses the Azure AD user object for all operations. Intune managedDevices are an extension of the Azure AD device object, so a device enrolled in Intune has both an Intune device ID and an Azure AD device ID.

 

To illustrate, in our example data Intune managedDevice masAP71 has an Intune device ID of e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx and an Azure AD device ID attribute of c15ae6a3-xxxx-xxxx-xxxxxxxxxxxx.

 

The corresponding Azure AD object: https://graph.microsoft.com/v1.0/devices/c15ae6a3-xxxx-xxxx-xxxxxxxxxxxx

 

The device’s Intune URI: https://graph.microsoft.com/beta/deviceManagement/managedDevices/e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx 

 

The example device’s (masAP71) Intune device ID and Azure AD device ID attributes as they correspond to their respective device ID and object ID identifiers.

 

Graph Explorer is a useful tool to investigate the underlying Graph API object data. By querying the device objects in both services, we see the relationship between the ID, deviceID, and AzureAD deviceID attributes, as illustrated in the image below.

 

The Intune device ID and Azure AD device ID attributes in Microsoft Intune and how they appear in Graph API.

 

Azure AD device ID and object ID attributes as they appear in Graph API.

 

The UPN values in Graph API as they map to Azure AD and Microsoft Intune.

 

Azure AD registered owner

Azure AD devices have an associated registeredOwners object that represents either the user who cloud joined the device to Azure AD or, in the case of bring your own device (BYOD) scenarios, the user who registered their personal device. Each device has only one registered owner. The URI syntax for the Azure AD registered owner is: https://graph.microsoft.com/v1.0/devices/c15ae6a3-xxxx-xxxx-xxxx-xxxxxxxxxxxx/registeredOwners.

 

Intune registered owner

The Intune service also has an associated primary user for managedDevice objects as well as an 'Enrolled by” attribute. In addition, each user object has a {userID}\managedDevices object associated with it that lists the devices associated with the user.

 

Intune managedDevice user attributes are:

• managedDevice/userPrincipleName
  
  

  Example: https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/e46e2ba6-xxxx-xxxx-xxxx-xxxxxxxxxxxx?$select=userPrincipalName 
  Description: The UPN of the “Enrolled by” account.
  Reference: https://docs.microsoft.com/graph/api/resources/intune-devices-manageddevice?view=graph-rest-1.0
  
  

• managedDevice/userDisplayName
  
  

  Example: https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/e46e2ba6-xxxx-xxxx-xxxx-xxxxxxxxxxxx?$select=userDisplayName
  Description: The display name of the “Enrolled by” account. This value is immutable (i.e. read-only) and is only populated during device enrollment in Intune.
  Reference: https://docs.microsoft.com/graph/api/resources/intune-devices-manageddevice?view=graph-rest-1.0
  
  

• managedDevice/users/userPrincipleName
  
  

  Example: https://graph.microsoft.com/v1.0beta/deviceManagement/managedDevices/e46e2ba6-xxxx-xxxx-xxxx-xxxxxxxxxxxx/users
  Description: The “Primary user” associated with a managed device. This is the device record’s corresponding mapping of the primary user UPN value to the users/{userID}/managedDevices list in the next entry. This value cannot be modified directly, but it can be changed to another user through the Change primary user or Remove primary user actions in Endpoint Manager admin center under All devices > {Device} > Properties.
  Reference: https://docs.microsoft.com/graph/api/intune-devices-windowsmanageddevice-list?view=graph-rest-beta
  
  

• users/{userID}/managedDevices
  
  

  Example: https://graph.microsoft.com/beta/users/e46e2ba6-xxxx-xxxx-xxxx-xxxxxxxxxxxx/managedDevices
  Description: All managedDevice objects for which an account is the “Primary user”.
  Reference: https://docs.microsoft.com/graph/api/user-get?view=graph-rest-beta&tabs=http
  
  

• users/{usersID}/registeredDevices
  
  Example: https://graph.microsoft.com/v1.0/users/e2a083c9-xxxx-xxxx-xxxx-xxxxxxxxxxxx/registeredDevices?$select=id,displayName
  Description: The Azure AD device object IDs associated with a user.
  Reference: https://docs.microsoft.com/graph/api/user-list-registereddevices?view=graph-rest-beta&tabs=http
  
  

• devices/{Azure AD Device ID}/registeredOwners
  
  

  Example: https://graph.microsoft.com/v1.0/devices/98687ed8-xxxx-xxxx-xxxx-xxxxxxxxxxxx/registeredOwners
  Description: The Azure AD user who cloud joined the device or registered it as their personal device. The registered owner is set at the time of registration.
  Reference: https://docs.microsoft.com/graph/api/device-list-registeredowners?view=graph-rest-1.0&tabs=http

 

Azure AD PowerShell Cmdlets

The Azure AD device object can be queried by display name, (Azure AD) device ID, or object ID. The object ID is commonly used.

 

# retrieve the Azure AD device attributes

Get-AzureADDevice -Filter "displayname eq 'mas-win11vm'" | Select-Object displayname, objectid, deviceid, objecttype

# get the registered owner from Azure AD

Get-AzureADDevice -Filter "displayname eq 'mas-win11vm'" | Get-AzureADDeviceRegisteredOwner

# get registered user of Azure AD device

Get-AzureADDevice -Filter "displayname eq 'mas-win11vm'" | Get-AzureADDeviceRegisteredUser

 

 

A screenshot of the query results for retrieving Azure AD device attributes.

 

 

# retrieve the Intune device attributes

Get-IntuneManagedDevice -managedDeviceId e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx

# get device ids
Get-IntuneManagedDevice -managedDeviceId e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx | select id, managedDeviceId, azureADDeviceId

# get primary user
(Invoke-MSGraphRequest -HttpMethod GET -Url https://graph.microsoft.com/beta/deviceManagement/managedDevices/e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx/users).value.userPrincipalName

 

 

A screenshot of the query results for retrieving the Intune device attributes.

 

What happens when you change the primary user ID?

You can change the primary user either from the Microsoft Endpoint Manager admin center under All devices > Device > Properties > Change primary user, or from Graph API by sending an HTTP POST command to: https://graph.microsoft.com/beta/deviceManagement/managedDevices/{'managedDeviceID'}/users/$ref. This API invokes various underlying database calls to modify both the Intune and Azure AD databases with the correct user ID reference.

 

Example: The following command in Graph Explorer will change the primary user to ‘Michel’ (user ID ‘3c2784cc-xxxx-xxxx-xxxx-xxxxxxxxxxxx’) in our test tenant.

• URI: https://graph.microsoft.com/beta/deviceManagement/managedDevices('e46e2ba6-xxxx-xxxx-xxxxxxxxxxxx')/users/$ref
• Verb: POST
• Body: { "@odata.id": "https://graph.microsoft.com/beta/users/xxxx-xxxx-xxxx-xxxxxxxxxxxx"}

 

A script demonstrating how to use this API is also available in the Intune PowerShell Samples repository on GitHub.

 

 

A screenshot of the HTTP POST command example in Graph API.

 

Key values after changing the primary user ID:

• /deviceManagement/managedDevices/{DeviceID}/userPrincipalName – no change (this is the enrolled by value; immutable)
• /deviceManagement/managedDevices/{DeviceID}/users/userPrincipalName – updated to new UPN.
• /deviceManagement/managedDevices/{DeviceID}/users – updated to new user ID information. This value is a pointer to the /users object.
• /users/{userID}/registeredDevices – device ID is added to this list. Record is a pointer to /devices/{deviceID}. Reference is removed from previous user if it was present.
• /devices/{deviceID}/registeredOwners – updated with a pointer to the /users/{userID} record.
• /devices/{deviceID}/registeredUsers - updated with a pointer to the /users/{userID} record.

 

Key takeaways tips, and advice

The Intune and Azure AD device records are related. Intune inherits from Azure AD.

 

There are two UPN values in Intune: the userPrincipleName at the device level is the ‘Enrolled by’ user, the ‘Primary user’ account is found one level deeper at the managedDevices/{Device ID}/users level.

 

Both the primary user and enrolled by user are shown on the device Overview blade in Intune. Only the ”primary user” value is displayed in the device Properties blade. The primary user attribute of an Intune device is optional. For multi-user scenarios the value will be blank.

 

Changing the device ownership of a device requires an HTTP POST command to managedDevices/{'managedDeviceID'}/users/$ref. The value cannot be edited directly (for example, by using an HTTP patch command to the device).

 

Graph URIs that begin with https://graph.microsoft.com/v1.0/devices are Azure AD records. Graph URIs that begin with https://graph.microsoft.com/v1.0/deviceManagement/managedDevices are Intune records.

 

Intune-managed devices have both Azure AD and Intune device records. User objects exist only in Azure AD and are referenced from Intune.

 

If in doubt when managing Intune devices, use the Intune APIs rather than Azure AD directly. This ensures that the action is logged in the Intune audit log, making it easier to find.

 

There will always be some latency in replicating values between Azure AD and Intune. If you are testing manually, wait a few minutes before refreshing objects. Automated solutions should verify that changes have replicated with an appropriate retry interval.

 

F12 developer tools and tools like Fiddler will help you understand how Intune sends commands to Graph API. Inspecting the sent URIs and payloads will help you locate the correct object in the Graph API reference. There is only one Graph API (with a v1.0 and a beta version). Anything that can be done in Intune can be done via PowerShell, Graph API, or Graph Explorer.

We hope this helps your understanding of how Intune and PowerShell work together! If you have questions or comments, reply to this post or reach out to @IntuneSuppTeam on Twitter.