Overview

Since our platform treats the email address as a unique, immutable security identifier, changing a domain requires creating a new user profile. To avoid downtime, Microsoft Entra ID (Azure AD) allows both domains to exist simultaneously so users can access their "old" profile while their "new" profile is being prepared.

The Strategy: "The User-Choice Bridge"

By configuring Microsoft to send both the primary email and all aliases (proxy addresses) during the SSO handshake, your platform's UI will allow users to choose between their old domain profile and their new domain profile. This ensures zero downtime and a self-service migration path for the end-user.

Phase 1: Entra ID Configuration

1. Verify your new domain: Add and verify the new domain in the Entra ID portal (Settings > Domain names).

2. Enable Alternate Login ID: Enable this in Entra ID settings to allow users to physically type their new email address into the Microsoft sign-in box, even while their account is still technically anchored to the old domain.

3. Assign Aliases: Ensure every user has their new email address added as a ProxyAddress (Alias) in Microsoft.

Phase 2: SSO Claims Mapping

Microsoft must be told to send more than just the primary UPN.

• Modify Enterprise App: In the Entra ID portal, go to your platform’s Enterprise Application > Single Sign-on > Attributes & Claims.

• Add Proxy Claim: Add a new claim to pass user.proxyaddresses. This allows Nexus to see that the person logging in owns two profiles.

Phase 3: Migration

1. Create New Profiles:  Create the new domain profiles in Nexus

2. Communicate: Instruct your users to logout and back into the Peoplesafe App:

   When the user logs in, Peoplesafe detects both emails in the SSO token. The user is prompted: "Select an account to continue". They must select the Peoplesafe profile that matches the new domain.
   
   See Logging into multiple accounts for examples.

3. The UPN Flip: Once all users have successfully accessed their new profiles, you can update the User Principal Name (UPN) in Microsoft to the new domain. This makes the new domain their permanent, primary identity.

4. Cleanup: The old domain profiles can then be removed from Nexus.

IT Administrator Checklist

Technical Summary for IT Teams

Note on NameID: Peoplesafe relies on the email claim. By passing the proxyaddresses array, you are providing the platform with the "evidence" it needs to link the two identities. 

The Alternate Login ID feature ensures that if a user types their new email address, Microsoft still recognizes them and sends the correct token containing both valid email strings.

Sample Powershell Scripts to get you started

Script 1: Bulk Add Aliases

This script identifies users with a Domain A (old domain) email and adds a matching Domain B (new domain) address as an alias (proxyAddress) without removing the old one.

# 1. Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.ReadWrite.All"

# 2. Define the domains
$oldDomain = "domainA.com"
$newDomain = "domainB.com"

# 3. Get users with the old domain
$users = Get-MgUser -Filter "endsWith(mail, '$oldDomain')" -All

foreach ($user in $users) {
    $alias = $user.MailNickname + "@" + $newDomain
    
    # Check if alias already exists to avoid duplicates
    if ($user.OtherMails -notcontains $alias) {
        Write-Host "Adding alias $alias to $($user.DisplayName)" -ForegroundColor Cyan
        
        # Combine existing aliases with the new one
        $newOtherMails = $user.OtherMails + $alias
        Update-MgUser -UserId $user.Id -OtherMails $newOtherMails
    }
}

Script 2: The Final "UPN Flip"

Once you are ready to finalise the migration and move users permanently to their new profiles, use this script to switch their Primary identity (UPN).

# 1. Get users currently on Domain A
$users = Get-MgUser -Filter "endsWith(userPrincipalName, '$oldDomain')" -All

foreach ($user in $users) {
    $newUPN = $user.MailNickname + "@" + $newDomain
    
    Write-Host "Switching UPN for $($user.DisplayName) to $newUPN" -ForegroundColor Yellow
    
    try {
        Update-MgUser -UserId $user.Id -UserPrincipalName $newUPN
    } catch {
        Write-Error "Failed to update $($user.DisplayName). Ensure $newDomain is verified."
    }
}