DirSync: How To Switch From Single Sign-On To Password Sync
Important Updates
(May 1, 2018)
To change from Single Sign-On (AD FS) to Password Hash Synchronization please use guidance provided here: http://aka.ms/aadauthmigrate
(May 5, 2014)
Azure Active Directory now supports Password Synchronization as both an alternative to Single Sign-On, as well as a temporary backup for your Single Sign-On experience.
Whereas you could previously only enable a user for Single Sign-On OR you could sync their password, we have now completed updates to the service so that you can be synchronizing passwords for your Federated Users, and if your on-premises Single Sign-On infrastructure becomes unavailable, you can switch to let users sign in with their synchronized passwords while you're resolving those infrastructure problems!
Best of all, there is no need to update your DirSync if you're already running Password Sync!
Note
Microsoft always strongly recommends you deploy your Single Sign-On infrastructure in a highly-available manner.
This wiki does not change that recommendation.
Guidance for planning your ADFS infrastructure may be found here.
If you are using a 3rd party STS, please refer to that product's respective documentation for guidance of appropriate scaled and redundant deployment topologies.
This article has been updated and will address two scenarios:
- You've decided that you want to deploy Password Sync as a backup for your Single Sign-On infrastructure
- You've decided that Password Sync is sufficient to meet your business scenario requirements and want to switch to use Password Sync exclusively.
Please see Implement Password Synchronization for how to deploy the Password Sync feature of the Azure Active Directory Sync tool.
This document only addresses the scenario of using Password Sync as a backup for SSO or migrating users from Federated Authentication to Managed Authentication with Password Sync.
Note
For feedback, click here
Timing Considerations
Changing a user's authentication details can be a disruptive activity. As such, you should plan carefully and schedule the migration at a time that is least disruptive to the end-user(s) that are being affected. Additionally it can take up to 2 hours for the domain conversation from federated to standard authentication to be updated in the various systems.
Note
Password Synchronization is a one-way push of password hashes from your on-premises Active Directory to Azure Active Directory.
You must ensure that your user’s password is sync’d before they attempt to login.
Both Approaches provide guidance on how to do this.
Background
At General Availability, the Password Synchronization feature did not support the synchronization of passwords for users in a Federated namespace.
We have recently updated the service code to allow this.
This enables the added possibility of running Password Sync while using Single Sign-On, and temporarily switching over to use synchronized passwords for login if you experience availability issues with your SSO infrastructure!
Mixing Password Sync and Federated Authentication in the same tenant
Customers can have a mix of managed and federated namespaces within the same tenant. For example, a customer with 3 domains (domain1.com, domain2.com, domain3.com) may elect to configure domain1.com and domain3.com for Password Sync, but continue to have domain2.com configured for federated authentication. It is not supported to configure users within the same namespace for both federated authentication and password sync. Similarly, a customer may enable
Deploying Password Sync as a backup for Single Sign-On
With this latest update, you may elect to deploy Password Sync to provide a backup solution for your Single Sign-On infrastructure. To accomplish this task, simply deploy the Directory Sync tool and enable the Password Sync option when prompted in the Configuration Wizard (if you haven't already). More information on the Implementing Password Sync can be found here.
If you are already running Password Sync, you don't need to upgrade your DirSync tool to light up this feature! Just make sure you run a full password sync now so that all of your users' passwords are synchronized to the cloud. You can trigger a full Password Sync to re-synchronize all DirSync'ing user passwords via the Set-FullPasswordSync cmdlet. Documentation on how to use this password may be found here.
Temporarily Switching from Single Sign-On to Synchronizated Passwords for Sign-In
If your Single Sign-On infrastructure becomes unavailable, you can now "switch" to using the synchronized password hashes for user sign-in while you resolve your infrastructure incident on a per-domain basis. Please refer to the "Entire Namespace Conversion" section below on how to do this. Be sure to set -SkipUserConversion $true when calling the Convert-MsolDomainToStandard commandlet.
It is recommended that you do not change UserPrincipalNames or ImmutableIds after converting your domain to managed state (via the Convert-MsolDomainToStandard commandlet) for users that have been switched to use sync'd passwords.
In the case where such changes have been made, administrators will notice that these changes do not show up in the cloud - this is by design.
When you convert the domain back to a federated state, the changes will be processed per usual.
Note
Switching from Single Sign-On to use Synchronized Passwords for Sign-In is not instantaneous.
Please see the Timing Considerations section below for guidance on when you should consider switching or waiting out the Single Sign-On outage window.
Switch to use Password Sync exclusively
If you have decided that you no longer wish to use Single Sign-On and that Password Synchronization will meet your business needs, you can switch to use Password Synchronization. There are two approaches to accomplishing this task:
- Incremental migration – consider this approach if you wish to test out password sync for some users in your company before switching a larger set of users.
- Entire namespace conversion – consider this approach if you are ready to switch large sets of users from federated authentication to managed authentication with password sync.
Note
In both cases, you need to ensure that the user’s password is sync’d before the user logs in.
You can accomplish this by running a full password sync prior to domain conversion, after domain conversion, or having the user will change their password on-premises to get their passwords consistent.
See Stage 2 of either Approach outlined below for guidance on this.
Approach 1 - Incremental Migration
If you want to incrementally transition your users from Federated Authentication to Managed Authentication, you can do so by switching your users from a Federated Namespace to a Managed Namespace, then synchronizing the passwords for the converted users.
Note
Following this approach will change the namespace of the migrated user’s UserPrincipalName (the domain following the ‘@’ sign).
This will potentially impact your users’ login experience.
Be sure to notify your users that their login name has changed.
The procedure, at a high level, is as follows:
Stage 1 - Update the users to migrate
Update the user’s UserPrincipalName from a Federated to a Managed Namespace for the users you wish to migrate from federated to managed authentication.
Do this in your on-premises Active Directory, then trigger a Directory Sync cycle to sync those changes to the cloud.
Note
To trigger a Directory Sync manually, perform the following steps: 1. Open PowerShell, and then type **Import-Module DirSync** 2. Type **Start-OnlineCoexistenceSync**, and then press **Enter**
Verify the user’s UserPrincipalName has changed in the cloud.
This can be done using the Get-MsolUser commandlet.
The Azure Active Directory Powershell Module and documentation on the commandlet set can be found here.
Stage 2 - Synchronize user passwords
After you have confirmed that your users’ UserPrincipalNames have been updated in the on-premises AD, have those users update their password in your on-premises Active Directory. This will trigger the password to synchronize to the cloud.
Once their password has been synchronized to the cloud, the user will be able to log into their cloud services using the same password as their on-premises password.
Approach 2 - Entire namespace conversion
Once a customer is ready to transition an entire namespace from Federated to Managed Authentication, they may follow this procedure to migrate all of their users from Federated Authentication to Managed Authentication. This is the same procedure that should be used if converting a to Managed state while troubleshooting your on-premises Single Sign-On infrastructure.
Note
Users will not be able to log into the cloud with their on-premises password until Password Sync has successfully synchronized their passwords.
This means that users will not be able to use the service during the period of time between Stage 1 completion and Stage 2 completion.
It is important to schedule the conversion over a weekend (if this is a planned activity) or another time during which the user will not be disrupted while their credentials are being converted and password synchronized.
Stage 1 - Convert the namespace
Convert the desired namespace from Federated to Managed with the Convert-MsolDomainToStandard cmdlet.
Documentation on this commandlet can be found here: http://technet.microsoft.com/en-us/library/dn194122.aspx
Detailed steps are as follows:
Click Windows Azure Active Directory, right-click Windows Azure Active Directory Module for Windows PowerShell, and then click Run as administrator.
Run the following commands in the order in which they are presented. Press Enter after you type each command.
$cred = Get-Credential
When you are prompted, enter Office 365 administrator credentials that are not SSO-enabled.
Connect-MsolService –credential $cred
Set-MsolADFSContext –Computer <AD FS 2.0 server name>
Note
1. In this command, the placeholder \<AD FS 2.0 server name\> represents the name of the primary AD FS 2.0 server. 2. If the AD FS server is on a remote server you must set the AD FS server context, if the AD FS server is local you can skip this step.
Convert-MSOLDomainToStandard –DomainName <federated domain name> -SkipUserConversion $false -PasswordFile c:\userpasswords.txt
Note
1. Replace \<federated domain name\> represents the name of the domain you are converting. 2. This command removes the Relying Party Trust information from the Office 365 authentication system federation service and the on-premises AD FS 2.0 federation service. The **-PasswordFile** parameter indicates the path of the text file that contains the newly created temporary password of each formerly federated user’s account and must not exist before calling the cmdlet.
> [!NOTE]
If you are **temporarily switching** to use synchronized passwords while you are repairing your SSO infrastructure, set **–SkipUserConversion** to be **$true**. If you are **permanently decommissioning** your SSO Infrastructure, set **-SkipUserConversion** to **$false** to ensure users are converted correctly Additionally if the AD FS server is not available because of a failure you can convert the domain to Standard using the Set-MsolDomainAuthentication cmdlet to set the authentication to managed.
You can confirm if all users are converted by running the cmdlet Convert-MSOLDomainToStandard a second time. When run the second time, you must specify a different password file. For users that have already be converted they will not be issued a new password. Similarly if you have problems with converting some users you can call the cmdlet Convert-MsolFederatedUser to convert a single user.
If required/desired you can manually convert all users in a domain by following the sample script below.
Stage 2 - Synchronize user passwords
At this point, if you have not previously run a full Password Sync, (or you first deployed Password Sync before May 1, 2014), you should trigger a full Password Sync to re-synchronize all DirSync'ing user passwords via the Set-FullPasswordSync cmdlet. Documentation on how to use this password may be found here.
Verifying synchronized passwords
The simplest way to ensure that user passwords have successfully synchronized after being migrated to a Managed Namespace is to have the users try to log into the service.
If users are not able to sign into the cloud service, see Password synchronization troubleshooting guide for Office 365 for details on troubleshooting this issue.
Sample script to manually convert all users in a domain
The script below will enable you to convert all users in a domain to standard users.
Note that you must first convert the domain to standard before calling this procedure.
It is also recommend to start a transcript of the session to record the passwords for the users if needed.
| 001
002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 |
Get-MsolUser?-All?-DomainName?[Domain?Name?to?Convert]?|?%?{?
try?{ $Upn?=?$_.UserPrincipalName $pw?=?Convert-MsolFederatedUser?-UserPrincipalName?$Upn??ErrorAction??Stop?? $Upn?+?"`r`nt"?+?$pw $pw?=?"" } Catch?{ if?($_.FullyQualifiedErrorId?-like?'Microsoft.Online.Administration.Automation.UserAuthenticationUnchangedException*'){ $Upn?+?"`r`nt?User?already?converted" }?Else? { $Upn?+?"`r`nt?Exception?"?+?$_.FullyQualifiedErrorId? } $_.Clear } } |
See Also
- Azure Active Directory Forum
- Implement Password Synchronization
- Dirsync/WAAD Password Sync Frequently Asked Questions
- Configure filtering for directory synchronization