This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Note
Sign-in to Microsoft Entra ID with email as an alternate login ID is a public preview feature of Microsoft Entra ID. For more information about previews, see Supplemental Terms of Use for Microsoft Azure Previews.
Many organizations want to let users sign in to Microsoft Entra ID using the same credentials as their on-premises directory environment. With this approach, known as hybrid authentication, users only need to remember one set of credentials.
Some organizations haven't moved to hybrid authentication for the following reasons:
To move toward hybrid authentication, you can configure Microsoft Entra ID to let users sign in with their email as an alternate login ID. For example, if Contoso rebranded to Fabrikam, rather than continuing to sign in with the legacy ana@contoso.com UPN, email as an alternate login ID can be used. To access an application or service, users would sign in to Microsoft Entra ID using their non-UPN email, such as ana@fabrikam.com.
This article shows you how to enable and use email as an alternate login ID.
Here's what you need to know about email as an alternate login ID:
unique_name and preferred_username claims (if present) in the ID token will return the non-UPN email.
In the current preview state, the following limitations apply to email as an alternate login ID:
User experience - Users may see their UPN, even when they signed-in with their non-UPN email. The following example behavior may be seen:
login_hint=<non-UPN email>.Unsupported flows - Some flows are currently not compatible with non-UPN emails, such as the following:
Unsupported scenarios - The following scenarios are not supported. Sign-in with non-UPN email for:
Unsupported apps - Some third-party applications may not work as expected if they assume that the unique_name or preferred_username claims are immutable or will always match a specific user attribute, such as UPN.
Logging - Changes made to the feature's configuration in HRD policy are not explicitly shown in the audit logs.
Staged rollout policy - The following limitations apply only when the feature is enabled using staged rollout policy:
Duplicate values - Within a tenant, a cloud-only user's UPN can be the same value as another user's proxy address synced from the on-premises directory. In this scenario, with the feature enabled, the cloud-only user will not be able to sign in with their UPN. More on this issue in the Troubleshoot section.
To sign in to Microsoft Entra ID, users enter a value that uniquely identifies their account. Historically, you could only use the Microsoft Entra UPN as the sign-in identifier.
For organizations where the on-premises UPN is the user's preferred sign-in email, this approach was great. Those organizations would set the Microsoft Entra UPN to the exact same value as the on-premises UPN, and users would have a consistent sign-in experience.
However, in some organizations the on-premises UPN isn't used as a sign-in identifier. In the on-premises environments, you would configure the local AD DS to allow sign-in with an alternate login ID. Setting the Microsoft Entra UPN to the same value as the on-premises UPN isn't an option as Microsoft Entra ID would then require users to sign in with that value.
The typical workaround to this issue was to set the Microsoft Entra UPN to the email address the user expects to sign in with. This approach works, though results in different UPNs between the on-premises AD and Microsoft Entra ID, and this configuration isn't compatible with all Microsoft 365 workloads.
A different approach is to synchronize the Microsoft Entra ID and on-premises UPNs to the same value and then configure Microsoft Entra ID to allow users to sign in to Microsoft Entra ID with a verified email. To provide this ability, you define one or more email addresses in the user's ProxyAddresses attribute in the on-premises directory. ProxyAddresses are then synchronized to Microsoft Entra ID automatically using Microsoft Entra Connect.
| Option | Description |
|---|---|
| Alternate Login ID for AD FS | Enable sign-in with an alternate attribute (such as Mail) for AD FS users. |
| Alternate Login ID in Microsoft Entra Connect | Synchronize an alternate attribute (such as Mail) as the Microsoft Entra UPN. |
| Email as an Alternate Login ID | Enable sign-in with verified domain ProxyAddresses for Microsoft Entra users. |
Traditional Active Directory Domain Services (AD DS) or Active Directory Federation Services (AD FS) authentication happens directly on your network and is handled by your AD DS infrastructure. With hybrid authentication, users can instead sign in directly to Microsoft Entra ID.
To support this hybrid authentication approach, you synchronize your on-premises AD DS environment to Microsoft Entra ID using Microsoft Entra Connect and configure it to use PHS or PTA. For more information, see Choose the right authentication method for your Microsoft Entra hybrid identity solution.
In both configuration options, the user submits their username and password to Microsoft Entra ID, which validates the credentials and issues a ticket. When users sign in to Microsoft Entra ID, it removes the need for your organization to host and manage an AD FS infrastructure.
One of the user attributes that's automatically synchronized by Microsoft Entra Connect is ProxyAddresses. If users have an email address defined in the on-premises AD DS environment as part of the ProxyAddresses attribute, it's automatically synchronized to Microsoft Entra ID. This email address can then be used directly in the Microsoft Entra sign-in process as an alternate login ID.
Important
Only emails in verified domains for the tenant are synchronized to Microsoft Entra ID. Each Microsoft Entra tenant has one or more verified domains, for which you have proven ownership, and are uniquely bound to your tenant.
For more information, see Add and verify a custom domain name in Microsoft Entra ID.
Email as an alternate login ID applies to Microsoft Entra B2B collaboration under a "bring your own sign-in identifiers" model. When email as an alternate login ID is enabled in the home tenant, Microsoft Entra users can perform guest sign in with non-UPN email on the resource tenant endpoint. No action is required from the resource tenant to enable this functionality.
Note
When an alternate login ID is used on a resource tenant endpoint that does not have the functionality enabled, the sign-in process will work seamlessly, but SSO will be interrupted.
Note
This configuration option uses HRD policy. For more information, see homeRealmDiscoveryPolicy resource type.
Once users with the ProxyAddresses attribute applied are synchronized to Microsoft Entra ID using Microsoft Entra Connect, you need to enable the feature for users to sign in with email as an alternate login ID for your tenant. This feature tells the Microsoft Entra login servers to not only check the sign-in identifier against UPN values, but also against ProxyAddresses values for the email address.
You can use either Microsoft Entra admin center or Graph PowerShell to set up the feature.
Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.
Browse to Identity > Hybrid management > Microsoft Entra Connect > Connect Sync
Select Email as alternate login ID**.
Click the checkbox next to Email as an alternate login ID.
Click Save.
With the policy applied, it can take up to one hour to propagate and for users to be able to sign in using their alternate login ID.
Note
This configuration option uses HRD policy. For more information, see homeRealmDiscoveryPolicy resource type.
Once users with the ProxyAddresses attribute applied are synchronized to Microsoft Entra ID using Microsoft Entra Connect, you need to enable the feature for users to sign-in with email as an alternate login ID for your tenant. This feature tells the Microsoft Entra login servers to not only check the sign-in identifier against UPN values, but also against ProxyAddresses values for the email address.
A Global Administrator is needed to manage this feature.
Open a PowerShell session as an administrator, then install the Microsoft.Graph module using the Install-Module cmdlet:
Install-Module Microsoft.Graph
For more information on installation, see Install the Microsoft Graph PowerShell SDK.
Sign-in to your Microsoft Entra tenant using the Connect-MgGraph cmdlet:
Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration" -TenantId organizations
The command will ask you to authenticate using a web browser.
Check if a HomeRealmDiscoveryPolicy already exists in your tenant using the Get-MgPolicyHomeRealmDiscoveryPolicy cmdlet as follows:
Get-MgPolicyHomeRealmDiscoveryPolicy
If there's no policy currently configured, the command returns nothing. If a policy is returned, skip this step and move on to the next step to update an existing policy.
To add the HomeRealmDiscoveryPolicy to the tenant, use the New-MgPolicyHomeRealmDiscoveryPolicy cmdlet and set the AlternateIdLogin attribute to "Enabled": true as shown in the following example:
$AzureADPolicyDefinition = @(
@{
"HomeRealmDiscoveryPolicy" = @{
"AlternateIdLogin" = @{
"Enabled" = $true
}
}
} | ConvertTo-JSON -Compress
)
$AzureADPolicyParameters = @{
Definition = $AzureADPolicyDefinition
DisplayName = "BasicAutoAccelerationPolicy"
AdditionalProperties = @{ IsOrganizationDefault = $true }
}
New-MgPolicyHomeRealmDiscoveryPolicy @AzureADPolicyParameters
When the policy has been successfully created, the command returns the policy ID, as shown in the following example output:
Definition DeletedDateTime Description DisplayName Id IsOrganizationDefault
---------- --------------- ----------- ----------- -- ---------------------
{{"HomeRealmDiscoveryPolicy":{"AlternateIdLogin":{"Enabled":true}}}} BasicAutoAccelerationPolicy HRD_POLICY_ID True
If there's already a configured policy, check if the AlternateIdLogin attribute is enabled, as shown in the following example policy output:
Definition DeletedDateTime Description DisplayName Id IsOrganizationDefault
---------- --------------- ----------- ----------- -- ---------------------
{{"HomeRealmDiscoveryPolicy":{"AlternateIdLogin":{"Enabled":true}}}} BasicAutoAccelerationPolicy HRD_POLICY_ID True
If the policy exists but the AlternateIdLogin attribute that isn't present or enabled, or if other attributes exist on the policy you wish to preserve, update the existing policy using the Update-MgPolicyHomeRealmDiscoveryPolicy cmdlet.
Important
When you update the policy, make sure you include any old settings and the new AlternateIdLogin attribute.
The following example adds the AlternateIdLogin attribute and preserves the AllowCloudPasswordValidation attribute that was previously set:
$AzureADPolicyDefinition = @(
@{
"HomeRealmDiscoveryPolicy" = @{
"AllowCloudPasswordValidation" = $true
"AlternateIdLogin" = @{
"Enabled" = $true
}
}
} | ConvertTo-JSON -Compress
)
$AzureADPolicyParameters = @{
HomeRealmDiscoveryPolicyId = "HRD_POLICY_ID"
Definition = $AzureADPolicyDefinition
DisplayName = "BasicAutoAccelerationPolicy"
AdditionalProperties = @{ "IsOrganizationDefault" = $true }
}
Update-MgPolicyHomeRealmDiscoveryPolicy @AzureADPolicyParameters
Confirm that the updated policy shows your changes and that the AlternateIdLogin attribute is now enabled:
Get-MgPolicyHomeRealmDiscoveryPolicy
Note
With the policy applied, it can take up to an hour to propagate and for users to be able to sign-in using email as an alternate login ID.
To remove an HRD policy, use the Remove-MgPolicyHomeRealmDiscoveryPolicy cmdlet:
Remove-MgPolicyHomeRealmDiscoveryPolicy -HomeRealmDiscoveryPolicyId "HRD_POLICY_ID"
Note
This configuration option uses staged rollout policy. For more information, see featureRolloutPolicy resource type.
Staged rollout policy allows tenant administrators to enable features for specific Microsoft Entra groups. It is recommended that tenant administrators use staged rollout to test user sign-in with an email address. When administrators are ready to deploy this feature to their entire tenant, they should use HRD policy.
A Global Administrator is needed to manage this feature.
Open a PowerShell session as an administrator, then install the Microsoft.Graph.Beta module using the Install-Module cmdlet:
Install-Module Microsoft.Graph.Beta
If prompted, select Y to install NuGet or to install from an untrusted repository.
Sign in to your Microsoft Entra tenant using the Connect-MgGraph cmdlet:
Connect-MgGraph -Scopes "Directory.ReadWrite.All"
The command returns information about your account, environment, and tenant ID.
List all existing staged rollout policies using the following cmdlet:
Get-MgBetaPolicyFeatureRolloutPolicy
If there are no existing staged rollout policies for this feature, create a new staged rollout policy and take note of the policy ID:
$MgPolicyFeatureRolloutPolicy = @{
Feature = "EmailAsAlternateId"
DisplayName = "EmailAsAlternateId Rollout Policy"
IsEnabled = $true
}
New-MgBetaPolicyFeatureRolloutPolicy @MgPolicyFeatureRolloutPolicy
Find the directoryObject ID for the group to be added to the staged rollout policy. Note the value returned for the Id parameter, because it will be used in the next step.
Get-MgBetaGroup -Filter "DisplayName eq 'Name of group to be added to the staged rollout policy'"
Add the group to the staged rollout policy as shown in the following example. Replace the value in the -FeatureRolloutPolicyId parameter with the value returned for the policy ID in step 4 and replace the value in the -OdataId parameter with the Id noted in step 5. It may take up to 1 hour before users in the group can sign in to Microsoft Entra ID with email as an alternate login ID.
New-MgBetaDirectoryFeatureRolloutPolicyApplyToByRef `
-FeatureRolloutPolicyId "ROLLOUT_POLICY_ID" `
-OdataId "https://graph.microsoft.com/v1.0/directoryObjects/{GROUP_OBJECT_ID}"
For new members added to the group, it may take up to 24 hours before they can sign in to Microsoft Entra ID with email as an alternate login ID.
To remove a group from a staged rollout policy, run the following command:
Remove-MgBetaPolicyFeatureRolloutPolicyApplyToByRef -FeatureRolloutPolicyId "ROLLOUT_POLICY_ID" -DirectoryObjectId "GROUP_OBJECT_ID"
To remove a staged rollout policy, first disable the policy then remove it from the system:
Update-MgBetaPolicyFeatureRolloutPolicy -FeatureRolloutPolicyId "ROLLOUT_POLICY_ID" -IsEnabled:$false
Remove-MgBetaPolicyFeatureRolloutPolicy -FeatureRolloutPolicyId "ROLLOUT_POLICY_ID"
To test that users can sign in with email, go to https://myprofile.microsoft.com and sign in with a non-UPN email, such as balas@fabrikam.com. The sign-in experience should look and feel the same as signing-in with the UPN.
If users have trouble signing in with their email address, review the following troubleshooting steps:
Make sure it's been at least 1 hour since email as an alternate login ID was enabled. If the user was recently added to a group for staged rollout policy, make sure it's been at least 24 hours since they were added to the group.
If using HRD policy, confirm that the Microsoft Entra ID HomeRealmDiscoveryPolicy has the AlternateIdLogin definition property set to "Enabled": true and the IsOrganizationDefault property set to True:
Get-MgBetaPolicyHomeRealmDiscoveryPolicy | Format-List *
If using staged rollout policy, confirm that the Microsoft Entra ID FeatureRolloutPolicy has the IsEnabled property set to True:
Get-MgBetaPolicyFeatureRolloutPolicy
Make sure the user account has their email address set in the ProxyAddresses attribute in Microsoft Entra ID.
You can review the sign-in logs in Microsoft Entra ID for more information. Sign-ins with email as an alternate login ID will emit proxyAddress in the Sign-in identifier type field and the inputted username in the Sign-in identifier field.
Within a tenant, a cloud-only user's UPN may take on the same value as another user's proxy address synced from the on-premises directory. In this scenario, with the feature enabled, the cloud-only user will not be able to sign in with their UPN. Here are the steps for detecting instances of this issue.
Open a PowerShell session as an administrator, then install the AzureADPreview module using the Install-Module cmdlet:
Install-Module Microsoft.Graph.Beta
If prompted, select Y to install NuGet or to install from an untrusted repository.
A Global Administrator is needed to manage this feature.
Connect-MgGraph -Scopes "User.Read.All"
Get affected users.
# Get all users
$allUsers = Get-MgUser -All
# Get list of proxy addresses from all synced users
$syncedProxyAddresses = $allUsers |
Where-Object {$_.ImmutableId} |
Select-Object -ExpandProperty ProxyAddresses |
ForEach-Object {$_ -Replace "smtp:", ""}
# Get list of user principal names from all cloud-only users
$cloudOnlyUserPrincipalNames = $allUsers |
Where-Object {!$_.ImmutableId} |
Select-Object -ExpandProperty UserPrincipalName
# Get intersection of two lists
$duplicateValues = $syncedProxyAddresses |
Where-Object {$cloudOnlyUserPrincipalNames -Contains $_}
To output affected users:
# Output affected synced users
$allUsers |
Where-Object {$_.ImmutableId -And ($_.ProxyAddresses | Where-Object {($duplicateValues | ForEach-Object {"smtp:$_"}) -Contains $_}).Length -GT 0} |
Select-Object ObjectId, DisplayName, UserPrincipalName, ProxyAddresses, ImmutableId, UserType
# Output affected cloud-only users
$allUsers |
Where-Object {!$_.ImmutableId -And $duplicateValues -Contains $_.UserPrincipalName} |
Select-Object ObjectId, DisplayName, UserPrincipalName, ProxyAddresses, ImmutableId, UserType
To output affected users to CSV:
# Output affected users to CSV
$allUsers |
Where-Object {
($_.ImmutableId -And ($_.ProxyAddresses | Where-Object {($duplicateValues | ForEach-Object {"smtp:$_"}) -Contains $_}).Length -GT 0) -Or
(!$_.ImmutableId -And $duplicateValues -Contains $_.UserPrincipalName)
} |
Select-Object ObjectId, DisplayName, UserPrincipalName, @{n="ProxyAddresses"; e={$_.ProxyAddresses -Join ','}}, @{n="IsSyncedUser"; e={$_.ImmutableId.Length -GT 0}}, UserType |
Export-Csv -Path .\AffectedUsers.csv -NoTypeInformation
To learn more about hybrid identity, such as Microsoft Entra application proxy or Microsoft Entra Domain Services, see Microsoft Entra hybrid identity for access and management of on-prem workloads.
For more information on hybrid identity operations, see how password hash sync or pass-through authentication synchronization work.
Training
Module
Discover how Microsoft Entra External ID can provide secure, seamless sign-in experiences for your consumers and business customers. Explore tenant creation, app registration, flow customization, and account security.
Certification
Microsoft Certified: Identity and Access Administrator Associate - Certifications
Demonstrate the features of Microsoft Entra ID to modernize identity solutions, implement hybrid solutions, and implement identity governance.
Documentation
Configuring Alternate Login ID
Learn more about: Configuring Alternate Login ID
Microsoft Entra Connect: User sign-in - Microsoft Entra ID
Microsoft Entra Connect user sign-in for custom settings.
How to migrate to the Authentication methods policy - Microsoft Entra ID
Learn about how to centrally manage multifactor authentication and self-service password reset (SSPR) settings in the Authentication methods policy.