SSPR Authentication Gates

SSPR Authentication Gates

Forefront Identity Manager 2010 R2 includes several authentication gates that can be configured for use with Self-Service Password Reset. These gates can be setup as part of an Authentication workflow. By default, FIM 2010 R2 includes the Password Reset AuthN Workflow which is configured with a password gate, a lockout gate and a QA gate. Each gate can be interactive (requires user interaction) or non-interactive; and regardless of which type of gate it is, gates are executed in sequential order one after each other.

The contents of this section are as follows:

1. Security Context

2. Password Gate

3. QA Gate

4. One-Time-Password Email Gate

5. One-Time-Password SMS Gate

6. Lockout Gates

7. Gate Ordering

8. Creating your own SSPR Workflow using the Authentication Gates

Security Context

Security context is an attribute that was added for FIM 2010 R2. It is an extended attribute on requests. It is used in conjunction with Authentication gates to specify whether or not a request originates from the extranet. The Security Context property is set when a gate is created and can have a value of All or Extranet.

The following is an example of a message header that has the Security Context of Extranet:

<SecurityContextAssertionProperty 
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">
Extranet
</SecurityContextAssertionProperty>

If the Security Context is set to Extranet, the activity/gate will only be run if the request comes from the extranet.

Authentication gates will ignore the Security Context property during registration. During registration, a user has the opportunity to register for all gates which have an interactive registration experience, regardless of whether the user registers from the intranet or the extranet. This ensures that regardless of where the user registers from, they have the opportunity to register for all gates that they may need to reset their password.

Password Gate

The goal of the password gate is to ensure that the user who is registering for self-service password reset is the user who is actually logged into the Windows session. By default, it is the first gate in the password registration process. This gate is not used in the reset process. The Password Gate does not use Security Context.

QA Gate

The QA gate provides a mechanism for users to authenticate to the FIM Service. This is typically used as part of the authentication workflow for an anonymous user to authenticate to FIM, as part of the password reset process, when the user has forgotten their Active Directory password.

The QA gate was implemented in FIM 2010, and provides a mechanism for:

• An administrator to define policies related to the QA gate, including the questions used in the gate.

• An end user to register their answers to the questions which are presented to them in the gate UX.

• An end user to authenticate to the FIM Service, by providing answers to questions which match the answers that they provided during the registration process.

The Password Registration Portal provides user experience to interact with the QA gate during registration. The Password Reset Portal provides user experience to interact with the QA gate during the reset process.

During Registration, the user is presented with a number of questions. The number of questions displayed depends on how the gate is configured. The gate may also be configured to require a user to answer some or all of the questions and to not allow duplicate answers. It can also be configured so that answers much match a particular regular expression. For example, a length requirement can be imposed on users so that their answers must be a certain number of characters long.

During Reset, the user is presented with a number of questions to answer. The number of questions displayed depends on how the gate is configured. This may be all of the questions the user registered answers for or it may be a subset. If for example, the user registered for 5 questions but the gate is configured to only present 3 questions randomly, then only those questions would appear. Likewise, the gate can be configured to only require the user to answer a specific number of questions correctly. When the user clicks the ‘Next’ button, the Reset Portal validates that the user has answered a sufficient number of questions, validates that the answers comply with uniqueness policy and text constraints defined in the QA gate, and sends the data to the QA activity which is executing on the FIM Service.

.

The QA gate is configured in the business process management designer in the FIM portal. FIM 2010 R2 has several new properties in the QA gate that an administrator can configure. These are as follows:

• Allow Duplicates

• Answer Constraint

• Answer Constraint User Description

• Answer Constraint Violation Error Message

• Allow registration from FIM 2010 Password Reset Extensions for Windows

Allow Duplicates - This is a checkbox that, when checked, will allow users to provide the same answer to more than one question.

Answer Constraint – This is a textbox that allows administrators to specify what text is allowed in the text box. This is expressed as a regular expression. The default value is ^.{4,}$. This means that the answers must contain at least 4 characters. Be aware that the regular expression is applied to the answer after the answer is normalized as follows:

• The white spaces characters are removed

• The characters with accents are replaced for the character with no accent

• The characters are converted to lowercase.

For additional information on regular expressions, see Regular Expression Language - Quick Reference.

Answer Constraint User Description – This is the text box for a message that is used to describe to the end user, what is an acceptable answer based on what is defined in the Answer Constraint. This text box is located next to Message to user that describes uniqueness and answer text constraints:

Answer Constraint Violation Error Message – This is the text box for an error message that will be shown to end users when they violate the Answer Constraint. It is located next to Terse inline error message to user for answers that violate uniqueness or text constraints:

Allow registration from FIM 2010 Password Reset Extensions for Windows – This is a radio button that can be marked Allow or Disallow and specifies whether an end user, who has the FIM 2010 rich client installed can register for the QA gate with the client. The default value is Disallow.

When answers are submitted to a QA gate activity, the answers are evaluated for compliance with the policy defined in the gate configuration. If the answers comply with policy, the registration process proceeds. If the answers do not comply with policy then the registration request fails with no opportunity to retry, without resubmitting the request.

In R2, it is the responsibility of the server to communicate to the client sufficient information so that the client (PW Registration Portal) can guide the user to input data which can enable successful registration, or stated differently, prevent the user from submitting data during registration which would cause the registration request to fail.

The QA gate enforces that the user’s registration complies with policy by failing registration if:

• The user responses have less than the minimum number of answers specified in the gate configuration.

• The user responses include more answers than the number of questions that are specified to be shown to the user during registration.

• Any normalized answer does not conform to the regex specified in Answer Constraint. If no regex is specified in the gate configuration, then this criterion is always evaluated as ‘pass’.

• Any two normalized answers are duplicated. (Except, if the gate is configured to allow duplicate answers, in which case this criterion is always evaluated as ‘pass’).

The business logic for validation of user answers is summarized in the diagram below:

During the password reset process, the Password Reset portal renders a user experience to allow the user to interact with the QA gate which is executing on the FIM Service. Specifically, the user can see some or all of the questions for which they registered, and can input their answers to the questions; by successfully providing answers that match the answers from the registration process, the user will be able to proceed with the password reset process.

None of the answer policies which are enforced during registration are evaluated during reset. It would constitute information disclosure for the reset experience to tell an unauthenticated user who may not be affiliated with the organization, what are the requirements for answers to questions in the QA gate.

As during the Registration process, there are two primary types of controls which enable user interaction with the QA gate during reset, text entry boxes,the ‘Next’ button, and the Cancel button which ends the session. Additionally, the page contains the interactive controls which are shared on other portal pages: About link, Privacy Policy link, Help link.

When the user clicks the ‘Next’ button, the Portal validates that the user has answered a sufficient number of questions, and sends the data to the QA activity which is executing on the FIM Service.

If the user has answered fewer questions than specified by policy, then the Portal displays the text : You must answer [n] questions in order to reset your password. Where [n] is the number specified in the gate configuration.

In the normal case where the user’s answers are successfully received by the QA activity, the user experience is as follows:

• If the answers provided during reset match the answers stored on the gate registration object, for at least the number of questions defined in the QA gate configuration, then the user has passed the QA gate, and the user experience depends upon whether there are other gates remaining in the workflow, or other AuthN workflows to which apply to password reset for the user.

  • If there are additional gates defined in the workflow which require user interaction, or additional workflows which require authentication, then the Portal loads the user experience for the next gate in workflow which requires user interaction.

  • If there are no additional gates which require user interaction, and no other AuthN workflows, then the Portal redirects the user to the Change Password page.

• If the user does not answer a sufficient number of questions correctly, then the user is directed to the error page, where they see the error specified in that section.

• If the user’s answers aren’t successfully received by the QA activity, then the user is directed to the error page, with the error message defined in that section. For example, if the session times out or the Reset Portal is unable to contact the FIM Service for some reason.

One-Time-Password Email Gate

The One-Time-Password (OTP) Email Gate is a new Authentication gate that is being introduced in FIM 2010 R2. This gate provides a way for a user’s identity to be verified by sending a one-time-password to the user’s email address. This password is then retrieved from their email and presented to the Password Reset portal to continue the reset experience.

The OTP Email Gate uses the e-mail address that is populated in the One-Time Email address attribute of a user. This is a new extended attribute on User in the FIM Portal. If you are using Read-Only as the registration mode you must ensure that the One-Time Password Email Address attribute is populated.

The OTP Email gate is configured in the business process management designer and has the following configurable options:

• Security Context

• Registration mode:

• Length of one-time password

• Email Template for sending one-time password to user

Security Context – As described above this can be set to either All or Extranet.

Registration mode – This is a radio button that allows Administrators to specify whether or not the user should specify an email address during registration. If this is set to Read/Write, then the user will be prompted for an email address when they register. If this is set to Read-Only then the user will not be allowed to enter an email during registration.

Length of one-time password – This specifies the length of the one-time-password that is sent to the user’s email. It can be between 6 and 12 digits long. The default value is 6.

Email Template for sending one-time password to user – This is the template that is used for sending the one-time-password. By default the OTP Email gate uses the Default one-time password notification email template. This is an email template in FIM 2010 R2. This template can be edited with your own message or an entirely new email template can be created and used. This template will contain the one time password. The ONE_TIME_PASSWORD variable, which gets auto-populated with the one time password when the email is sent to the user’s email address is responsible for this.

During user registration, depending on how the OTP Email Gate is configured, the end user may or may not be asked to provide an email address. If the Registration mode is set to Read/Write, then the user will be presented with the screen below

If the Registration mode is set to Read-Only then the user will be presented with the screen shown below. This is to make the user aware that during the reset experience they will receive a security code in their email and what their current email address is in the organization. The grayed out value that is shown in the box is pulled from the One-Time Password Email Address attribute of the user. This is a new extended attribute on User in the FIM Portal. If you are using Read-Only as the registration mode you must ensure that the One-Time Password Email Address attribute is populated. This can be done through synchronization with AD, manually, or by some other process.

During reset the user is presented with a text box for entering in the security code that has been sent to the users email. The security code must match exactly or reset will fail. This means if any leading or trailing spaces are added in the text box, the reset will fail.

It is also possible to use the rich client to enter a OTP Email security code. It is important to remember that if this is going to be used in your organization then the email address used to send the OTP Email security code should be an email that is accessible by the end-user and doesn’t require the password for the organization.

The business logic for user Authentication is summarized in the diagram below:

One-Time-Password SMS Gate

The One-Time-Password (OTP) SMS Gate is a new Authentication gate that is being introduced in FIM 2010 R2. This gate provides a way for a user’s identity to be verified by sending a one-time-password to the user’s mobile phone via an SMS provider. This password is then retrieved from their mobile phone and presented to the Password Reset portal to continue the reset experience.

The OTP SMS Gate uses the mobile phone number that is populated in the One-Time Password Mobile Phone attribute of the user. This is a new extended attribute on User in the FIM Portal. If you are using Read-Only as the registration mode you must ensure that the One-Time Password Mobile Phone attribute is populated.

The OTP SMS gate is configured in the business process management designer and has the following configurable options:

• Security Context

• Registration mode:

• Length of one-time password

• SMS text message to user

Security Context – As described above this can be set to either All or Extranet.

Registration mode – This is a radio button that allows Administrators to specify whether or not the user should specify a mobile phone number during registration. If this is set to Read/Write, then the user will be prompted for a mobile phone number when they register. If this is set to Read-Only then the user will not be allowed to enter a mobile phone number during registration.

Length of one-time password – This specifies the length of the one-time-password that is sent to the user’s mobile phone. It can be between 6 and 12 digits long. The default value is 6.

SMS text message to user – This is the message that will be sent to the user’s mobile phone along with the security code. By default the OTP SMS gate uses Your security code is {0}. Where {0} is replaced with the security code.

During user registration, depending on how the OTP SMS Gate is configured, the end user may or may not be asked to provide a mobile phone number. If the Registration mode is set to Read/Write, then the user will be presented with the screen below

If the Registration mode is set to Read-Only then the user will be presented with the screen shown below. This is to make the user aware that during the reset experience they will receive a security code on their mobile phone and what their current phone number is in the organization. The grayed out value that is shown in the box is pulled from the One-Time Password Mobile Phone attribute of the user. This is a new extended attribute on User in the FIM Portal. If you are using Read-Only as the registration mode you must ensure that the One-Time Password Mobile Phone attribute is populated. This can be done through synchronization with AD, manually, or by some other process.

During reset the user is presented with a text box for entering in the security code that has been sent to the user’s mobile phone. The security code must match exactly or reset will fail. This means if any leading or trailing spaces are added in the text box, the reset will fail.

It is also possible to use the rich client to enter a OTP SMS security code.

The business logic for user Authentication is summarized in the diagram below:

Be aware that in order to implement a OTP SMS gate, there are two things that are required. They are:

• A valid SMS (Short Message Service) provider - You need to sign up with an SMS Service Provider.

• SmsServiceProvider.dll – This is code that is written the enables FIM 2010 R2 to send an SMS message to your provider. This file must be named SmsServiceProvider.dll and must be located in Program Files\Microsoft Forefront Identity Manager\2010\Service.

The following is a code example of the SmsServiceProvider.dll

//------------------------------------------------------------
// Copyright (c) Microsoft Corporation.  All rights reserved.
//------------------------------------------------------------
namespace Microsoft.IdentityManagement.Samples
{
    using System;
    using System.Collections.Generic;
    using System.Globalization;
    using System.Net;
    using System.Text;
    using Microsoft.IdentityManagement.SmsServiceProvider;
    using System.Web;
    using System.Security.Cryptography;
    using System.IO;


   
    public class SmsServiceProvider : ISmsServiceProvider
    {
        
        public void SendSms(string mobileNumber,
                            string message,
                            Guid requestId,
                            Dictionary<string, object> deliveryAttributes)
        {
            mySMSProvider.SendSms(mobileNumber, message);
        }
    }


    class mySMSProvider
    {
        static string RequestURL = "https://www.mySMSProvider.contoso.com/sms.dll?Action=SendSMS";
        static string adminAccount;
        static string adminEmail;
        static string adminPassword;

        mySMSProvider()
        {
        }

        public static int SendSms(string userMobileNumber, string message)
        {
            WebClient wc = new WebClient();
            string requestData;

            requestData = Microsoft.IdentityManagement.Samples.mySMSProvider.GetRequestData(userMobileNumber, message);

            byte[] postData = Encoding.ASCII.GetBytes(requestData);

            byte[] response = wc.UploadData(mySMSProvider.RequestURL, postData);

            string result = Encoding.ASCII.GetString(response);  // result contains the error text

            int returnValue = System.Convert.ToInt32(result.Substring(0, 4), NumberFormatInfo.InvariantInfo);
            return returnValue;
        }

        public static string GetRequestData(string mobile, string message)
        {

            string myrequestData;

            myrequestData = "AccountId=" + adminAccount
                 + "&Email=" + System.Web.HttpUtility.UrlEncode(adminEmail)
                 + "&Password=" + System.Web.HttpUtility.UrlEncode(adminPassword)
                 + "&Recipient=" + System.Web.HttpUtility.UrlEncode(mobile)
                 + "&Message=" + System.Web.HttpUtility.UrlEncode(message);

            return myrequestData;


        }

        public void GetCredentials()
        {
 
            string mypwordFile = (@"C:\Program Files\Microsoft Forefront Identity Manager\2010\Service\SmsEncryptedCredentials.txt");


            FileInfo info;
            int len;
            byte[] buffin;
            byte[] buffout;

            byte[] Entropy = { 9, 8, 7, 6, 5 };

            info = new FileInfo(mypwordFile);
            len = (int)info.Length;

            buffin = File.ReadAllBytes(mypwordFile);
            buffout = ProtectedData.Unprotect(buffin, Entropy, DataProtectionScope.CurrentUser);

            File.WriteAllBytes(mypwordFile, buffout);

            StreamReader sr = new StreamReader(mypwordFile);
            adminAccount = sr.ReadLine();
            adminEmail = sr.ReadLine();
            adminPassword = sr.ReadLine();


            sr.Close();

            buffin = File.ReadAllBytes(mypwordFile);
            buffout = ProtectedData.Protect(buffin, Entropy, DataProtectionScope.CurrentUser);

            File.WriteAllBytes(mypwordFile, buffout);
            

        }


    };
}

For additional information on creating the SmsServiceProvider.dll see Test Lab Guide: Demonstrating the FIM 2010 R2 Password Reset SMSProvider with the OTP SMS Gate and MSDN.

Lockout Gates

Lockout Gate is a non-interactive gate and it does the following:

1. It checks if the user is temporarily locked out. If yes, the authentication will fail and the user would receive an error message. Notice if the user is permanently locked out, the request processor will kick the user out in earlier stages and will never hit the Lockout Gate.

2. Increments the lockout counter for the specific user.

3. Temporarily or permanently lockout the user if necessary based on the updated counter.

It also registers itself to the workflow's Completed event, when signaled, will unlock the user.

The Lockout gate is configured in the business process management designer and has the following configurable options:

• Security Context

• Lockout

Security Context – As described above this can be set to either All or Extranet.

Lockout – This allows for three items to be configured. The first is the lockout duration in minutes. This is how long a user will be locked out of the reset portal if the lockout threshold is reached. The second, is the lockout threshold. This is the number of times the user can fail to complete the workflow before they are locked out. And finally the number of times a user can be locked out of the reset portal before becoming permanently locked out of the portal.

The business logic for the Lockout gate is summarized in the diagram below:

Gate Ordering

Suppose you have an Authentication Workflow (AuthN WF) that has a Lockout gate followed by a QA gate. A malicious user could initiate SSPR for EmployeeA and intentionally fail the QA gate to permanently lockout EmployeeA.

By changing the AuthN WF to QA -> Lockout -> QA, the Lockout Gate will not be hit unless the malicious user passes the first QA Gate.

Please note that in this case, the first QA Gate is not protected by the Lockout Gate and is subjected to a brute force attack. That is the price you have to pay to prevent Denial of Service using the Lockout Gate. You should work with your security compliance team in your organization to decide what is right for your organization.

A common mistake in gate ordering is to have only a lockout gate after a QA gate.

In this instance you can attempt to answer questions several times and you will never get locked out. The reason is you will only hit the lockout gate if the QA gate is passed successfully. Because the lockout gate is non-interactive, it will increment the lockout counter but then subsequently reset it to zero because the workflow is over and has been successful. The QA gate does not hold the lockout counter. Only the lockout gate does.

So to resolve this you can place either a password authentication gate (for the registration page) or a QA gate before the lockout gate and then have an additional QA gate after the lockout gate. This way, once the user has either successfully passed the first gate, the lockout gate is hit and the counter incremented then the next gate is hit. If the user fails this gate, the counter is still incremented and additional attempts will ultimately hit the lockout threshold and lock the user out. Keep in mind that if a user cancels out of the QA gate, say by just exiting their browser, the lockout counter will still be incremented and will not be set back to zero. Only successfully completing the workflow will achieve this.

Also, as mentioned above, you don’t want to have just a Lockout gate followed by a QA gate as this could allow a malicious user the ability to lock accounts out.

Creating your own SSPR Workflow using the Authentication Gates

By default, FIM 2010 R2 provides the Password Reset AuthN Workflow. This workflow can be modified to suite your organizations needs by adding or removing additional Authentication gates. This can be done from the Activity Picker in the business process management designer.

In some cases, it may be desirable to create your own workflow and use that instead of the default one provided. This can be done with the following steps.

1. Create an Authentication Workflow

   

2. Modify the Password Reset Objects set

   

3. Modify the Anonymous Users can reset their password Management Policy

   

Configuring password registration and reset for multiple languages

Use the following steps to configure environments where users may need to access the password portals in different languages. This example will use English, French, German, and Italian.

To configure password registration and reset for multiple languages

1. For each language, do the following:

   • Create a set for the related language – For example: EnglishUsersSet, FrenchUsersSet, GermanUsersSet, ItalianUsersSet

   • Create a duplicate of the Password Reset AuthN Workflow for the related language – For example: EnglishAuthNWorkFlow, FrenchAuthNWorkflow, GermanAuthNWorkFlow, ItalianAuthNWorkflow

   • Create a duplicate of the MPR ‘Anonymous Users Can Reset Password’ for all of the related languages

     The following is the structure for English users:

     Policy	English Anonymous Users Can Reset Password
     Type:	Request
     Requestors:	Anonymous Users
     Operation:	Modify a single-valued attribute
     Permissions:	Grant
     Target Resource Definition Before Request:	EnglishUsersSet
     Target Resource Definition After Request:	EnglishUsersSet
     Resource Attributes:	Select specific attributes Reset Password
     Policy Workflows	Authentication Workflows EnglishAuthNWorkFlow Action Workflows Password Reset Action Workflow

   •  

2. Add the following to the Password Reset Objects set:

   • All newly created sets – For example: EnglishUsersSet, FrenchUsersSet, GermanUsersSet, ItalianUsersSet

   • All newly created AuthN workflows – For example: EnglishAuthNWorkFlow, FrenchAuthNWorkflow, GermanAuthNWorkFlow, ItalianAuthNWorkflow

   • All newly created MPRs – For example: English Anonymous Users Can Reset Password, French Anonymous Users Can Reset Password, German Anonymous Users Can Reset Password, Italian Anonymous Users Can Reset Password

3. Disable the default MPR “Anonymous Users can Reset Password”

   Warning

   Be aware that once Anonymous Users can Reset Password is disabled, any user outside of the sets we created above will not be able to reset the password.