Deploying MS Entra SSPR in a Hybrid Environment with PowerShell

Posted on

Figure : Password reset flow using Microsoft Entra SSPR and Password Writeback through Microsoft Entra Connect in a Hybrid Active Directory environment.

After upgrading to a Microsoft 365 license that includes Microsoft Entra ID P1, organizations often begin by implementing Conditional Access policies. Another key feature, particularly in hybrid environments, is Self-Service Password Reset (SSPR), which allows users to reset their passwords independently.

Architecture Overview

By default, Microsoft Entra ID Free supports Password Hash Synchronization (PHS) from on-premises Active Directory (AD) to Microsoft Entra ID. However, password changes made directly in Entra ID are not written back to the on-premises AD environment, resulting in a one-way password synchronization model.

Organizations with Microsoft Entra ID P1 (or higher) can enable Password Writeback through Microsoft Entra Connect, allowing password changes and resets performed in Entra ID to be synchronized back to on-premises Active Directory. This capability is particularly valuable in hybrid environments, enabling users to securely reset or change their passwords from anywhere, without requiring a connection to the corporate network.

In this guide, you’ll learn how to gradually deploy Self-Service Password Reset (SSPR) in a hybrid identity environment and leverage PowerShell to simplify and automate the rollout process.

Prerequisites

Before you begin, ensure the following requirements are met:

✅ Microsoft Entra ID Premium P1 (or higher) license to support Password Writeback and SSPR

✅ Microsoft Entra Connect installed and configured to synchronize identities between on-premises Active Directory and Microsoft Entra ID

✅ Password Writeback feature enabled in Microsoft Entra Connect

✅ Hybrid Identity Administrator role (minimum required permission) or higher administrative privileges

✅ Users synchronized from on-premises Active Directory to Microsoft Entra ID

✅ At least one supported authentication method configured for SSPR (such as Microsoft Authenticator, mobile phone, or email)

Note: This configuration enables a seamless hybrid password management experience, allowing users to reset their passwords in Microsoft Entra ID while ensuring that password changes are automatically synchronized back to on-premises Active Directory.

Step 1: Create an Active Directory Security Group and Enable Password Writeback in Microsoft Entra Connect

To support a phased rollout of Self-Service Password Reset (SSPR), begin by creating an Active Directory security group that will contain the users who are authorized to use SSPR. Then, enable Password Writeback in Microsoft Entra Connect to allow password changes made in Microsoft Entra ID to synchronize back to on-premises Active Directory.

1. Create an Active Directory Security Group

Create a new security group in Active Directory to manage SSPR-enabled users. For example:

Group Name: SSPR-Enabled-Users

Tip: Ensure that the security group is located in an Organizational Unit (OU) that is included in Microsoft Entra Connect synchronization. Otherwise, the group will not be synchronized to Microsoft Entra ID.

2. Enable Password Writeback in Microsoft Entra Connect

  1. Open the Microsoft Entra Connect wizard on the Entra Connect server.
  2. Select Configure.
  3. Choose Customize synchronization options, and then click Next.
  4. Sign in using an account with the Hybrid Identity Administrator or Global Administrator role, and click Next.
  5. Continue through the wizard until you reach the Optional Features page.
  6. Select the Password Writeback option and click Next.
  7. Review the configuration settings and click Configure.
  8. Once the configuration completes successfully, click Exit to close the wizard.

Tip: Verify Microsoft Entra Connect Synchronization

After configuring synchronization, verify that it is working correctly by creating a test user in Active Directory and initiating a Delta Synchronization:

Start-ADSyncSyncCycle -PolicyType Delta

You can then confirm that the newly created user has been successfully synchronized to Microsoft Entra ID.

If the ADSyncTools PowerShell module is not already installed, install it using the following commands:

 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

 Install-Module -Name ADSyncTools

    The ADSyncTools module provides additional synchronization troubleshooting and management capabilities for Microsoft Entra Connect environments.

    Step 2: Enable Self-Service Password Reset (SSPR) in Microsoft Entra ID

    Before enabling Self-Service Password Reset (SSPR), it’s important to understand its deployment scope. At the time of writing, SSPR can be enabled for all users or for a single Microsoft Entra group. While nested groups are supported, many hybrid organizations structure users using Active Directory Organizational Units (OUs) rather than groups. Because of this, creating multiple pilot groups solely for phased SSPR adoption can add unnecessary administrative overhead. A dedicated security group, such as SSPR-Enabled-Users, provides a simple and effective approach for controlled deployment and testing.

    Enable SSPR for a Pilot Group

    1. Sign in to the Microsoft Entra Admin Center at https://entra.microsoft.com using an account assigned the Hybrid Identity Administrator role (or a higher privileged role).
    2. Verify that Password Writeback is functioning correctly:
      • Navigate to Protection → Password Reset → On-premises Integration.
      • Confirm that Microsoft Entra ID detects password writeback as enabled and properly configured through Microsoft Entra Connect.
    3. Navigate to:
      • Protection → Password Reset
    4. Under Manage → Properties, configure the following setting:
      • Self-service password reset enabled = Selected
    5. In the Selected group field, choose the SSPR-Enabled-Users security group created in Step 1.
    6. Click Save to apply the configuration.

    Tip: Starting with a pilot group allows you to validate registration, password reset, and password writeback functionality before expanding SSPR to a broader user population. Once testing is complete, you can gradually add more users or enable SSPR for the entire organization.

    Note: Default SSPR settings are suitable for most deployments. However, you can customize Authentication Methods as needed and require two verification methods for password reset to enhance security. 🔐

    ⚠️ Important: On-premises Active Directory password policies, including Default Domain Policy and Fine-Grained Password Policies (FGPPs), are enforced during Microsoft Entra ID password resets. To ensure a seamless password writeback experience, Microsoft recommends setting the Minimum Password Age to 0 days. Otherwise, users who receive a temporary password from the help desk may be unable to immediately change it using SSPR, resulting in unnecessary delays and a poor user experience.

    Step 3: Automate the Gradual SSPR Rollout Using PowerShell

    Now for the fun part! 🎉 Let’s use PowerShell to automate the gradual rollout of Self-Service Password Reset (SSPR) based on Active Directory Organizational Units (OUs).

    ℹ️ Prerequisite:
    The device running the script must have the Active Directory PowerShell module installed. This module is included with the Remote Server Administration Tools (RSAT). To install it, run the following command from an elevated PowerShell session:

    Install-WindowsFeature RSAT-AD-PowerShell

    1. Export Licensed Users from Microsoft 365

    Before building the automation, export a list of users who are licensed with Microsoft Entra ID P1 or higher. Although SSPR can technically function for all users when at least one P1 license exists in the tenant, only appropriately licensed users should be included to maintain licensing compliance.

    To export the user list:

    • Navigate to the Microsoft 365 Admin Center.
    • Go to Users → Active Users.
    • Select Export Users and download the CSV file.

    💡 Tip:
    Review the exported CSV and remove any users who do not have a Microsoft Entra ID P1 (or higher) license before using it with the automation process.

    2. Create an OU Inventory CSV

    Next, generate a CSV file containing the Organizational Units (OUs) that will be onboarded to SSPR. PowerShell can be used to export the required OU information.

    After creating the CSV file, add a new column named SSPRGroup.

    This column serves as a tracking mechanism for the automation process:

    • When the script successfully adds licensed users from an OU to the SSPR-Enabled-Users security group, it writes Added in the corresponding SSPRGroup column.
    • During subsequent executions, the script skips previously processed OUs and continues with the next OU pending evaluation.
    • This approach enables a controlled, phased deployment of SSPR while providing a simple method for tracking rollout progress.

    ✅ Benefits of this approach:

    • Gradually roll out SSPR by department or business unit.
    • Ensure only licensed users are added to the SSPR group.
    • Track deployment progress through a single CSV file.
    • Prevent duplicate processing of previously onboarded OUs.
    • Simplify administration and troubleshooting during pilot and production deployments.

    Run these commands one by one

    $OUs = Get-ADOrganizationalUnit -Filter * -SearchBase 'OU=assumebreach users,DC=assumebreach,DC=local'

    $OUs | Select-Object Name, DistinguishedName | Export-Csv -Path 'C:\temp\ou-list.csv' -NoTypeInformation

    3. Create the PowerShell Automation Script

    Next, create a PowerShell script that reads both the licensed users CSV and the OU inventory CSV, then identifies licensed users within each OU and automatically adds them to the SSPR-Enabled-Users security group.

    The script uses the SSPRGroup column in the OU CSV to track processing status. Once all eligible users from an OU have been added to the security group, the script updates the corresponding SSPRGroup value to Added, ensuring that previously processed OUs are skipped during future executions. This enables a controlled, phased rollout of SSPR while maintaining clear deployment tracking and minimizing administrative effort. 🚀

    Import-Module ActiveDirectory

[array]$OUList = Import-Csv -Path '.\ou-list.csv'
[array]$LicensedUsers = Import-Csv -Path '.\m365-licensed-users.csv'

$OU = $OUList | Where-Object { $_.SSPRGroup -ne 'Added'} | Select-Object -First 1

if ($null -ne $OU) {
$users = Get-ADUser -Server "INSERT_SERVER_NAME" -Filter * -SearchBase $OU.DistinguishedName -SearchScope OneLevel

foreach ($user in $users) {
    $LicensedUser = $LicensedUsers | Where-Object {$_.UserPrincipalName -eq $user.UserPrincipalName}
    if ($LicensedUser) {
        Add-ADGroupMember -Server "INSERT_SERVER_NAME" -Identity "SSPR-Enabled-Users" -Members $user.SamAccountName
    }
}

$OU.SSPRGroup = 'Added'
$OUList | Export-Csv -Path '.\ou-list.csv' -NoTypeInformation
}

    $OU.SSPRGroup = ‘Added’
    $OUList | Export-Csv -Path ‘.\ou-list.csv’ -NoTypeInformation
    }

    Save and Configure the PowerShell Script

    1. Save the script as Add-SSPRUsers.ps1 in a secure location of your choice. Before executing the script, update the following values to match your environment:
    • Replace INSERT_SERVER_NAME with the hostname of your domain controller.
    • Update the paths for the licensed users CSV and OU inventory CSV files.
    • Verify that the account running the script has the required permissions to read Active Directory and modify group memberships.

    Step 4: Automate the Script with Task Scheduler

    To streamline the SSPR rollout process, configure the script to run automatically on a daily schedule.

    1. Open Task Scheduler and select Create Basic Task.
    2. Enter a task name such as Add SSPR Users, then click Next.
    3. Choose Daily as the trigger and click Next.
    4. Specify the desired start date and execution time, then click Next.
    5. Select Start a Program and click Next.
    6. In the Program/Script field, enter:

    powershell.exe

    7. In the Add arguments (optional) field, enter:

    -ExecutionPolicy Bypass -File "C:\Path\To\Your\Script\Add-SSPRUsers.ps1"

    8. Review the configuration and click Finish to create the scheduled task.

    💡 Tip: Run the task using a service account with the appropriate Active Directory permissions and enable task history to simplify monitoring and troubleshooting. This ensures new licensed users are automatically added to the SSPR-Enabled-Users group as additional OUs are processed. 🚀

    Additional Recommended Task Scheduler Configuration

    After creating the scheduled task, consider applying the following settings to improve reliability, security, and automation.

    1. Right-click the task and select Properties.
    2. On the General tab:
      • Select Run whether user is logged on or not.
      • Enable Run with highest privileges to ensure the script has the necessary permissions.
    3. On the Triggers tab:
      • Select the existing trigger and click Edit.
      • Configure the schedule as required for your environment.
    4. Under Advanced Settings:
      • Enable Repeat task every and configure an appropriate interval if more frequent execution is required.
    5. On the Conditions tab:
      • Clear Start the task only if the computer is on AC power to prevent the task from being skipped on battery-powered devices.
    6. On the Settings tab:
      • Enable If the task fails, restart every and specify a suitable retry interval to improve resilience.
      • Optionally, enable Run task as soon as possible after a scheduled start is missed to ensure missed executions are processed.

    Key Takeaways ⭐

    Congratulations! 🎉 You have successfully deployed Microsoft Entra Self-Service Password Reset (SSPR) in a hybrid identity environment using a controlled, PowerShell-driven approach.

    By leveraging Active Directory Organizational Units (OUs) and automated group membership management, you can introduce SSPR gradually across the organization, ensuring a smooth and well-governed rollout. This method provides greater visibility into the deployment process, helps maintain licensing compliance, minimizes administrative overhead, and allows issues to be identified and resolved before expanding to a wider user population.

    Combining Microsoft Entra Password Writeback, group-based SSPR enablement, and scheduled PowerShell automation creates a scalable and repeatable solution that empowers users to securely reset or unlock their accounts while reducing help desk dependency and improving overall operational efficiency.

    With SSPR successfully implemented, your organization is one step closer to delivering a modern, secure, and self-service identity experience for both end users and IT administrators. 🚀🔐

    Thanks !

    Leave a Reply

    Your email address will not be published. Required fields are marked *