For feedback, click here

Problem Statement

Some customers cannot use their on-premises UserPrincipalNames to authenticate their users with Windows Azure Active Directory, or one of its associated services (i.e. Office 365, InTune, etc.).

This is commonly because their on-premises UserPrincipalNames are using a non-routable domain (i.e. single level domains or “.local” / ”.intranet” domains). Standard guidance for these customers is to change their on-premises UserPrincipalNames to use a different domain as recommended in Password policy in Azure AD.

However, those same customers may not be able to implement that guidance for a variety of reasons.

If this sounds like the situation you're in, then this wiki is for you!

In this wiki, we'll prescribe the process that will allow you to on-board to Azure Active Directory, and its associated services, using an Alternate Login ID.

Follow the guidance provided below which will walk you through the process of:

  • Modifying the DirSync attribute flow for UserPrincipalName for provisioning/sync
  • Leveraging the Alternate Login ID feature of AD FS for Single Sign-On authentication 
The Alternate Login ID feature may impact various other Azure AD and Office 365 scenarios including:
  • Office 365 ProPlus activation may require explicit sign-in 

Please contact your Account representative for more information on these incompatibilities.


↑ Back to top


What you’ll need


Alternate Login ID Attribute using a publically routable, verified domain

This solution assumes that you can specify a different attribute (we refer to this as the “Alternate Login ID”) in your on-premises AD that can be used as sign-in value for your users.

The attribute must be using a publically routable, verified domain.

An alternate attribute must:

  1. Be of a compatible data type to the UserPrincipalName attribute in Active Directory (schema details documented here: .
  2. Conform to the UserPrincipalName restrictions as documented here: 

Directory Sync

Customers will be able to deploy the prescribed solution below on the currently available version of either:

  • the Windows Azure Active Directory Sync tool or
  • the Azure AD Connector for FIM 2010 R2

No upgrade/new versions of software are required to achieve this configuration.  

Password Sync

You can still use Password Sync if you deploy this solution.

No changes are required to the Password Sync feature/configuration for this solution to work.  

Single Sign-On

If you want Single Sign-On via ADFS, you’ll need to perform the steps outlined in the sections below - called out as appropriate.

Customers using other 3rd party STS’ as supported by the Works with Office 365 Identity program should refer to their respective STS documentation for the analogous configuration steps. 

  1. Customers that wish to enable Single Sign-On using ADFS are required to deploy / upgrade ADFS to Windows Server 2012 R2 with KB2919355 in order to leverage the Solutions prescribed in the Update Single Sign-On section below.There are no known dependencies on the customer’s forest functional level.
  2. We strongly recommend that you make this configuration change to Directory Sync before you perform your initial synchronization run. There are several scenarios where making this configuration change after you have populated your tenancy can cause issues.


↑ Back to top


How To Update


Update Directory Sync

  1. Deploy the desired Directory Sync solution BUT do not perform an initial sync.
  2. Update the attribute flow rule for UserPrincipalName in your Directory Sync configuration (in the Active Directory Connector) to synchronize an alternate attribute from your on-premises Active Directory instead of their AD.User.UserPrincipalName to Azure Active Directory.
  3. Run your initial sync.

Step-by-step instructions to change the synchronization attribute flow can be found in the Updating Sync Engine Configuration section at the end of this wiki.

If you need to make this change after you have run your initial sync, you must handle the following potential scenarios:

  1. The old UserPrincipalName and the new Alternate Login ID values for a User are both using Federated Domains.

    In this case, Directory Sync will not automatically update the UserPrincipalName.

    You will need to do this manually with the Set-MsolUserPrincipalName commandlet in addition to changing the attribute mapping in Directory Sync.
  2. The User is licensed. In this case, Directory Sync will not automatically update the UserPrincipalName.

    You will need to do this manually with the Set-MsolUserPrincipalName commandlet in addition to changing the attribute mapping in Directory Sync.
  3. The new Alternate Login ID value is currently being used by another user.

    This will result in a Duplicate UserPrincipalName Sync Error.

    You will need to ensure that no other user in the directory is currently using the new Alternate Login ID value for this operation to succeed.  

Update Single Sign-On

If the customer requires Single Sign-On, they should also:

  1. Deploy (or upgrade to) and configure ADFS on Windows Server 2012 R2 (as documented here: ).
  2. Install KB2919355 (through Windows Update Services or other applicable update service)
  3. Run the following PowerShell cmdlet on AD FS server to update AD FS configuration:

    Set-AdfsClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID <attribute you have chosen> -LookupForests <forest list>


    • AlternateLoginID is the LDAP name of the attribute to use instead of UserPrincipalName for login. This attribute will also be issued as the UserPrincipalName claim in the SAML token.
    • LookupForests is a single string containing the list of forest DNS where the user may belong to, with domains separated by commas
    Both AlternateLoginID and LookupForests must be set when calling the Set-AdfsClaimsProviderTrust cmdlet.

    For example, the following command configures ADFS such that users sign-in with their “Mail” attribute rather than their UserPrincipalName, and ADFS will look up users in the and forests:

    Set-AdfsClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID mail -LookupForests,
  4. Additionally, administrators will need to update the ADFS Claims Issuance Rules.

    They will need to update Rule #1 with the appropriate attribute name as follows.

    The example attribute used below is “mail”.

    You must specify the attribute you’ve chosen instead of UserPrincipalName (matches to the -AlternateLoginID parameter value):
    Old Claim Rule
    c:[Type = "http: // com/ws/2008/06/identity/claims/windowsaccount Name"] => issue (store = "Active Directory", types = (" ",
    "http: // com/LiveID/Federation/2008/05/ImmutablelD"),query="samAccountName={0};userPrincipalName, objectGuiD; (1)", param = regexreplace(c.Value, "(?<domain>[’\\)+)\\(?<user>.+)", "${user)"),param = c.Value);
    New Claim Rule
    c:[Type = "http: // com/ws/2008/06/identity/claims/windowsaccount Name"] => issue (store = "Active Directory", types = (" ", "http: // com/LiveID/Federation/2008/05/ImmutablelD"),query="samAccountName={0};mail, objectGuiD; (1)", param = regexreplace(c.Value, "(?<domain>[’\\)+)\\(?<user>.+)", "${user)"),param = c.Value);


The text highlighted in yellow in the top should be updated with the highlighted text in the bottom row.

It is critical that the semicolon (“;”) precede the word “mail” in the updated claim rule, where "mail" is the attribute you have chosen to use instead of the UserPrincipalName.


  1. When configuring alternate login ID, admin needs to make sure that AD FS can uniquely identify the user account with this ID across the lookup forests that admin configures, otherwise the login will fail.
  2. Admins must make sure that all AD authenticated users can access the CanonicalName attribute of the user object.

    That is, the ACLs of CanonicalName AD attribute should include “Authenticated Users””.


Update the Sync Engine Configuration

If you have just installed the Directory Sync tool, and have not yet run the first sync cycle, then you will need to log off the machine and log back on before you can perform the steps below.  This is required to refresh your group memberships to give access to miisclient.exe.

To update the attribute that is synchronized to the cloud, you must do the following:

  1. Log into the machine running the Directory Sync tool (or the FIM Sync Engine).
  2. Navigate to C:\Program Files\Windows Azure Active Directory Sync\SYNCBUS\Synchronization Service\UIShell and double-click miisclient.exe.
  3. Navigate to the Management Agents tab and right-select the “Active Directory Connector > Properties”.
  4. Select the Configure Attribute Flow option in the left navigation pane.
  5. Find the Object Type: user option and expand the attribute flows.
  6. Find the “UserPrincipalName” Metaverse Source Attribute and update the Data Source Attribute to be the correct attribute you wish to flow instead (in this example, “mail”).
  7. Set the Mapping Type value to be "Direct".
  8. Click the Edit button.
  9. Click OK to save the configuration.

↑ Back to top