Assigning Immutable IDs in an Entra-only Environment

Overview

This guide explains how to assign Immutable IDs to Microsoft Entra users in an Entra-only environment.

The process consists of two steps:

1. Retrieve the list of users who require an Immutable ID.
2. Generate and assign a unique Immutable ID to each user.

Once completed successfully, the users will be ready for the next stage of your deployment.

Prerequisites

Before you begin, ensure you have:

• PowerShell 5.1 or PowerShell 7 installed.
• An account with permission to read and update Microsoft Entra users (for example, User Administrator or Global Administrator).
• Internet connectivity to Microsoft Graph.
• Permission to install Microsoft Graph PowerShell modules (if they are not already installed).

Step 1 – Retrieve the User List

Create a new PowerShell script (for example, GetUsers.ps1) and paste in the following script.

Configure Your Domain(s)

Replace the example domain name(s) with your organization's Microsoft Entra domain(s).

• Most organizations only need to specify a single domain.
• If users have User Principal Names (UPNs) across multiple domains, add each domain to the list below. The script will retrieve users from all specified domains.

Example – Single Domain (most common)

$domains = @(
    "contoso.com"
)

Example – Multiple Domains

$domains = @(
    "contoso.com",
    "fabrikam.com"
)

Full Script

Install-Module Microsoft.Graph.Users -Scope CurrentUser -Force

Import-Module Microsoft.Graph.Users

Connect-MgGraph -Scopes "User.Read.All"

$domains = @(
    "domainexample1.com",
    "domainexample2.com"
)

$matchedUsers = Get-MgUser -All -Property UserPrincipalName |
    Where-Object {
        $upn = $_.UserPrincipalName.ToLower()
        $domains | Where-Object { $upn.EndsWith("@$_") }
    } |
    Select-Object -ExpandProperty UserPrincipalName |
    Sort-Object

Write-Host '$users = @('

foreach ($user in $matchedUsers) {
    Write-Host "    `"$user`","
}

Write-Host ')'

Expected Output

After the script completes, you'll see output similar to:

$users = @(
    "user1@contoso.com",
    "user2@contoso.com",
    "user3@contoso.com"
)

Copy the entire output. You'll use it in the next step.

Step 2 – Generate and Assign Immutable IDs

Create a new PowerShell script (for example, GenerateImmutableIDs.ps1) and paste in the script below.

Replace the example $users array with the output copied from Step 1.

Full Script

Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Force
Import-Module Microsoft.Graph.Authentication


Connect-MgGraph -Scopes "User.ReadWrite.All"


$users = @(
    "user1@domainexample1.com",
    "user1@domainexample2.com"
)


foreach ($user in $users) {


    $immutableId = [Convert]::ToBase64String(([Guid]::NewGuid()).ToByteArray())


    Write-Host "Setting ImmutableID for $user -> $immutableId"


    $body = @{
        onPremisesImmutableId = $immutableId
    } | ConvertTo-Json


    $params = @{
        Method      = "PATCH"
        Uri         = "https://graph.microsoft.com/v1.0/users/$user"
        Body        = $body
        ContentType = "application/json"
    }


    Invoke-MgGraphRequest @params
}

Verify Success

As the script runs, you should see output similar to:

Setting ImmutableID for user1@contoso.com -> 0G4fTRgBbkq5Q1mN...
Setting ImmutableID for user2@contoso.com -> 5gVmM2zSLk6RkY1H...
Setting ImmutableID for user3@contoso.com -> G3lV0aQ6MkmW8JtD...

If the script completes without errors, the Immutable IDs have been successfully assigned to the specified users.

Troubleshooting

No users are returned

• Verify that the domain name(s) specified in the $domains array are correct.
• Confirm that users exist in Microsoft Entra with User Principal Names (UPNs) matching the specified domain(s).

Authentication fails

• Sign in using an account with sufficient Microsoft Entra permissions.
• Ensure the Microsoft Graph PowerShell modules install successfully when prompted.

Insufficient privileges

The account running the script must have permission to update Microsoft Entra user attributes (for example, User Administrator or Global Administrator).

Next Steps

After all users have been assigned Immutable IDs, proceed with the federation configuration for your environment.

Notes

• The scripts can be safely re-used for future deployments by updating the domain name(s) and user list.
• Immutable IDs are generated as random GUID-based values encoded in Base64, ensuring each user receives a unique identifier.
• If your environment contains users across multiple Microsoft Entra domains, simply include each domain in the $domains array before running the first script. For most organizations, only a single domain is required.