Forefront Identity Manager (FIM) 2010 Update 1, when coupled with a Windows Server 2008 R2 Service Pack 1 (or Windows Server 2008 Service pack 2 or Windows Server 2008 R2 RTM plus hotfix) Primary Domain Controller Emulator (PDCe) Operations Master (OM) role holder enables the Self-service Password Reset (SSPR) feature of FIM to fully honour all Active Directory Domain Services (AD DS) password policy settings.

Prior to the AD DS DCR described in KB2386717: ‘The “Enforce password history” and “Minimum password age” Group Policy settings do not work when you reset the password for a Windows Server 2008 R2-based or a Windows Server 2008-based computer‘ password reset operations bypassed the underlying logic that maintains the minimum password age and password history. A password reset has traditionally been thought of as an administrative action therefore an administrative reset should not need worry about history or, more importantly, age. I say traditionally, of course such an operation is still, rightly, considered an administrative operation. However with the advent of end-user focussed self-service password reset applications something has had to change so that a reset operation can optionally reset the password (in a secure manner) with a new password submitted by the end user (a user-defined password).

The AD DS product group (PG) has implemented this change. And the FIM PG has consumed the change.

KB2443871: “FIM 2010 Self Service Password Reset now supports Enforcement of all domain password policies” fully describes how to configure the FIM Synchronization Service to utilise the new AD DS behaviour. In summary, you make the following configuration:

1. Implement the hotfix for Windows Server 2008 or Windows Server 2008 R2 RTM (it’s included in Windows Server 2008 R2 Service Pack 1) on the PDCe.
2. Configure the FIM Synchronization Service registry value ADMAEnforcePasswordPolicy (located under the key “HKLM\ SYSTEM\ CurrentControlSet\ Services\ FIMSynchronizationService\ Parameters\ PerMAInstance\<ma name>”)

The reason I’m writing this blog post is to hopefully succinctly describe why the documentation explicitly refers to the PDCe. There have been a number of questions around how to implement this feature on the public FIM forum as well as internally on the FIM discussion alias. The crux of the matter is this: the password reset activity (Password Reset Action Workflow Activity) that runs in the context of an action workflow (Password Reset Action Workflow, 79315438-c20b-465e-bcd6-677685f2783a) submits the password reset operation to the FIM Synchronization Service via the MIIS_CSObject::SetPassword method. This method has been extended. The original definition was:

String SetPassword(String newPassword, Boolean forceChangeAtLogon, Boolean unlockAccount) 

The new definition, or more likely override, is as follows:

String SetPassword(String newPassword, Boolean forceChangeAtLogon, Boolean unlockAccount, Boolean validatePasswordPolicy) 

The last Boolean parameter (validatePasswordPolicy) makes use of the new LDAP extended control: LDAP_SERVER_POLICY_HINTS (1.2.840.113556.1.4.2066). The way the underlying code has been implemented is to always target the PDCe (DsGetDCName() Flag DS_PDC_REQUIRED). This is the reason why the documentation specifically mentions the PDCe. The LDAP extended control can be implemented on any DC (indeed it should be implemented on all DCs if you’re using it outside of FIM SSPR as the mixture of supported LDAP controls should be minimised to that defined by the OS level of the DCs really). However for the purpose of FIM SSPR only the PDCe is targeted. This is slightly confusing but ultimately conveniently flexible. As this means it is potentially considerably easier to implement SSPR with the fully honoured password policy in environments that don’t yet implement Windows Server 2008 or Windows Server 2008 R2 domain controllers. Don’t get me wrong –it’s still not a simplistic change (within the confines of a given organisations politics and processes). It does require the AD DS schema extension and domain preparation required as part of any DC upgrade programme. The difference is that many organisations are currently planning on, or in the process of, moving to a Windows Server 2008 or Windows Server 2008 R2 domain and the introduction of one is often allowed and can sometimes expedite the project itself.

The other thing of note around the current implementation of the set password operation with the LDAP_SERVER_POLICY_HINTS control is that the only connection that the AD MA will work over is LDAPS (LDAP over TLS/SSL). Now, again, this is an implementation choice (by the FIM PG). Yes, it is possible (and in some cases more trivial) to utilise what’s commonly referred to as LDAP bind channel encryption (basically Kerberos signing and sealing of the LDAP connection). However, presently, the FIM PG hasn’t implemented this code. This adds a small complexity to the deployment for environments that have not yet deployed LDAPS. Now you need to configure LDAPS on the PDCe. When I say configure I mean enrol the necessary certificate. There’s no real DC-side configuration. There are three choices, of which only two are really valid in production:

1. Purchase a certificate from a trusted root authority, e.g. Verisign or Thwarte;
2. Implement a Public Key Infrastructure (PKI), e.g. Active Directory Certificate Services (AD CS);
3. Implement a self-signed certificate. Realistically this option is only prudent for testing and sandpit environments.

Interestingly though the AD MA code doesn’t perform certificate revocation list (CRL) checking. Is this a good thing? Bad thing? Or doesn’t it matter? J

Summary

When MIIS_CSObject::SetPassword is called with the Boolean validatePasswordPolicy parameter the LDAP_SERVER_POLICY_HINTS control is utilised. The AD MA explicitly requests an LDAPS connection to the DC hosting the PDCe OM role and does not perform CRL checking. When MIIS_CSObject::SetPassword is called without the Boolean validatePasswordPolicy parameter, or the value is false, a “normal” password reset is performed, i.e. password history and minimum age are ignored. Reiterated another way, password resets initiated by the Password Reset Action Workflow always target the PDCe.

• If the registry value ADMAEnforcePasswordPolicy is enabled on the FIM Synchronization Service computer then an LDAPS connection is established (without CRL checking).
• If the value is disabled, or not present, a “normal” (dependent upon MA configuration, i.e. either Kerberos signing and sealing or LDAPS) LDAP connection is established to the PDCe.

References

The latest (at time of writing, use the support website for the most up-to-date information) build of FIM is hotfix rollup package kb2502631 (build 4.0.3573.2). The hotfix rollups are cumulative.

The support article that defines the configuration of the ADMAEnforcePasswordPolicy option is kb2443871.

The AD DS hotfix for the LDAP_SERVER_POLICY_HINTS control is kb2386717.

Scenario

You browse to the FIM Portal and click the link to Register for password reset. The password reset registration wizard opens and immediately the error “The Forefront Identity Manager service has not started yet. Please wait one minute and try again” is presented (screenshot below).

If you enable client side tracing you’ll see that no error is written to the trace.

Cause

Internet Explorer protected mode is enabled. The following figure shows the Internet Explorer status bar.

The status bar indicates that protected mode is on for the intranet zone.

More information

In my case I’m in a virtualised lab using my FIM server to test the password reset client settings. I’m running Internet Explorer 8 on the server and the virtual hostname of my FIM Service instance is configured to be in the Local Intranet zone.

Why is protected mode enabled? Because I’m running the Windows Server SKU. Actually, that’s only partly true. By default Internet Explorer (IE) Enhanced Security Configuration (ESC) is enabled on the Server versions of Windows. In Internet Explorer 8 and 9 Protected Mode is only enabled for Internet and Restricted Sites zones. Intranet and Trusted Sites have protected mode turned off. However when IE ESC is enabled this is slightly different –only the Trusted Sites zone is exempt from protected mode under IE ESC. That is, when IE ESC is enabled protected mode is also enabled for the Intranet zone.

Note. Protected mode is the reason for the guidance around the FIM portal hostname being a member of the Intranet zone for IE6, IE8 and IE9 and a member of the Trusted Sites zone in IE7. Although technically this limitation only applies to Vista and later versions of Windows as XP can’t use protected mode.

Moral of the story? In the lab turn IE ESC off if you want to test SSPR on your FIM server.

Summary

SSPR doesn’t work with Protected Mode enabled, even if you have configured Site Lock. If you want to use SSPR on Server versions of Windows you’ll need to add the portal hostname(s) to the Trusted Sites zone or turn protected mode off for the Intranet Zone (which requires IE Enhanced Security Configuration be turned off). At the client, the Intranet Zone is what you need if you’re running IE6, IE8 or IE9. If you’re using IE7 you should add the portal hostname to the Trusted Sites zone and enable Integrated Windows Authentication (IWA) for the zone.

Scenario

A user attempts to reset their password using Forefront Identity Manager 2010 self-service password reset (SSPR). The user successfully authenticates via the question and answer (Q&A) gate, provides the new password and receives the error:

An error occurred when trying to reset your password, please contact the helpdesk for assistance. 

Here’s a screenshot:

More information

If you look at the request log you’ll see that the action WF failed (screenshot below).

If you inspect the action WF that failed with a PostProcessingError you’ll see a request status detail of:

Exception of type 'System.Workflow.ComponentModel.WorkflowTerminatedException' was thrown. 

To get at the real error you need to look in either the event log or the trace file. Identify the PostProcessingError in the FIM Service event log or the service trace (in the event log it’ll be a warning event) and then scroll down and you’ll see an error. Here’s one such example:

PWReset Activity's MIIS Password Set call failed with call-failure:0x80004005 

That hexadecimal value is an access denied error.

Which account needs permissions to reset the password? The AD DS MA account. The Password Reset Action WF makes a call into the FIM Synchronization Service WMI interface to perform the password reset. That interface is told the target by way of the CS Object returned from this WQL query:

WQL:SELECT * FROM MIIS_CSObject WHERE (Domain='CORP' AND Account='paulw-admin') or (FullyQualifiedDomain='CORP' AND Account='paulw-admin') or (Domain='CORP' AND UserPrincipalName='paulw-admin') or (FullyQualifiedDomain='CORP' AND UserPrincipalName='paulw-admin') 

Note that if that WQL query fails the password reset will actually fail with this error:

Password Reset Activity could not find Mv record for user. 

An aside that might be helpful, that means that FIM can’t find the target. I occasionally hit this in the lab when I script the creation of users via PowerShell and forget to put them within the scope of Synchronization. J

Resolution

Grant the AD DS MA account the Reset Password Control Access Extended Right as well as write property (WP) on userAccountControl and lockoutTime.

Ignoring all other permissions for now, for SSPR you need to be able to Set a password (not change) and modify userAccountControl and lockoutTime (the latter unlocks locked out users).

Note. You don’t have to unlock users (see the bottom-most checkbox below). But why wouldn’t you do that?

The above figure is the Password Management Settings dialog (accessed by clicking Settings… in the screenshot below).

You’ll need to define these permissions within the scope of management of FIM. Here’s one approach. Assuming all users are located within child OUs of departments within a departments OU, e.g. CN=Bischoff\, Jimmy, OU=Users, OU=Human Resources, OU=Departments & Functions, DC=corp, DC=tailspin-toys, DC=com.

You can grant the necessary permissions to an SG called “Create and update user objects” to which the AD DS MA account belongs with three DSACLS commands. I’ve wrapped the commands into a CMD script. Save the following with a CMD or BAT extension and run under an account with permissions to change permissions in AD DS.

@echo off 

set targetDN=OU=Departments ^& Functions,DC=corp,DC=tailspin-toys,DC=com 
set trustee=CORP\Create and update user objects 

echo "Reset Password" Control Access Right (CAS) 
dsacls "%targetDN%" /I:S /G "%trustee%":CA;"Reset Password";user 1>NUL 

echo Write Property lockoutTime on descendant user objects 
dsacls "%targetDN%" /I:S /G "%trustee%":WP;lockoutTime;user 1>NUL 

echo Write Property userAccountControl on descendant user objects 
dsacls "%targetDN%" /I:S /G "%trustee%":WP;userAccountControl;user 1>NUL 

set targetDN= 
set trustee= 

echo All done. 

I made it difficult for myself with the ampersand character in the example above so that you can see how to escape characters. Note that I use the top-most OU to define the permissions. I make use of permissions inheritance to flow these permissions down to the OUs in which the users really reside.

Scenario

You attempt to invoke the self-service password reset (SSPR) process and get the error:

A gate plugin exception was encountered while running the Password Reset application.
Error Text: An error occurred while calling SetDisplaySettings.
Error Code: 50001.

A screenshot is below.

Alternatively you attempt to register for self-service password reset and you get a generic error:

An error was encountered. Please call helpdesk or your system administrator for further assistance.

A screenshot is below.

If you look at the FIM Password Reset client trace file (assuming you’ve enabled it) you’ll see this error:

PwdMgmtProxy: Microsoft.ResourceManagement.WebServices.Faults.ServiceFaultException: The registration workflow did not start. The FIM Service is not properly configured. 
 at Microsoft.IdentityManagement.PasswordReset.PasswordResetOperation.StartRegistration() 

Followed closely by this:

PwdMgmtProxy: Microsoft.IdentityManagement.PasswordReset.Utilities.UserFailureException: An unexpected error has occurred. Please contact helpdesk or your administrator. 
 at Microsoft.IdentityManagement.PasswordReset.PasswordResetOperation.WriteGetNGateMsg(ClientPipeContext& client) 
 at Microsoft.IdentityManagement.PasswordReset.PasswordResetOperation.Register(ClientPipeContext& client) 
 at Microsoft.IdentityManagement.PasswordReset.PasswordManagementProxy.PipeCommunicationThread(Object context) 

More information

The first error “The registration workflow did not start. The FIM Service is not properly configured.” occurs when the requestor is not a member of the All Active People set. The out-of-box (OOB) management policy rule (MPR): “General workflow: Registration initiation for authentication activity” has the All Active People set configured as the Resource Current Set and Resource Final Set. If the requestor is not a member of this set the registration or reset process will fail.

Resolution

Ensure that all members of the Password Reset Users Set are also members of the All Active People set. You could change the resource current and resource final sets but this is an OOB MPR for SSPR so you’re likely better off ensuring consistency between the set of users that can access the registration process (Password Reset Users Set) and the set of users used by one of the core MPRs for the process.

Reference

Once again Anthony Ho’s expert assistance on the FIM forum resulted in me getting to the bottom of this error quickly.

Why did this happen to me?

This is why!   JJ.

In Forefront Identity Manager (FIM) 2010 it is possible for a user to provide the same answer for each question when registering for SSPR.  There is also no control on the minimum length of an answer, whether it must have a number or not, etc.

FIM 2010 R2 (release candidate) supports QA gate complexity constraints via regular expressions.  In the QA gate activity settings in addition to defining the total number of questions, the number of questions displayed and required during registration, and the number of questions displayed and required during reset (as well as the new security context option that defines whether the gate applies to extranet or all) there are some new settings:

• Allow duplicate answers.  A Boolean value, implemented as a checkbox that, as the name implies, permits the same answer when checked.  For most of us this will remain unchecked.
• Answer constraint.  A regular expression that defines the permissible structure and complexity of answers, i.e. you can define the minimum and maximum length, allowed characters, etc.  This answer constraint is a global setting –there is not one constraint per question.
• Message to user that describes uniqueness and answer text constraints.  As the label implies this is the string that defines (displays) the constraints on the registration page.
• Terse inline error message to user for answers that violate uniqueness or text constraints.  Again, as the label nicely describes, this is the error string presented on a per-answer input basis if the answer does not match the regex defined as the answer constraint.

This is a long awaited and great improvement to the core functionality of SSPR.  To close this post and summarise the above here’s a screenshot.

A user of Forefront Identity Manager 2010 Self-Service Password Reset successfully authenticates the question and answer (Q&A) gate, inputs a new password and fails to successfully reset with the generic error “An error occurred when attempting to reset password, please try again”.

Upon inspection of the Forefront Identity Manager log in Event Viewer the following error has been recorded:

Textually, that’s an event ID 3 from Microsoft.ResourceManagement with a description of “PWReset Activity’s MIIS Password Set call failed with ma-access-denied”.

As the error suggests the issue is that the AD MA account does not have permissions to reset the password of the user in question.

Microsoft help and support knowledgebase article kb2028194 also describes this issue but instead focuses on “protected users”, i.e. those who’s security descriptor (SD) is managed by the Active Directory Domain Services (AD DS) adminSDHolder object.  Probably because the SSPR deployment guide does state what permissions are required.

The purpose of this post is to provide instructions on what permissions are required and how to deploy them.  I’ve already posted this information in the form of a CMD script at the bottom of this post.  In this post I’ll provide a PowerShell script to set the permissions.

The discussion of protected users is outside of the scope of this blog post.  The aforementioned KB describes this quite well.  In my experience I’ve kept them out of the scope of FIM 65% of the time and modified adminSDHolder the other 35% of the time.  Here’s an example script.

# SsprPermissions.ps1 v1.0 Paul Williams (pawill@microsoft.com) Microsoft Services Feb. 2012
# Simple script that grants an account (ideally a domain local group) the necessary permissions
# for the AD MA to perform a password set operation.

PARAM
(
    [Parameter(Mandatory = $false)]
    [String]$Target = "OU=People,DC=corp,DC=contoso,DC=com",
    
    [Parameter(Mandatory = $false)]
    [String]$Trustee = "CORP\FimSyncAdmaResetPasswordAccess"
);

Write-Host "`nSsprPermissions.ps1 v1.0 Paul Williams (pawill@microsoft.com) Microsoft Services Feb. 2012`n";
Write-Host "`nTarget:  $Target`nTrustee: $Trustee`n";
Write-Host "Granting the following permissions...";
Write-Host '"Reset Password" Control Access Right (CAS) on descendent user objects';
[String]$cmd = "dsacls '$Target' /I:S /G '`"$Trustee`":CA;`"Reset Password`";user'";
Invoke-Expression $cmd |Out-Null;

Write-Host "Write Property (WP) lockoutTime on descendent user objects";
[String]$cmd = "dsacls '$Target' /I:S /G '`"$Trustee`":WP;lockoutTime;user'";
Invoke-Expression $cmd |Out-Null;

Write-Host "`nScript complete.`n`n";

In summary, the ADMA account needs the following permissions on users in scope of the SSPR solution:

• Reset Password extended right.  This controls the ability to actually set (not change) a password.
• Write Property lockoutTime.  This attribute is written to unlock the account.

This post covers one of two reasons that the FIM Service fails to reset a password and throws the error PWReset Activity could not connect to the directory.  The other issue is described here.

A user of Forefront Identity Manager 2010 Self-Service Password Reset successfully authenticates the question and answer (Q&A) gate, inputs a new password and fails to successfully reset with the generic error “An error occurred when attempting to reset password, please try again”.

Upon inspection of the Forefront Identity Manager log in Event Viewer the following error has been recorded:

Textually, that’s an event ID 3 from Microsoft.ResourceManagement with a description of “PWReset Activity could not connect to the directory”.

As the error suggests the issue is that the entered password did not make it to the directory.  Or another way, the call into MIIS_CSObject::SetPassword failed.

The reason?  There might be several, i.e. an ADMA connectivity or authentication issue but one sure reason is that the Enable password management option under Password management in the Configure Extensions page of your ADMA is not checked –see screenshot below.

We must enable password management to be able to utilise MIIS_CSObject::SetPassword which is what the Password Reset Action Workflow calls.

While developing multi-language SSPR, i.e. different sets of users configured to invoke a different AuthN WF with a different QA Gate configuration based on a “primary language” or “preferred language”, I managed to revoke the ability for my non-administrative lab users to register for SSPR.  Troubleshooting was actually quite easy once I’d found a couple of web.config settings from various bits of information (mainly posted by Anthony Ho).  The purpose of this post is to attempt to define that simple technique.

The R2 password portals are ASP.NET web applications, which means they’re driven by a web.config file.  They log information to the Forefront Identity Manager event log.  You can trivially turn verbose logging on and off as well as verbose errors (displayed by the portal) via the web.config.

What’s cool about editing the web.config is that the changes are immediate, i.e. no need for a recycle of the application pool or web application.

Configuration file locations

Password Registration Portal configuration file location

By default the location of the password registration portal web.config is:

C:\Program Files\Microsoft Forefront Identity Manager\2010\Password Registration Portal\web.config

Password Reset Portal configuration file location

By default the location of the password reset portal web.config is:

C:\Program Files\Microsoft Forefront Identity Manager\2010\Password Reset Portal\web.config

Configuring verbose/detailed tracing

To configure verbose or detailed tracing to the FIM event log change the switchValue property of the source element with the name of either Microsoft.CredentialManagement.RegistrationPortal or Microsoft.CredentialManagement.ResetPortal from Error to Verbose.  You’ll find the SOURCE element under system.diagnostics\sources.

For the registration portal:

Change:

<source name=”Microsoft.CredentialManagement.RegistrationPortal” switchValue=”Error”>

To:

<source name=”Microsoft.CredentialManagement.RegistrationPortal” switchValue=”Verbose”>

For the reset portal:

Change:

<source name=”Microsoft.CredentialManagement.ResetPortal” switchValue=”Error”>

To:

<source name=”Microsoft.CredentialManagement.ResetPortal” switchValue=”Verbose”>

Configuring troubleshooting information on the error page

To have the error displayed by the Portal give you a stack trace instead of the generic custom error change:

<add key=”ShowTroubleshootingInfoOnErrorPage” value=”false” />

To:

<add key=”ShowTroubleshootingInfoOnErrorPage” value=”true” />

You’ll find that element under configuration\portalSettings\settings.

This post covers one of two reasons that the FIM Service fails to reset a password and throws the error PWReset Activity could not connect to the directory.  The other issue is described here.

A user of Forefront Identity Manager (FIM) 2010 or FIM 2010 R2 self-service password reset (SSPR) successfully authenticates the question and answer gate, inputs a new password and fails to successfully reset with the generic error “An error occurred when attempting to reset password, please try again”.

Upon inspection of the Forefront Identity Manager log in Event Viewer event ID 3 from Microsoft.ResourceManagement.Service with a description of “PWReset Activity could not connect to the directory” has been recorded.

The password reset action WF communicated with the FIM Synchronization Service but the password set operation failed.  The reason?  The Active Directory Management Agent (ADMA) is configured to run in a separate process.  See screenshot below.  The checkbox at the bottom of the properties page of the MA “Run this management agent in a separate process” must not be selected.

When an ADMA is configured to run in a separate process the password reset cannot set the password.

Two primary reasons for the Forefront Identity Manager 2010 (FIM) or Forefront Identity Manager 2010 R2 Self Service Password Reset (SSPR) password reset action workflow (WF) failing to successfully reset a password after a user has successfully authenticated via the QA Gate or one of the new R2 gates have been posted on this blog.  This post is just a quick table of contents for the two posts.  In both cases the error message logged by the action workflow is the same: PWReset Activity could not connect to the directory.

• Issue #1.  Enable password management is *not enabled* on the ADMA.
• Issue #2.  Run this management agent in a separate process *is enabled* on the ADMA.

When we get this error we can rule out membership in FIMSyncBrowse and FIMSyncPasswordSet groups, DCOM and WMI permissions.  It’s possible this error can be thrown for other reasons, but I haven’t seen any others personally and haven’t got round to simulating major Active Directory issues yet.

One thing that might be of interest however is the new feature in FIM 2010 R2 build 4.1.2548.0:

FIM Service

New feature

When the FIM password reset activity does not connect to Active Directory, the Windows Management Instrumentation (WMI) components return a code. The code explains the reason for this failure.

More information on that build can be found here (the quote above is taken from kb2750671).  That suggests we might get more info. bubbled up that helps with these silly layer-8 issues.

Most, but probably not all, will know that the FIMAutomation PowerShell snapin that shipped with Forefront Identity Manager 2010 R2 included additional cmdlets to those that shipped with FIM 2010.  The new cmdlets are for Self Service Password Reset (SSPR) registration.  There are various scenarios for utilising these cmdlets, e.g.:

• you pre-populate answers from an internal system, i.e. you don’t give users the choice of their secret answers because you have them in HR or some other system; or
• you want to register a load of users for performance testing; or
• you want to pre-populate some answers and allow the users to register some others (this is not available OOB but not too difficult to develop in ASP.NET if you have a couple of days spare).

The cmdlets in question are:

• Confirm-AuthenticationWorkflowRegistration
• Get-AuthenticationWorkflowRegistrationTemplate
• Register-AuthenticationWorkflow
• Unregister-AuthenticationWorkflow

There’s good documentation on using the cmdlets in the Programmatic User Registration information/article.

I’ve been using the cmdlets to pre-register a load of users for load testing.  I thought I’d share the script I used for easy reference.  Before I do that let’s step through the process.

Pre-requisites

The permissions required for registration are relative to the requestor, which means I can register for myself but not for another.  Before you can bulk-load registration data you therefore require an MPR.  As I’m only registering QAGate answers I just need the one MPR to allow me to do this:

• Type: Request
• Operation: Create resource, Delete resource
• Permissions: Grants Permission (True/checked)
• Target Resource Definition Before Request: All Gate Registrations
• Target Resource Definition After Request: All Gate Registrations
• Resource Attributes: All Attributes (sloppy, but it’s for admins so not too big a deal, feel free to get more granular)

You define your own set of requestors or just use the administrators set.  You define a name and description, I’m not going to tell you what to put in there.  And there’s no WFs needed.  This is all about granting you permissions to do what needs to be done.

What needs to be answered?

Logon to one of your servers running the FIM Service and open a PowerShell shell and import the FIMAutomation snap-in:

Add-PSSnapin fimautomation

Grab the AuthN WF you want to register users for and dump the questions to the screen:

(Get-AuthenticationWorkflowRegistrationTemplate `
    –AuthenticationWorkflowName 'msresource365dotCom Password Reset AuthN Workflow'
).GateRegistrationTemplates.Data.Name

The order is important!  So copy and paste that list into PowerShell_ISE or whatever you use to write scripts.

Creating the answers

Next we clone the template (we could have done this earlier but we didn’t), populate the answers and then we’re ready to perform the registration.

To clone the template we call the Clone() method of the object returned by the command we’ve just run:

$enAuthNWFTemplate = (
    Get-AuthenticationWorkflowRegistrationTemplate `
        -AuthenticationWorkflowName 'msresource365dotCom Password Reset AuthN Workflow'
).Clone()

Next we populate the answers.  We use an index, which is why we dumped the questions earlier, e.g.

# What is your favourite food?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[0].Value = "Burger, chips and a glass of Shiraz"

# What is your favourite colour?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[1].Value = "Coch tywyll"

# What is the name of your favourite musical artist, band, symphony or piece?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[2].Value = "Pearl Jam"

# What was the name of your elementary / primary school?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[3].Value = "Chateau fort de Roquetaillade"

# What was your first car/bike?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[4].Value = "Aston Martin V12 Vantage S"

# Enter a memorable date other than your birthday (YYYY/MM/DD)
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[5].Value = "14/10/1066"

# What is your favourite movie or show?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[8].Value = "The Expendables"

Registration

Submit the populated template along with a username to the FIM Service:

Register-AuthenticationWorkflow `
    -UserName corp\pawill `
    -AuthenticationWorkflowRegistrationTemplate $enAuthNWFTemplate

That returns a success status, but just in case let’s verify the operation:

Confirm-AuthenticationWorkflowRegistration `
    -UserName corp\pawill `
    –AuthenticationWorkflowName $enAuthNWFTemplate.DisplayName

Putting it all together

From my examples and the links to the documentation you can see it’s pretty easy to register a user.  The following script was very quickly written to register a large number of users so that we can do some load testing.  For the purpose of testing we need the same answers for all in-scope objects, therefore I created a CSV file of account names, prefixed with their domain, e.g. DOMAIN\sAMAccountName.  The column is called user.  The following PowerShell script reads the file from the current directory, loads the FIM PowerShell snap-in, clones the QAGate, populates it with answers, and the iterates the CSV file registering each user in the file with the same QAGate data.

Write-Host "`nSSPR QAGate bulk registration script v0.1ps1`n`tPaul Williams (pa***will****@microsoft.com) October 2013`n"

Write-Host "Consuming input CSV file"
$users = Import-Csv -Path .\sSPRBulkRegistrationUsers-Batch1-enGB.csv

if(!$?)
{
    Exit
}

if( (Get-PSSnapin -Registered | ? { $_.Name -eq 'fimautomation' }).Count -eq 1 -and
    (Get-PSSnapin | ? { $_.Name -eq 'fimautomation' }).Count -eq 0)
{
    Write-Host "Loading FIMAutomation PowerShell module"
    Add-PSSnapin fimautomation
}

if(!$?)
{
    Exit
}

Write-Host "Retrieving AuthN WF to clone"
$enAuthNWFTemplate = (Get-AuthenticationWorkflowRegistrationTemplate `
    -AuthenticationWorkflowName 'msresource365dotCom Password Reset AuthN Workflow - ENG').Clone()

Write-Host "Populating question answers"

# What is your favourite food?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[0].Value = "Burger, chips and a glass of Shiraz"

# What is your favourite colour?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[1].Value = "Coch tywyll"

# What is the name of your favourite musical artist, band, symphony or piece?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[2].Value = "Pearl Jam"

# What was the name of your primary/elementary school?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[3].Value = "Chateau fort de Roquetaillade"

# What was your first car/bike?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[4].Value = "Aston Martin V12 Vantage S"

# Enter a memorable date other than your birthday (YYYY/MM/DD)
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[5].Value = "14/10/1066"

# What is your favourite movie or show?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[8].Value = "The Expendables"

Write-Host "Registering users"
foreach($user in $users)
{
    $userName = $user.user
    Write-Host "Registering en-GB QAGate for user <$userName>..." -NoNewline
    Register-AuthenticationWorkflow `
        -UserName $userName `
        -AuthenticationWorkflowRegistrationTemplate $enAuthNWFTemplate
}

Write-Host "`nScript complete.`n"

I hope this is helpful!

In my previous post I described that Microsoft have released a preview of the next generation of directory synchronisation in the form of Azure Active Directory Synchronization Services, or AAD Sync for short.  The official announcement, via the Active Directory Team Blog, also included some other exciting news!

Preview Self Service Password Reset writeback to Windows Server AD using DirSync

A preview of DirSync password writeback for Self Service Password Reset has been added to Azure Active Directory.  This preview capability allows customers who rely on federation or password hash sync to use Azure AD Premium to reset on-premises passwords in Windows Server Active Directory.

The preview requires a new version of the Directory Synchronization tool, a.k.a. DirSync which, as stated in the official announcement, can be downloaded from this link.  Once installed the DirSync PowerShell cmdlet Enable-OnlinePasswordWriteback is used to configure the feature.  Documentation is/will be here.

What about AADSync?  Will that support write-back?  Not in the current preview is the answer to that question.

In Forefront Identity Manager (FIM) 2010 it is possible for a user to provide the same answer for each question when registering for SSPR.  There is also no control on the minimum length of an answer, whether it must have a number or not, etc.

FIM 2010 R2 (release candidate) supports QA gate complexity constraints via regular expressions.  In the QA gate activity settings in addition to defining the total number of questions, the number of questions displayed and required during registration, and the number of questions displayed and required during reset (as well as the new security context option that defines whether the gate applies to extranet or all) there are some new settings:

• Allow duplicate answers.  A Boolean value, implemented as a checkbox that, as the name implies, permits the same answer when checked.  For most of us this will remain unchecked.
• Answer constraint.  A regular expression that defines the permissible structure and complexity of answers, i.e. you can define the minimum and maximum length, allowed characters, etc.  This answer constraint is a global setting –there is not one constraint per question.
• Message to user that describes uniqueness and answer text constraints.  As the label implies this is the string that defines (displays) the constraints on the registration page.
• Terse inline error message to user for answers that violate uniqueness or text constraints.  Again, as the label nicely describes, this is the error string presented on a per-answer input basis if the answer does not match the regex defined as the answer constraint.

This is a long awaited and great improvement to the core functionality of SSPR.  To close this post and summarise the above here’s a screenshot.

A user of Forefront Identity Manager 2010 Self-Service Password Reset successfully authenticates the question and answer (Q&A) gate, inputs a new password and fails to successfully reset with the generic error “An error occurred when attempting to reset password, please try again”.

Upon inspection of the Forefront Identity Manager log in Event Viewer the following error has been recorded:

Textually, that’s an event ID 3 from Microsoft.ResourceManagement with a description of “PWReset Activity’s MIIS Password Set call failed with ma-access-denied”.

As the error suggests the issue is that the AD MA account does not have permissions to reset the password of the user in question.

Microsoft help and support knowledgebase article kb2028194 also describes this issue but instead focuses on “protected users”, i.e. those who’s security descriptor (SD) is managed by the Active Directory Domain Services (AD DS) adminSDHolder object.  Probably because the SSPR deployment guide does state what permissions are required.

The purpose of this post is to provide instructions on what permissions are required and how to deploy them.  I’ve already posted this information in the form of a CMD script at the bottom of this post.  In this post I’ll provide a PowerShell script to set the permissions.

The discussion of protected users is outside of the scope of this blog post.  The aforementioned KB describes this quite well.  In my experience I’ve kept them out of the scope of FIM 65% of the time and modified adminSDHolder the other 35% of the time.  Here’s an example script.

# SsprPermissions.ps1 v1.0 Paul Williams (pawill@microsoft.com) Microsoft Services Feb. 2012
# Simple script that grants an account (ideally a domain local group) the necessary permissions
# for the AD MA to perform a password set operation.

PARAM
(
    [Parameter(Mandatory = $false)]
    [String]$Target = "OU=People,DC=corp,DC=contoso,DC=com",

    [Parameter(Mandatory = $false)]
    [String]$Trustee = "CORP\FimSyncAdmaResetPasswordAccess"
);

Write-Host "`nSsprPermissions.ps1 v1.0 Paul Williams (pawill@microsoft.com) Microsoft Services Feb. 2012`n";
Write-Host "`nTarget:  $Target`nTrustee: $Trustee`n";
Write-Host "Granting the following permissions...";
Write-Host '"Reset Password" Control Access Right (CAS) on descendent user objects';
[String]$cmd = "dsacls '$Target' /I:S /G '`"$Trustee`":CA;`"Reset Password`";user'";
Invoke-Expression $cmd |Out-Null;

Write-Host "Write Property (WP) lockoutTime on descendent user objects";
[String]$cmd = "dsacls '$Target' /I:S /G '`"$Trustee`":WP;lockoutTime;user'";
Invoke-Expression $cmd |Out-Null;

Write-Host "`nScript complete.`n`n";

In summary, the ADMA account needs the following permissions on users in scope of the SSPR solution:

• Reset Password extended right.  This controls the ability to actually set (not change) a password.
• Write Property lockoutTime.  This attribute is written to unlock the account.

This post covers one of two reasons that the FIM Service fails to reset a password and throws the error PWReset Activity could not connect to the directory.  The other issue is described here.

A user of Forefront Identity Manager 2010 Self-Service Password Reset successfully authenticates the question and answer (Q&A) gate, inputs a new password and fails to successfully reset with the generic error “An error occurred when attempting to reset password, please try again”.

Upon inspection of the Forefront Identity Manager log in Event Viewer the following error has been recorded:

Textually, that’s an event ID 3 from Microsoft.ResourceManagement with a description of “PWReset Activity could not connect to the directory”.

As the error suggests the issue is that the entered password did not make it to the directory.  Or another way, the call into MIIS_CSObject::SetPassword failed.

The reason?  There might be several, i.e. an ADMA connectivity or authentication issue but one sure reason is that the Enable password management option under Password management in the Configure Extensions page of your ADMA is not checked –see screenshot below.

We must enable password management to be able to utilise MIIS_CSObject::SetPassword which is what the Password Reset Action Workflow calls.

While developing multi-language SSPR, i.e. different sets of users configured to invoke a different AuthN WF with a different QA Gate configuration based on a “primary language” or “preferred language”, I managed to revoke the ability for my non-administrative lab users to register for SSPR.  Troubleshooting was actually quite easy once I’d found a couple of web.config settings from various bits of information (mainly posted by Anthony Ho).  The purpose of this post is to attempt to define that simple technique.

The R2 password portals are ASP.NET web applications, which means they’re driven by a web.config file.  They log information to the Forefront Identity Manager event log.  You can trivially turn verbose logging on and off as well as verbose errors (displayed by the portal) via the web.config.

What’s cool about editing the web.config is that the changes are immediate, i.e. no need for a recycle of the application pool or web application.

Configuration file locations

Password Registration Portal configuration file location

By default the location of the password registration portal web.config is:

C:\Program Files\Microsoft Forefront Identity Manager\2010\Password Registration Portal\web.config

Password Reset Portal configuration file location

By default the location of the password reset portal web.config is:

C:\Program Files\Microsoft Forefront Identity Manager\2010\Password Reset Portal\web.config

Configuring verbose/detailed tracing

To configure verbose or detailed tracing to the FIM event log change the switchValue property of the source element with the name of either Microsoft.CredentialManagement.RegistrationPortal or Microsoft.CredentialManagement.ResetPortal from Error to Verbose.  You’ll find the SOURCE element under system.diagnostics\sources.

For the registration portal:

Change:

<source name=”Microsoft.CredentialManagement.RegistrationPortal” switchValue=”Error”>

To:

<source name=”Microsoft.CredentialManagement.RegistrationPortal” switchValue=”Verbose”>

For the reset portal:

Change:

<source name=”Microsoft.CredentialManagement.ResetPortal” switchValue=”Error”>

To:

<source name=”Microsoft.CredentialManagement.ResetPortal” switchValue=”Verbose”>

Configuring troubleshooting information on the error page

To have the error displayed by the Portal give you a stack trace instead of the generic custom error change:

<add key=”ShowTroubleshootingInfoOnErrorPage” value=”false” />

To:

<add key=”ShowTroubleshootingInfoOnErrorPage” value=”true” />

You’ll find that element under configuration\portalSettings\settings.

This post covers one of two reasons that the FIM Service fails to reset a password and throws the error PWReset Activity could not connect to the directory.  The other issue is described here.

A user of Forefront Identity Manager (FIM) 2010 or FIM 2010 R2 self-service password reset (SSPR) successfully authenticates the question and answer gate, inputs a new password and fails to successfully reset with the generic error “An error occurred when attempting to reset password, please try again”.

Upon inspection of the Forefront Identity Manager log in Event Viewer event ID 3 from Microsoft.ResourceManagement.Service with a description of “PWReset Activity could not connect to the directory” has been recorded.

The password reset action WF communicated with the FIM Synchronization Service but the password set operation failed.  The reason?  The Active Directory Management Agent (ADMA) is configured to run in a separate process.  See screenshot below.  The checkbox at the bottom of the properties page of the MA “Run this management agent in a separate process” must not be selected.

When an ADMA is configured to run in a separate process the password reset cannot set the password.

Two primary reasons for the Forefront Identity Manager 2010 (FIM) or Forefront Identity Manager 2010 R2 Self Service Password Reset (SSPR) password reset action workflow (WF) failing to successfully reset a password after a user has successfully authenticated via the QA Gate or one of the new R2 gates have been posted on this blog.  This post is just a quick table of contents for the two posts.  In both cases the error message logged by the action workflow is the same: PWReset Activity could not connect to the directory.

• Issue #1.  Enable password management is *not enabled* on the ADMA.
• Issue #2.  Run this management agent in a separate process *is enabled* on the ADMA.

When we get this error we can rule out membership in FIMSyncBrowse and FIMSyncPasswordSet groups, DCOM and WMI permissions.  It’s possible this error can be thrown for other reasons, but I haven’t seen any others personally and haven’t got round to simulating major Active Directory issues yet.

One thing that might be of interest however is the new feature in FIM 2010 R2 build 4.1.2548.0:

FIM Service

New feature

When the FIM password reset activity does not connect to Active Directory, the Windows Management Instrumentation (WMI) components return a code. The code explains the reason for this failure.

More information on that build can be found here (the quote above is taken from kb2750671).  That suggests we might get more info. bubbled up that helps with these silly layer-8 issues.

Most, but probably not all, will know that the FIMAutomation PowerShell snapin that shipped with Forefront Identity Manager 2010 R2 included additional cmdlets to those that shipped with FIM 2010.  The new cmdlets are for Self Service Password Reset (SSPR) registration.  There are various scenarios for utilising these cmdlets, e.g.:

• you pre-populate answers from an internal system, i.e. you don’t give users the choice of their secret answers because you have them in HR or some other system; or
• you want to register a load of users for performance testing; or
• you want to pre-populate some answers and allow the users to register some others (this is not available OOB but not too difficult to develop in ASP.NET if you have a couple of days spare).

The cmdlets in question are:

• Confirm-AuthenticationWorkflowRegistration
• Get-AuthenticationWorkflowRegistrationTemplate
• Register-AuthenticationWorkflow
• Unregister-AuthenticationWorkflow

There’s good documentation on using the cmdlets in the Programmatic User Registration information/article.

I’ve been using the cmdlets to pre-register a load of users for load testing.  I thought I’d share the script I used for easy reference.  Before I do that let’s step through the process.

Pre-requisites

The permissions required for registration are relative to the requestor, which means I can register for myself but not for another.  Before you can bulk-load registration data you therefore require an MPR.  As I’m only registering QAGate answers I just need the one MPR to allow me to do this:

• Type: Request
• Operation: Create resource, Delete resource
• Permissions: Grants Permission (True/checked)
• Target Resource Definition Before Request: All Gate Registrations
• Target Resource Definition After Request: All Gate Registrations
• Resource Attributes: All Attributes (sloppy, but it’s for admins so not too big a deal, feel free to get more granular)

You define your own set of requestors or just use the administrators set.  You define a name and description, I’m not going to tell you what to put in there.  And there’s no WFs needed.  This is all about granting you permissions to do what needs to be done.

What needs to be answered?

Logon to one of your servers running the FIM Service and open a PowerShell shell and import the FIMAutomation snap-in:

Add-PSSnapin fimautomation

Grab the AuthN WF you want to register users for and dump the questions to the screen:

(Get-AuthenticationWorkflowRegistrationTemplate `
    –AuthenticationWorkflowName 'msresource365dotCom Password Reset AuthN Workflow'
).GateRegistrationTemplates.Data.Name

The order is important!  So copy and paste that list into PowerShell_ISE or whatever you use to write scripts.

Creating the answers

Next we clone the template (we could have done this earlier but we didn’t), populate the answers and then we’re ready to perform the registration.

To clone the template we call the Clone() method of the object returned by the command we’ve just run:

$enAuthNWFTemplate = (
    Get-AuthenticationWorkflowRegistrationTemplate `
        -AuthenticationWorkflowName 'msresource365dotCom Password Reset AuthN Workflow'
).Clone()

Next we populate the answers.  We use an index, which is why we dumped the questions earlier, e.g.

# What is your favourite food?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[0].Value = "Burger, chips and a glass of Shiraz"

# What is your favourite colour?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[1].Value = "Coch tywyll"

# What is the name of your favourite musical artist, band, symphony or piece?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[2].Value = "Pearl Jam"

# What was the name of your elementary / primary school?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[3].Value = "Chateau fort de Roquetaillade"

# What was your first car/bike?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[4].Value = "Aston Martin V12 Vantage S"

# Enter a memorable date other than your birthday (YYYY/MM/DD)
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[5].Value = "14/10/1066"

# What is your favourite movie or show?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[8].Value = "The Expendables"

Registration

Submit the populated template along with a username to the FIM Service:

Register-AuthenticationWorkflow `
    -UserName corp\pawill `
    -AuthenticationWorkflowRegistrationTemplate $enAuthNWFTemplate

That returns a success status, but just in case let’s verify the operation:

Confirm-AuthenticationWorkflowRegistration `
    -UserName corp\pawill `
    –AuthenticationWorkflowName $enAuthNWFTemplate.DisplayName

Putting it all together

From my examples and the links to the documentation you can see it’s pretty easy to register a user.  The following script was very quickly written to register a large number of users so that we can do some load testing.  For the purpose of testing we need the same answers for all in-scope objects, therefore I created a CSV file of account names, prefixed with their domain, e.g. DOMAIN\sAMAccountName.  The column is called user.  The following PowerShell script reads the file from the current directory, loads the FIM PowerShell snap-in, clones the QAGate, populates it with answers, and the iterates the CSV file registering each user in the file with the same QAGate data.

Write-Host "`nSSPR QAGate bulk registration script v0.1ps1`n`tPaul Williams (pa***will****@microsoft.com) October 2013`n"

Write-Host "Consuming input CSV file"
$users = Import-Csv -Path .\sSPRBulkRegistrationUsers-Batch1-enGB.csv

if(!$?)
{
    Exit
}

if( (Get-PSSnapin -Registered | ? { $_.Name -eq 'fimautomation' }).Count -eq 1 -and
    (Get-PSSnapin | ? { $_.Name -eq 'fimautomation' }).Count -eq 0)
{
    Write-Host "Loading FIMAutomation PowerShell module"
    Add-PSSnapin fimautomation
}

if(!$?)
{
    Exit
}

Write-Host "Retrieving AuthN WF to clone"
$enAuthNWFTemplate = (Get-AuthenticationWorkflowRegistrationTemplate `
    -AuthenticationWorkflowName 'msresource365dotCom Password Reset AuthN Workflow - ENG').Clone()

Write-Host "Populating question answers"

# What is your favourite food?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[0].Value = "Burger, chips and a glass of Shiraz"

# What is your favourite colour?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[1].Value = "Coch tywyll"

# What is the name of your favourite musical artist, band, symphony or piece?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[2].Value = "Pearl Jam"

# What was the name of your primary/elementary school?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[3].Value = "Chateau fort de Roquetaillade"

# What was your first car/bike?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[4].Value = "Aston Martin V12 Vantage S"

# Enter a memorable date other than your birthday (YYYY/MM/DD)
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[5].Value = "14/10/1066"

# What is your favourite movie or show?
$enAuthNWFTemplate.GateRegistrationTemplates[0].Data[8].Value = "The Expendables"

Write-Host "Registering users"
foreach($user in $users)
{
    $userName = $user.user
    Write-Host "Registering en-GB QAGate for user <$userName>..." -NoNewline
    Register-AuthenticationWorkflow `
        -UserName $userName `
        -AuthenticationWorkflowRegistrationTemplate $enAuthNWFTemplate
}

Write-Host "`nScript complete.`n"

I hope this is helpful!

Implementing Azure Active Directory Password Reset?  Want to make it a bit easier for your users who logon to Azure AD using federated identities to get to the self-service password reset and/or unlock portal?

Take the following customised forms-based authentication (FBA) sign-in page in Active Directory Federation Services (AD FS) 2012 R2, a.k.a. “AD FS 3.0” – typically accessed by users outside of the corporate network, hitting the FS-P (Web Application Proxy, WAP) but also by corpnet users with devices that are not capable of performing Integrated Windows Authentication (IWA, sometimes referred to as WIA).

When a user gets their password wrong, the page changes to include the bad username/password verbiage, like so:

A requirement that has cropped up, for me at least, a few times is to allow users to navigate to the password reset workflow from here – particularly those customers that have enabled the ~updatepassword endpoint that allows for the neat in-line password change experience.

The result of this requirement is therefore something like this – the FBA sign-in page after a bad password is entered.

See how I’ve added “Forgotten your password?  Reset it here”?  Click that URL results in you hitting the Azure Active Directory Password Reset portal and the user ID input box being automatically populated with your username, as entered in the AD FS FBA user name input box:

The solution to this requirement is quite neat and easy.  Firstly, the generic Azure AD SSPR portal takes a query string called username to facilitate pre-populating the User ID input.  The client-side JavaScript therefore needs to: look for the error text on the page, and if it’s there, add a new paragraph with an anchor that contains the username already input in the form.

Here’s some proof-of-concept JS to do this:

// Code to look for bad password
var badPasswordError = document.getElementById('errorText');
if (badPasswordError) {
    if (badPasswordError.innerText.startsWith('Incorrect user ID or password')) {
        var introductionDiv = document.getElementById('introduction');
        var userNameAreaDiv = document.getElementById('userNameInput');
        var userNameFromInputBox = userNameAreaDiv.value
        if (userNameFromInputBox != userNamePlaceHolder) {
            introductionDiv.innerHTML = introductionDiv.innerHTML +
                'Forgotten your password?  Reset it <a href="https://passwordreset.microsoftonline.com?username=' + userNameFromInputBox + '">here</a>.';
        }
    }
}

To deploy the code you will need to export the current theme and modify the OnLoad.js script and then update AD FS with the modified script.  This process is documented here:

• Advanced Customization of AD FS Sign-in Pages
  https://technet.microsoft.com/en-us/library/dn636121(v=ws.11).aspx

Note.

The above code snippet has a dependency on a var called userNamePlaceHolder.  You can remove this check or you can implement the placeholder customisation with the following block of additional JS.

// Code to change the example@domain.com placeholder
var userNamePlaceHolder = document.getElementById('userNameInput');
if (userNamePlaceHolder) {
    if ("someone@example.com" == userNamePlaceHolder.getAttribute("placeholder")) {
        userNamePlaceHolder.setAttribute('placeholder', 'user.name@abstractsynapse.com');
    }
}

What the above is doing is replacing the out-of-box someone@example.com with user.name@abstractsynapse.com.