Overview

This document is an installation guide for the OpenOTP Authentication Provider for AD FS 3.0 / 4.0. Hence, the installation or configuration of WebADM, including token registration is not covered in this guide. For installation and usage guides to WebADM refer to the RCDevs WebADM Installation Guide and Administrator guides available through the RCDevs’ online documentation.

The OpenOTP Authentication Provider for AD FS is a component that integrates the RCDevs OpenOTP authentication into an Active Directory Federation Services server, adding OpenOTP authentication as a possible MFA option in the AD FS Management tool.

The OpenOTP Authentication Provider for ADFS allows you to use various types of authentication tokens and standards supported by the OpenOTP server. This includes OATH HOTP/TOTP, push notifications with OpenOTP Token, YubiKeys, SMS, phishing-resistant methods such as FIDO2 and more.

System Requirements

The OpenOTP Authentication Provider has to be installed on the Windows servers with an AD FS role. Your environment should fulfill the following requirements:

  • Windows 2008 or later.
  • Network access.
  • An instance of WebADM and OpenOTP running in your network.
  • Permanent connection to OpenOTP server’s network API.
  • DNS suffix set to match your AD domain.

Preliminary Information

Administrative/elevated permissions are necessary on ADFS server(s) to correctly set up and/or change the OpenOTP Authentication Provider’s configuration.
To correctly set up the provider, please gather the following information. You will need to enter during the installation process:

  • The URI(s)s of the OpenOTP web-service(s) (mandatory).
    • These URIs are mandatory, due to the client needs to know where the OpenOTP SOAP network API can be reached. They are entered as a comma-separated list. At least one URI is necessary.
  • Your local domain (optional). Needed to force a domain, which is not set as default on the OpenOTP side.
  • A custom login text or tile caption (optional). A text that is displayed on the AD FS login pane.
  • A client ID (optional). An ID to identify this part of your infrastructure to OpenOTP, allowing to modulate OpenOTP’s behavior with client policies.
  • A certificate authority (CA) file (optional).
  • A certificate file and the certificate password (optional).
  • A custom settings string (optional).
  • SOAP timeout delay (optional).

OpenOTP plugin for ADFS works for ADFS 3.0 & 4.0 (earlier than Windows server 2008). If you have an older version, you have to update your ADFS Infrastructure.

Installation and Configuration

Installation

In this post, we assume an existing ADFS infrastructure is in place and available. This post will not cover the ADFS infrastructure setup. For guidance on setting up ADFS, please refer to the Microsoft Documentation.

For this tutorial, you will need to have WebADM/OpenOTP installed and configured. Please refer to the WebADM installation and administration guides for detailed instructions.

Before running the MSI file, please make sure your ADFS and WebADM/OpenOTP services are running.

The OpenOTP plugin for ADFS must be installed on every ADFS server. Download the plugin from the RCDevs Website.

Extract the files from the archive on your ADFS server(s), then run the MSI file and click Next.

The MSI file should be executed with domain admin or local admin permissions. To ensure you have the required permissions for the installation, you can run the MSI file through PowerShell in "Run as Administrator" mode.

adfs
adfs

Review and accept the End-User License Agreement, then click Next. On the following page, select your default folder location and click Next.

adfs

On this page, you need to configure the URL of one of your WebADM servers. If you are running a WebADM cluster, the OpenOTP URLs should be automatically retrieved in Auto mode. If the URLs are not automatically retrieved, you can configure them manually as shown below:

adfs

Click Next. On the following page, all configuration options are optional. If you wish to use a client certificate for enhanced security, you can provide the details on this screen.

Click the information icons (i) for additional guidance throughout the installation process.

adfs

On the next page, you can configure failover with OpenOTP, set the SOAP request timeout, and adjust UPN Mode. If you're unsure, it's best to keep the default settings. Click Next and then Install.

Here, you can also specify a custom settings string for your WebADM and OpenOTP configuration, although this setting is deprecated since WebADM client policies. Additionally, you can modify the default SOAP service timeout. If you have defined two server URLs, you can set up a request routing policy:

  • Ordered: The first server is preferred. If it does not respond, the second server is used.
  • Balanced: Servers are selected randomly for each request. If one does not respond, the other is used.
  • Consistent: Server selection is based on the user ID. Requests for a specific user are routed to the same server. If that server does not respond, the other server is used.

Click Next when you are finished, and then click Install.

adfs

On the next page, you can configure a custom message to display when users need assistance. For example:

adfs

On the next screen, you will be prompted to provide the ADFS WAP IP address(es). If you enable the setting Send the service provider ID as the Client ID to OpenOTP, the ADFS absolute URI will be automatically returned.

The checkbox Send the service provider ID as the Client ID to OpenOTP allows you to send a unique value per service provider to OpenOTP, enabling the creation and matching of a dedicated client policy for each service provider configured with ADFS. If a unique identifier cannot be retrieved for a service provider, the default Client ID value configured in step 1/5 will be sent to OpenOTP.

This feature is supported for WS-Federation, SAML, and OpenID implementations.

adfs

Click Next to continue the setup.

adfs

The installation is almost complete. At the end of the ADFS plugin installation, you will see a message similar to the one below:

adfs

You need to provide the SID of your ADFS service account. Check your ADFS service configuration to obtain the name and domain values.

The following commands should be executed in the Windows Command Prompt, not in PowerShell.

C:\Users\administrateur>wmic useraccount where (name='svc_adfs' and domain='RCDEVSDOCS') get sid
SID 
S-1-5-21-2556788148-2650686732-506205049-1105

If you are using a Managed Service Account, the above command will not return the SID. Instead, you should use the Get-AdServiceAccount command on your AD domain controller.

For example, if the service account is adfs$, you would use the following command:

PS C:\Users\Administrator.RCDEVSDOCS> Get-ADServiceAccount -identity svc_adfs$

DistinguishedName : CN=svc_adfs,CN=Managed Service Accounts,DC=rcdevsdocs,DC=com
Enabled           : True
Name              : svc_adfs
ObjectClass       : msDS-GroupManagedServiceAccount
ObjectGUID        : c8cc36ac-4a81-4973-bcba-f23e59f7f50d
SamAccountName    : svc_adfs$
SID               : S-1-5-21-2556788148-2650686732-506205049-1105
UserPrincipalName :
adfs

On the next screen, you will be prompted to register the plugin in your ADFS configuration database. The registration should only be performed on the primary ADFS server that owns the configuration (master). Click Yes if you are installing the plugin on the master server, and No if you are installing it on secondary ADFS nodes. Ensure that ADFS services are running during the registration.

adfs

After the Authentication Provider registration, ADFS services will be automatically restarted.

adfs

On the next screen, click on Finish and the installation is done.

adfs

Repeat this procedure on every ADFS servers!

ADFS Configuration for Multi-Factor Authentication

In this documentation, we enable OpenOTP Multi-Factor Authentication on the default ADFS login page, which is disabled by default.
For instructions on enabling the default ADFS login page, refer to Microsoft Documentation.

With ADFS 4.0 on Windows Server 2019, the PasswordLess feature is now available. This allows users to log in to ADFS by providing only their username and OTP. The username must correspond to a valid account in Active Directory.

Configuration for ADFS 3.0

Now, we will configure the ADFS server(s) for multi-factor authentication. To do this, open Windows Server Manager, click on Tools, and select ADFS Management.

adfs
adfs

On the ADFS Management page, right click on Authentication Policies and click on Edit Global Multi-factor Authentication.

adfs

On the next page, you will see a new option under additional authentication methods named "RCDevs OpenOTP Authentication Provider." Check the box next to this option and click OK.

adfs

Your ADFS server is now configured with OpenOTP for ADFS plugin. In order to use it, your relaying party must be configured for multi-factor authentication.

Configuration for ADFS 4.0

Now, we will configure the ADFS server(s) to have multi-factor authentication. For this, go on Windows Server Manager, click on Tools and ADFS Management.

adfs

On the ADFS Management page, under Service right click on Authentication Methods and click on Edit Multi-factor Authentication Methods.

adfs

On the next page, you will find a new option available in the additional authentication methods named RCDevs OpenOTP Authentication Provider. Check the box of this option if it's not already checked and click Apply.

adfs

Relaying parties configured for MFA authentication can now use OpenOTP for ADFS plugin.

Windows Hello For Business

In order to be able to use OpenOTP authentication for Windows Hello for Business devices registrations, you need to execute the following command through PowerShell on your primary ADFS server:

Set-MsolDomainFederationSettings -DomainName <DOMAIN NAME> -SupportsMfa $true

Adapt the command with your domain name. On my side it is:

Set-MsolDomainFederationSettings -DomainName RCDEVSDOCS -SupportsMfa $true

PasswordLess Configuration for ADFS 4.0

Windows Server 2019 introduces some notable changes to ADFS, particularly relevant for OpenOTP use cases:

  • External Authentication Providers as the Primary Authentication Method: OpenOTP can now serve as the first authentication factor, eliminating the need to expose the AD password initially. Additionally, since the OpenOTP ADFS plugin can validate both the AD password and a second factor, it can be configured as the primary authentication provider.

  • Password Authentication as Additional Authentication: You can optionally adjust the default authentication flow from "surname + password followed by OTP" to "username + OTP followed by password." In this setup, the second factor is the AD password. This configuration is useful for mitigating the risk of AD account lockout due to brute-force attacks on passwords associated with leaked usernames.

ADFS OpenOTP Plugin as Primary Authentication Method

To configure the ADFS OpenOTP plugin as the primary authentication method, open the ADFS Management console, expand the Service folder, and click on Authentication Methods. Then, configure ADFS Authentication Methods > Primary Authentication Methods > Edit and enable the setting Allow additional authentication provider as primary.

adfs

Click Ok button and edit again Primary Authentication Methods. As ADFS OpenOTP plugin is already installed, you should now see RCDevs OpenOTP Authentication Provider available.

adfs
Enable it for access you want to protect with OpenOTP:
adfs

You can now try to perform a login with PasswordLess authentication.

The following screenshots are coming from another instance of ADFS. Don't take into account the ADFS URL and UPN value use for that login example

adfs

Click Next button:

adfs

Click Continue button and OpenOTP plugin will call OpenOTP server for authentication:

adfs

Provide the OTP and you are logged in.

LDAP Password as Additional Authentication Method

To configure LDAP password as second factor, open the ADFS Management console, expand Service folder and click on Authentication methods, configure ADFS Authentications Methods > Additional Authentication Methods > Edit and enable the setting Forms Authentication:

adfs

Apply the configuration.

Now, all policies requiring additional factor or MFA will ask for User LDAP password as 2nd factor.

After OpenOTP success login, I'm now prompted for the LDAP password of my account:

adfs

I provide my password and then I'm connected:

adfs

Voice Biometric Authentication through Web Browser

In order to use Voice authentication with ADFS and to provide your VOICE password through the microphone of your computer/laptop and your Web browser, ADFS needs to support some additional HTTP headers (worker-src).
By default, we advise to configure the following through PowerShell:

Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" -SetHeaderValue "default-src 'self' 'unsafe-inline' 'unsafe-eval'; img-src 'self' data:; worker-src blob:"

You may have a custom ADFS configuration where the HTTP headers values configured are different from the ones previously described.
The important part is regarding 'worker-src blob:' which must be added to your existing configuration.

Set-AdfsResponseHeaders -SetHeaderName "Content-Security-Policy" -SetHeaderValue "EXISTING CONFIG"; worker-src blob:"

After enabling it, you can use VOICE authentication through ADFS. You will be prompted for VOICE password as below:

adfs

Click on Record button, the microphone is triggered and then provide your VOICE password, and you are logged in.

Uninstalling the OpenOTP Authentication Provider

If you ever decide to uninstall the provider, simply re-run the installer and choose Remove.

adfs

Troubleshooting

To pinpoint a problem in your ADFS for OpenOTP plugin setup, you can start with the Windows Event viewer: "Applications and Services Logs", enter in "AD FS" folder and then "Admin" logs.
Also look at /opt/webadm/logs/webadm.log.

If the provider registration failed, you can manually register OpenOTP Authentication provider by executing the following command through PowerShell. You may need to adjust the version number and the PublicKeyToken of OpenOTP plugin for ADFS.

The command for the registration looks like:

Register-AdfsAuthenticationProvider -TypeName "AuthenticationProvider.AuthenticationAdapter, OpenOTPAuthenticationProvider, version=x.x.x.x, culture=neutral, publicKeyToken=xxxxxxxxxxxxx, processorArchitecture=AMD64" -Name "OpenOTPAuthenticationProvider"

In order to figure out the values for PublicKeyToken and version, you can execute the following command:

([system.reflection.assembly]::loadfile("C:\Windows\Microsoft.NET\assembly\GAC_64\OpenOTPAuthenticationProvider\v4.0_1.0.12.0__b04a046270ba95d2\OpenOTPAuthenticationProvider.dll")).FullName

Which return:

OpenOTPAuthenticationProvider, Version=1.0.12.0, Culture=neutral, PublicKeyToken=b04a046270ba95d2

The name folder containing the OpenOTPAuthenticationProvider.dll may change according to the version of the ADFS plugin. Please adapt the path if required. The path below is for 1.0.12.0 version of ADFS plugin.

The registration command is then:

Register-AdfsAuthenticationProvider -TypeName "AuthenticationProvider.AuthenticationAdapter, OpenOTPAuthenticationProvider, version=1.0.12.0, culture=neutral, publicKeyToken=b04a046270ba95d2, processorArchitecture=AMD64" -Name "OpenOTPAuthenticationProvider"