Password writeback: how to configure Azure AD to manage on-premises passwords
Updated: February 10, 2015
Use the links below to jump to the information about password writeback that interests you most.
- Password writeback overview
- How password writeback works
- How to enable/disable password writeback
- Troubleshooting password writeback
Password writeback is an Azure Active Directory Sync component that can be enabled and used by the current subscribers of Azure Active Directory Premium. For more information, see Azure Active Directory Editions. It allows you to configure your cloud tenant to write passwords back to you on-premises Active Directory. It obviates you from having to set up and manage a complicated on-premises self-service password reset solution, and it provides a convenient cloud-based way for your users to reset their on-premises passwords wherever they are. Read on for some of the key features of password writeback:
- Zero delay feedback. Password writeback is a synchronous operation. Your users will be notified immediately if their password did not meet policy or was not able to be reset or changed for any reason.
- Supports resetting passwords for users using AD FS or other federation technologies. With password writeback, as long as the federated user accounts are synchronized into your Azure AD tenant, they will be able to manage their on-premises AD passwords from the cloud.
- Supports resetting passwords for users using password hash sync. When the password reset service detects that a synchronized user account is enabled for password hash sync, we reset both this account’s on-premises and cloud password simultaneously.
- Supports changing passwords from the access panel and O365. When federated or password sync’d users come to change their expired or non-expired passwords, we’ll write those passwords back to your local AD environment.
- Supports writing back passwords when an admin reset them from the Azure Management Portal. Whenever an admin resets a user’s password in the Azure Management portal, if that user is federated or password sync’d, we’ll set the password the admin selects on your local AD, as well. This is currently not supported in the Office Admin Portal.
- Enforces your on-premises AD password policies. When a user resets his/her password, we make sure that it meets your on-premises AD policy before committing it to that directory. This includes history, complexity, age, password filters, and any other password restrictions you have defined in your local AD.
- Doesn’t require any inbound firewall rules. Password writeback uses an Azure Service Bus relay as an underlying communication channel, meaning that you do not have to open any inbound ports on your firewall for this feature to work, only 443 outbound.
- Is not supported for user accounts that exist within protected groups in your on-premises Active Directory. For more information about protected groups, see Appendix C: Protected Accounts and Groups in Active Directory.
Password writeback has three main components:
- Password Reset cloud service (this is also integrated into Azure AD’s password change pages)
- Tenant-specific Azure Service Bus relay
- On-prem password reset endpoint
When a federated or password hash sync’d user comes to reset or change his or her password in the cloud, the following occurs:
- We check to see what type of password the user has. If we see the password is managed on premises, then we ensure the writeback service is up and running. If it is, we let the user proceed, if it is not, we tell the user that their password cannot be reset here.
- Next, the user passes the appropriate authentication gates and reaches the reset password screen.
- The user selects a new password and confirms it.
- Upon clicking submit, we encrypt the plaintext password with a public key that was created during the writeback setup process.
- After encrypting the password, we include it in a payload that gets sent over an HTTPS channel to your tenant specific service bus relay (that we also set up for you during the writeback setup process). This relay is protected by a randomly generated password that only your on-premises installation knows.
- Once the message reaches service bus, the password reset endpoint automatically wakes up and sees that it has a reset request pending.
- The service then looks for the user in question by using the cloud anchor attribute. For this lookup to succeed, the user object must exist in the AD connector space, it must be linked to the corresponding MV object, and it must be linked to the corresponding AAD connector object. Finally, in order for sync to find this user account, the link from AD connector object to MV must have the sync rule “Microsoft.InfromADUserAccountEnabled.xxx” on the link. This is needed because when the call comes in from the cloud, the sync engine uses the cloudAnchor attribute to look up the AAD connector space object, then follows the link back to the MV object, and then follows the link back to the AD object. Because there could be multiple AD objects (multi-forest) for the same user, the sync engine relies on the “Microsoft.InfromADUserAccountEnabled.xxx” link to pick the correct one.
- Once the user account is found, we attempt to reset the password directly in the appropriate AD forest.
- If the password set operation is successful, we tell the user their password has been modified and that they can go on their merry way.
- If the password set operation fails, we return the error to the user and let them try again. The operation might fail because the service was down, because the password they selected did not meet organization policies, because we could not find the user in the local AD, or any number of reasons. We have a specific message for many of these cases and tell the user what they can do to resolve the issue.
The table below describes which scenarios are supported for which versions of our sync capabilities. In general, it is highly recommended that you install the latest version of AADSync if you want to use password writeback. You can find the latest version of AAD Sync at http://www.microsoft.com/en-us/download/details.aspx?id=44225.
Password writeback is a highly secure and robust service. In order to ensure your information is protected, we enable a 4-tiered security model that is described below.
- Tenant specific service-bus relay – When you set up the service, we set up a tenant-specific service bus relay that is protected by a randomly generated strong password that Microsoft never has access to.
- Locked down, cryptographically strong, password encryption key – After the service bus relay is created, we create a strong asymmetric key pair which we use to encrypt the password as it comes over the wire. The private key of this key pair lives only in your on-premises environment and Microsoft never has access to it. The public key gets placed into your tenant’s secret store in the cloud, which is a heavily locked down.
- Industry standard TLS – When a password reset or change operation occurs in the cloud, we take the plaintext password and encrypt it with your public key. We then plop that into an HTTPS message which is sent over an encrypted channel using Microsoft’s SSL certs to your service bus relay. After that message arrives into Service Bus, your on-prem agent wakes up, authenticates to Service Bus using the strong password that had been previously generated, picks up the encrypted message, decrypts it using the private key we generated, and then attempts to set the password through the AD DS SetPassword API. This step is what allows us to enforce your AD on-prem password policy (complexity, age, history, filters, etc) in the cloud.
- Message expiration policies – Finally, if for some reason the message sits in Service Bus because your on-prem service is down, it will be timed out and removed after several minutes in order to increase security even further.
This section walks you through configuring password reset to write passwords back to an on-premises Active Directory.
- Password writeback prerequisites
- Step 1: Install or upgrade Azure Sync Tool to version 1.0.0419.0911 or later
- Step 2: Enable password writeback on your Directory Sync computer & configure firewall rules
- Step 3: Ensure you have the proper permissions defined on your ADMA account for password writeback to occur
- Step 4: Reset your password as a user and verify it is written back to on-premises AD
Before you can enable and use the password writeback, you must make sure you complete the following prerequisites:
- You have an Azure AD tenant with Azure AD Premium enabled. For more information, see Azure Active Directory Editions.
- Password reset has been configured and enabled in your tenant. For more information, see Self-service password reset in Azure AD: how to enable, configure, and test self-service password reset.
- You have at least one administrator account and one test user account with an Azure AD Premium license that you can use to test this feature. For more information, see Azure Active Directory Editions
Important Make sure that the administrator account that you use to enable password writeback is a cloud administrator account (created in Azure AD), not a federated account (created in on-premises AD and synchronized into Azure AD.
- You have a single or multi-forest AD on-premises deployment running Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, or Windows Server 2012 R2 with the latest service packs installed.
Note If you are running an older version of Windows Server 2008 or 2008 R2, you can still use this feature, but will need to install KB 2386717 before being able to enforce your local AD password policy in the cloud.
- You have the Azure AD Sync tool installed and you have prepared your AD environment for synchronization to the cloud. For more information, see Directory Integration Tools.
- If you are using DirSync, you must make sure your organization’s firewall is configured to block outbound connections. You must unblock TCP port 828 or 818 in order to enable and use the password writeback. If you are using AADSync, this step is not necessary, as only 443 TCP outbound needs to be open.
Password writeback is available in releases of the Azure AD Sync Tool with version number 1.0.0419.0911 or higher. Password writeback with automatic account unlock is available in releases of the Azure AD Sync Tool with version number 1.0.0485.0222 or higher. If you are running an older version, please upgrade to at least this version before proceeding. Download the latest version of Azure AD Sync.
- Navigate to %ProgramFiles%Azure Active Directory Sync.
- Find the ConfigWizard.exe executable.
- Right-click the executable and select the Properties option from the context menu.
- Click on the Details tab.
- Find the File version field.
If this version number is greater than or equal to 1.0.0419.0911, you can skip to Step 2: Enable password writeback on your Directory Sync computer & configure firewall rules. If you have never installed AADSync before, then here are some resources you can use to learn about pre-requirements for setting up sync:
- If this is your first time installing the Azure AD Sync Tool, it is recommended that you follow a few best practices to prepare your environment for directory synchronization. Before you install the Azure AD Sync Tool, you must activate directory synchronization in either the Office 365 or the Azure management portals. For more information, see Azure Active Directory Sync.
Now that you have the Azure AD Sync tool downloaded, you are ready to enable password writeback. You can do this in one of two ways. You can either enable password writeback in the optional features screen of the Azure AD Sync setup wizard, or you can enable it via Windows PowerShell.
- On your Directory Sync computer, open the Azure AD Sync configuration wizard.
- Click through the steps until you reach the optional features configuration screen.
- Check the Password write-back option.
- Complete the wizard, the final page will summarize the changes and will include the password writeback configuration change.
- Once installation is complete, if you are blocking unknown outbound connections in your environment, you will also need to add the following rules to your firewall. Make sure you reboot your AADSync machine after making these changes:
- Allow outbound connects over port 443 TCP
- Allow outbound connections to https://ssprsbprodncu-sb.accesscontrol.windows.net/
Note You can disable password writeback at any time by either re-running this wizard and deselecting the feature, or by setting the Write Passwords Back to On-Premises Directory setting to No in the User Password Reset Policy section of your directory’s Configure tab in the Azure Management Portal.
- On your Directory Sync computer, open a new elevated Windows PowerShell window.
- If the module is not already loaded, type in the Import-Module ADSync command to load the AAD Sync cmdlets into your current session.
- Get the list of AAD Connectors in your system by running the Get-ADSyncConnector cmdlet and storing the results in $aadConnectorName
- To get the current status of writeback for the current connector by running the following cmdlet: Get-ADSyncAADPasswordResetConfiguration –Connector $aadConnectorName.
- Enable password writeback by running the cmdlet: Set-ADSyncAADPasswordResetConfiguration –Connector $aadConnectorName –Enable $true
- Once installation is complete, if you are blocking unknown outbound connections in your environment, you will also need to add the following rules to your firewall. Make sure you reboot your AAD Sync machine after making these changes:
- Allow outbound connections over port 443 TCP
- Allow outbound connections to https://ssprsbprodncu-sb.accesscontrol.windows.net/
Note If prompted for a credential, make sure that the administrator account that you specify for AzureADCredential is a cloud administrator account (created in Azure AD), not a federated account (created in on-premises AD and synchronized into Azure AD. Note You can disable password writeback through PowerShell by repeating the same instructions above but passing $false in step or by setting the Write Passwords Back to On-Premises Directory setting to No in the User Password Reset Policy section of your directory’s Configure tab in the Azure Management Portal.
Verify that the configuration was successful
Once the configuration succeeds, you will see the message Password reset write-back is enabled in the Windows PowerShell window. You can verify the service was installed correctly by opening Event Viewer, navigating to the application event log, and looking for event 31005 – OnboardingEventSuccess from the source PasswordResetService.
For troubleshooting information and FAQ information, see “Troubleshoot Password Writeback” and “Password Writeback On-premises Event Log Error Codes” sections in FAQ/Troubleshooting for Azure AD password management.
For every forest that contains users whose passwords will be reset, if X is the account that was specified for that forest in the configuration wizard (during initial configuration), then X must be given the Reset Password, Change Password, Write Permissions on “lockoutTime”, and Write Permissions on “pwdLastSet”, extended rights on the root object of each domain in that forest. The right should be marked as inherited by all user objects.
Setting these permissions will allow the MA service account for each forest to manage passwords on behalf of user accounts within that forest. If you neglect to assign these permissions, then, even though writeback will appear to be configured correctly, users will encounter errors when attempting to manage their on-premises passwords from the cloud. Here are the detailed steps on how you can do this using the Active Directory Users and Computers management snap-in:
|it could take up to an hour for these permissions to replicate to all objects in your directory.|
- Open Active Directory Users and Computers with an account that has the appropriate domain administration permissions.
- In the View Menu option, make sure Advanced Features is turned on.
- In the left panel, right click the object that represents the root of the domain.
- Click on the Security tab.
- Then click Advanced.
- On the Permissions tab, click Add.
- Select the account you want to give permissions to (this is the same account that was specified while setting up sync for that forest).
- In the drop down on the top, select Descendent User objects.
- In the Permission Entry dialog box that shows up, check the box for Reset Password, Change Password, Write Permissions on “lockoutTime”, and Write Permissions on “pwdLastSet”.
- Then click Apply/Ok through all the open dialog boxes.
Now that password writeback has been enabled, you can test that it works by resetting the password of a user whose account has been synchronized into your cloud tenant.
- Navigate to http://passwordreset.microsoftonline.com or go to any organizational ID login screen and click the Can’t access your account? link.
- You should now see a new page which asks for a user ID for which you want to reset a password. Enter your test user ID and proceed through the password reset flow.
- After you reset your password, you will see a screen that looks similar to this. It means you have successfully reset your password in your on-premises and/or cloud directories.
- To verify the operation was successful, go to your Directory Sync computer, open Event Viewer, navigate to the application event log, and look for event 31002 – PasswordResetSuccess from the source PasswordResetService for your test user.
For troubleshooting information and FAQ, see “Troubleshoot Password Writeback” and “Password Writeback On-premises Event Log Error Codes” sections in FAQ/Troubleshooting for Azure AD password management.