SurePassID ADFS MFA Adapter Install Guide

SurePassID Authentication Server

SurePassID MFA for Active Directory Federation Services (ADFS)

This guide explains how to install and configure the SurePassID MFA Adapter for Windows. This guide's purpose is to provide a reference for system administrators.

This guide provides information on the following topics:

• What is SurePassID MFA Adapter?

  • A brief introduction to the SurePassID MFA Adapter.

• Installing and Configuring SurePassID MFA Adapter

  • Detailed explanations for installing the SurePassID MFA Adapter in a Windows environment.

What is the SurePassID ADFS MFA Adapter?

The SurePassID MFA Adapter is an ADFS MFA authentication plug-in that adds Two Factor Authentication (2FA) to any application (relying party) defined to ADFS.

The SurePassID MFA Adapter supports both IdP initiated logins and SP (service provider - relying party) started logins and with any SurePassID MFA server (cloud, on-premises) supporting all the SurePassID 2FA supported authentication methods and devices.

Send OTP Options:

• Send SMS OTP– Sends SMS text message having the OTP sent to the user’s phone.

• Send OTP by Voice Call - Call is made to the user’s phone speaking the OTP. This is an invaluable option for users that do not have SMS capabilities on their phone or users sitting at their desk or for the visually impaired.

• Email Code – An email having the OTP is sent to the user’s email account.

Push Authentication Options:

• Push SMS Question – A question is sent to the user’s mobile device asking the user to confirm a request to allow access to the system. If the user responds positively, they can log in with just a username and password.

• Push Question - A question is sent to the user’s mobile device asking the user to confirm a request to allow access to the system. If the user responds positively, they can log in with just a username and password. Requires SurePassID Mobile Authenticator.

• Push OTP - An OTP is sent to the user’s mobile device. The OTP can be used as if it were an OTP from a soft token, or hard token (fob or card). Requires SurePassID Mobile Authenticator.

• Push Voice Question - A voice call is made to the user’s phone asking the user to confirm access to the system. If the user responds positively, they can log in with just a username and password.

• Push Fido2 Question – A phishing-resistant prompt is sent to the user's mobile device requesting Fido2 authenticator confirmation. If approved, the user can log in with only a username and password. SurePassID Mobile Authenticator is required.

Security

SurePassID ADFS MFA Adapter Server requires TLS 1.2 or TLS 1.3 for transport security.

System Logging

SurePassID ADFS MFA Adapter maintains its own system log files to store critical information. The system logs help you troubleshoot and repair any issues the system might encounter during daily operations.

Installing the ADFS MFA Adapter

The SurePassID ADFS MFA Adapter installation installs the required components.

To install the SurePassID ADFS Adapter, you must first download and unzip the installer from here:

https://downloads.surepassid.com/ADFS/ADFSA.zip

The SurePassID ADFS MFA Adapter installer and application is digitally signed by SurePassID. You must verify that as part of the installation.

After downloading, unzip the file and run the installer.

Remember My Device

Users can choose to have their device remembered for several days, allowing them to skip 2FA during that period.

Pro Tip:

All messages sent to the user can be tailored to your organization's needs in the SurePassID portal using the Customize SMS Messages and Customize Email Messages menus.

Prerequisites

The SurePassID ADFS MFA Adapter is compatible with the following 64-bit Windows versions:

• Windows 2012 – All versions

• Windows 2016 – All versions

• Windows 2019 – All versions

• Windows 2022 – All versions

• Windows 2025 – All versions

SurePassID ADFS MFA Adapter is compatible with these ADFS versions:

• ADFS 2.x

• ADFS 3.x

• ADFS 4.x

• ADFS 5x

SurePassID ADFS MFA Adapter needs a SurePassID MFA server, either in the Azure cloud or on-premises.

Here are a few recommended items to consider after installing the SurePassID ADFS MFA Adapter.

• Configure ADFS Gateway Server Configuration

These suggestions will be addressed later.

Installing the ADFS MFA Adapter

The SurePassID MFA Adapter installer will install all the MFA Adapter components and prerequisites.

To install the product, you must first download the installation file https://downloads.surepassid.com/ADFS/ADFSA.zip, unzip the file and run SurePassID ADFSAdapter.exe and you will see the following installation form:

Click Next and the SurePassID MFA Adapter License Agreement will be displayed.

Read the License Agreement and if you agree then select the “I accept the terms in the License Agreement” radio button and then click the Next button and you will see the installation folder form.

Select or confirm the installation folder, then click Next button to continue.

Click the Install button to start the installation process. You will first be presented with SurePassID verified publisher statement.

If you do not see the Verified Publisher: SurePassID Corp. click No to cancel install. If you do see it, click Yes to install the product.

The installation is complete. Click the Finish button. You are now ready to configure the system.

Configuration Settings

The SurePassID MFA Adapter configuration settings are stored in the SurePassIdAdfsAdapterconfig.txt file located in the SurePassID MFA Adapter installation folder.

The format of this file is the same format as the settings file for the Windows Credential Provider and other SurePassID plug-ins. The default settings file SurePassIdAdfsAdapterconfig.txt is discussed below:

Step1: Configure SurePassID ADFS Adapter Settings

All the configuration settings for the system are in ADFS conf file (SurePassIdAdfsAdapterconfig.txt) found in the folder where the product is installed.

Note: When you make changes to the SurePassIdAdfsAdapterconfig.txt file, the settings will not take effect until the remove and install PowerShell scripts have been rerun. See Step 2 below.

The format of the file is one option per line, each option is a combination of an option name and value separated by an equal (=) sign. Option names are described in the following sections.

• AuthenticationMode – The MFA Adapter can operate in Primary Authentication mode (PA) or Secondary Factor Only mode (SFO).

  • In PA mode, the MFA Adapter will perform both first factor authentication (using SurePassID directory) and second factor.

  • SFO mode only performs the second factor authentication after Active Directory perform the users first factor (username, password) authentication.

AD FS Configuration Manager allows you to set ADFS to allow external authentication (e.g. MFA adapter) as primary or second factor.

• If you configure ADFS to use SurePassID as the primary authentication, then set this value to p.

• If you configure ADFS to use SurePassID as second factor authentication then set this value to s.

The default is s (second factor).

NOTE: Only ADFS 4.0 and later support primary authentication.

• AuthServerURL – The SurePassID authentication endpoint URL. In most cases, you will not need to change this unless you are using a custom SurePassID installation. The values are:

  • sandbox - The SurePassID sandbox system.

  • prod – The SurePassID production cloud system.

• AuthServerToken - Refers to the API Key Identifier, which forms one part of a custom API Key used to specify ADFS access rights to an MFA server. For earlier versions of SurePassID, use Server Login Name for your SurePassID account.

• AuthServerKey - Refers to the API Key, which forms a second part of a custom API Key used to specify ADFS access rights to an MFA server. For earlier versions of SurePassID, use Server Login Password for your SurePassID account.

All application requests to the MFA Server require an Application Key. To create a new Application Key just for RADIUS Server (recommended) click the New Application Key link and see the form below:

The Key Name is the friendly name to identify this key. It is not used for any security purposes. For instance, you could name it ADFS Key.

Select the ADFS Adapter from the Permissions Templates drop-down list.

The Key Identifier parameter is the AuthServerToken and the Key parameter is the AuthServerKey

Copy Key Identifier and Key for later use when configuring ADFS MFA Adapter. One you click the Add button the Key will no longer be viewable. If you forget the Key, you can delete this Application Key and add a new one.

Press the Add button to save the Api Key.

Caution: Deleting an Application Key prevents applications using it from accessing the MFA Server. It cannot be restored; a new key must be generated and updated in the application.

• LogLevel - Turn on local logging for the system. This setting is used to debug issues with the system. Unless required, logging should be turned off. By the default log files are created in the c:\windows\temp folder. The default log path can be changed by setting the LogFilePath to the desired location. Values for LogLevel are:

  • 0=no logging

  • 1=logging is on

  • 2=advanced (REST API logging – trouble shooting only)

• LogFilePath – The path where log files will be written to. This path must exist. If not specified, the default path is c:\windows\temp. By default the system does not log events to the Windows Event Log. If you want the logs sent to the Windows Even Log run the following Powershell command:

New EventLog -LogName SurePass – SourceName ADFSAdapter

• SecureCookieName – The name of the cookie that will be used to store state information about the Remember My Device session. The default value is SP_CookieMonster_.

• mailto:DoNotShowCookieName – The name of the cookie that will be used to store information about the Remember My Device session state information.The default value is SP_DNSCookie.

• SurePassUseUpn – By default SurePassID sends the user account name without domain information to the SurePassID MFA server when performing user authentication. Setting this parameter changes the default behavior and SurePassID MFA Adapter sends the entire user User-Principal-Name (UPN) to the MFA Server server. A UPN consists of a UPN prefix (the user account name) and a UPN suffix (a DNS domain name). This means the user name in SurePassID MFA server will need to be the UPN and not just the username.

• SessionDays – This parameter turns on and configures the Remember My Device option. If you set this parameter to 0 or do not provide it then the Remember My Device option is not available to the user. A non-zero value represents the number of days a user’s access will not require MFA authentication for login. The user turns on this feature by checking the Remember My Device option when in the option is presented. For example, if you set SessionDays=10 and the user checks the Remember My Device the user will not need to use MFA authentication for the following 10 days after they login with MFA authentication. This feature if for convenience in low risk situations only.

• DoNotShowDays – The number of days that the Remember My Device option will not be shown. This value cannot be less than Session days. The default value is SessionDays.

• WaitForPushResponse – All push requests will wait for the user to authenticate on their mobile or until the request times out. 0=no 1=yes. Default is 1.

• GenericErrorText – The html text that will be displayed to the user when an error is received from the SurePassID MFA server. If this setting is not specified the message displayed to the user is the message received from the SurePassID MFA server. The original error from the server is always written to the trace log if tracing is turned on (LogLevel= 1 | 2).

• AllowSMS - Allow the user to request an OTP be sent by SMS to their mobile device. 0=no 1=yes.

• AllowEmail - Allow the user to request an OTP be sent to their email. 0=no 1=yes.

• AllowCall - Allow the user to request an OTP be sent by voice call. 0=no 1=yes.

• AllowPushApp - Allow the user to request that a push authentication be sent (pushed) to their mobile device to confirm their identity. Requires the user to have SurePassID Mobile Authenticator installed on their mobile device. 0=no 1=yes.

• AllowPushSMS - Allow the user to request that an SMS push question can be sent to their mobile device to confirm their identity. 0=no 1=yes

• AllowPushVoice - Allow users to request a voice call that will allow them to confirm their identity. 0=no 1=yes.

• SurePassUseVerifyMethod– By default the SurePassID admins sets user allowable authentication methods in the config file as defined by the Allow settings (e.g. AllowSMS) in the config file. This setting can dynamically adjust the user’s allowable authentication methods. This is an advanced function and requires additional server side set-up and may not be available on your platform. 0=no 1=yes.

• PushAppName - For push authentications, the name of the application requesting access. The PushAppName is displayed to the user when they receive a push notification. The default is ADFS. Users should not accept push requests from unknown app names or requests that were not initiated by them.

• PushAuthnReason – For push authentications, the reason why the application is requesting access that is displayed to the user on their mobile. The default is Login. Users should not accept push requests for known reasons.

• RelyingPartyUrl - For push authentications, the url of the application requesting access. This is the endpoint that will accept push responses from the user’s mobile device. This can be complex depending on your configuration. You should not specify this parameter unless instructed by SurePassID technical support.

• PasswordText – The textbox helper text for the user to enter their password

• PasscodeText - – The textbox helper text for the user to enter their passcode (OTP).

• RMD_DNSText – The html text that will be present at the bottom the MFA authentication form. The default value is

<b>Please select an option and press the Done button</b>

• RMD_DNSButtonText – The html text that will be present at the bottom the MFA authentication form. The default value is Done.

• RememberMyDeviceText – The html text that will be present at the bottom the MFA authentication form. The default value is Remember My Device

• DoNotShowAgainText – The html text for the Do Not Show This Again checkbox that relates to the RememberMyDevice option.

The default value is Do Not Show This Again.

• SupportText – The html text that will be present at the bottom of the MFA authentication form. The default is

Support Email: supportk@surepassid.com>

• NoValidAuthenticationMethods – The html text that will be displayed to the user if they have no MFA authentication methods assigned to them. Default is:

<b>No authentication methods available for your account. Contact your administrator.</b>

The following figure shows the locations of each of these user interface settings on the form.

Configure ADFS For Second Factor Only

Follow these steps to add SurePassID MFA as a strong authentication provider for ADFS.

Open the ADFS Management Console to select Authentication Policies in the left pane to see settings in the right pane.

The Authentication Policies setting defines how ADFS will handle primary authentication (first factor) which is usually username and password, and MFA authentication configured in each section.

Clicking the Edit button to the right of Global Settings in the MFA Authentication section allows you to set any number of MFA authentication providers at the global level for all relying party apps such as Outlook Web Access, Office 365, SharePoint, etc. that will use these authentication settings.

Clicking Manage to the right Custom Settings can let you set the MFA authentication options on a relying party by relying party basis. When clicking the Edit button, you will see the following form.

As you can see the only MFA authentication option is Certificate Authentication.

To add SurePassID as the MFA authentication option, follow these steps:

Start your favorite version of PowerShell as an Admin and open the install.ps1 located in the scripts folder of the SurePassID ADFS installation folder.

C:\Program Files (x86)\SurePassId Corp\SurePassId Adfs Adapter\scripts

Click the green run button on the top of the toolbar and you will see the following screen showing that the adapter is configured as highlighted in a green box.

Once the script has been executed, navigate to Authentication Policies and select the Edit option next to Global Settings. The SurePassID MFA Adapter will be available; activate it by selecting the corresponding checkbox as indicated below:

Pro Tip:

Upon installation of the SurePassID MFA Adapter, ADFS reads the configuration settings from SurePassIdAdfsAdapterconfig.txt and stores them in the ADFS repository. Any modifications to these settings will only take effect if the SurePassID MFA Adapter is first removed (by executing the remove.ps1 script) and then re-installed (by executing the install1.ps script).

This document does not cover the ADFS Relying Party app setup due to frequent changes in options. Please refer to Microsoft ADFS documentation or contact our support team for assistance.

Step 4: Using ADFS MFA Adapter For Authentication

After you have turned on SurePassID MFA Adapter for an app (relying party) or globally for all relying parties, you can login to the system using MFA authentication.

This example will show you how to use the IdP initiated method however, the SP (Service Provider) initiated method will be nearly identical.

Open the IdP initiated ADFS login page as show below.

Click the Sign in button.

Enter your Active Directory credentials and click the Sign in button. If they are correct you will see the following:

If the system administrator as reset the users Password/PIN account the user will see the following options to reset their Password/PIN:

You can enter your OTP from a hard or soft token or select an alternative method from the links below. For example, if Send passcode via SMS was selected, the following will be displayed.

The page is updated to show the Passcode has been sent.

Enter the passcode and select Login. If correct, the following screen appears:

You are now signed in. You can now access any ADFS apps without re-entering any credentials.

Step5: Using MFA Adapter For Primary MFA Authentication

Once the SurePassID MFA Adapter is enabled for a specific application (relying party) or globally for all relying parties, users can access the system using primary MFA authentication. Primary MFA authentication allows SurePassID to verify both the first factor (username and password) and the second factor.

This example demonstrates the IdP-initiated method; the ADFS SP-initiated approach is remarkably similar.

• Open the IdP initiated ADFS login page as shown below.

• Click the Sign in button.

• Enter your Active Directory username and press the Next Button.

This option appears only if ADFS supports multiple primary authentication methods. If SurePassID is the sole primary authentication method, the form will not appear.

• Select SurePassID Strong Authentication.

• Enter the SurePassID Password/PIN for this user and press Login.

• If the password/PIN is incorrect the form will be updated. Re-enter your password/PIN and press the Login button. When the password is correct you will proceed.

• Enter your passcode (OTP) and press Login or select another authentication method.

If your administrator resets your SurePassID password or PIN, the previous form will not appear; you will see a new form instead:

• To reset the password/PIN enter your new password/PIN followed by a valid passcode (OTP) and press Login.

If you are successful in authentication with your second factor or changing your Password/PIN you will see the following message:

• You are signed in and can use all your ADFS applications.

• Enter the passcode and select Login. If correct, the following will appear:

You are signed in. You can now access any ADFS apps without re-entering any credentials.