ADFS & OpenOTP
  Download PDF

Simple Login

Push Login

1. Product Documentation

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 the RCDevs WebADM Administrator Guide available through the RCDevs’ online documentation library.

2. Product Overview

The OpenOTP Authentication Provider for AD FS is a component that integrates the RCDevs OpenOTP one-time password authentication into an Active Directory Federation Services server, adding OpenOTP authentication as a possible MFA option in the AD FS Management tool. RCDevs OpenOTP Authentication Server is a WebApp that is tightly coupled to the RCDevs WebADM application server. The Authentication Provider enables you to use all types of authentication tokens and authentication standards supported by the OpenOTP authentication module. That includes OATH/HOTP, OATH/TOTP, OATH/OCRA, Mobile-OTP, YubiKey, SMSOTP, MailOTP. Software tokens are provided by various publishers and for a variety of platforms including Android and iOS.

3. 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.

4. Preliminary Information

Administrative/elevated permissions are necessary on any server to correctly set up and/or change the OpenOTP Authentication Provider’s configuration. To correctly setup 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).

Note

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.

5. Installation and Configuration

5.1 Installation

In this post, we will assume an existing ADFS infrastructure installed and available. This post will not cover how to setup ADFS. Please refer to the Microsoft documentation and/or the TechNet blog for details about how to install and configure ADFS Microsoft Documentation. For this recipe, you will need to have WebADM/OpenOTP installed and configured. Please, refer to WebADM Installation Guide and WebADM Manual to do it.

Note

Before running the MSI file, please make sure your ADFS services is running.

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

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

Note

MSI file should be run with domain admin rights. To be sure that you have the good permissions, you can execute the MSI file through PowerShell in “Run As Administrator” mode.





Accept End-User License Agreement and click on Next. On the next page, choose your default folder location and click on Next.

On this page, you have to configure one of your WebADM servers URL. If you are running a WebADM cluster, then both OpenOTP URLs should be automatically retrieve in the Auto mode. If your OpenOTP URL(s) can not be automatically retrieve, then configure URL(s) manually like below :

Click Next. On the next page, every configuration is optional. If you’d like to use a client certificate for enhanced security, please use this next screen to provide the detail. Clicking on the information marks (i) will provide additional help during the installation procedure.

Next page allows you to configure failover with OpenOTP, SOAP request timeout and UPN Mode. Keep the default configuration if you are not sure of what you need. Click on Next and Install.

Here you may set up a custom settings string for your WebADM and OpenOTP configuration (This setting is deprecated since WebADM client policies). Furthermore, you may change the default SOAP service timeout. If two server URLs are defined in server URL, you can optionally configure a request routing policy (i.e. the server selection policy).  There are three policies available:

  • Ordered: The first server is always preferred. When it does not respond, the second server is used.
  • Balanced: The server is chosen randomly for each request. When it does not respond, the other is used.
  • Consistent: The server selection depends on the user ID. A request for one specific user is also always routed to the same server. If it does not respond, the other server is used. Click Next when you are done and afterwards Install.

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

Click Next to continu the setup.

Installation is near complete. At the end of the installation of ADFS plugin, you will have a message like below:

You need to provide the SID of your ADFS service account. On my side, the command will be:

C:\Users\administrateur>wmic useraccount where (name='administrator' and domain='RCDEVS') get sid
SID 
S-1-5-21-1866855866-3248828235-1037604996-500

In case you are using Managed Service Account, the above command will not give yout the SID and you might need to use Get-AdServiceAccount command instead. In this example the service account is “adfs”:

PS C:\Users\Administrator> Get-AdServiceAccount -Identity adfs
DistinguishedName : CN=adfs,CN=Managed Service Accounts,DC=test,DC=local
Enabled           : True
Name              : adfs
ObjectClass       : msDS-GroupManagedServiceAccount
ObjectGUID        : 7b122e5f-e920-49cc-b34d-f5c432b2539e
SamAccountName    : adfs_new$
SID               : S-1-5-21-391341617-2745208684-1719714213-1123
UserPrincipalName :

Important Note

The previous command should be executed through Windows Command Prompt and not with Powershell.

On the next screen, you have to register the OpenOTP service in your ADFS instance. The registration should be done only once per ADFS instance. Click on Yes if it’s the first time you install OpenOTP ADFS plugin. For the others, ADFS servers in the same instance, click on No. ADFS services should be running during the registration.

Note

After provider registration, ADFS services will be automatically restarted.



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

Plugin installation

Repeat this procedure on every ADFS servers!

6. ADFS Configuration for Multi-Factor Authentication

In this documentation, we enable OpenOTP Multi-Factor authentication on the default ADFS login page. This page is disabled by default. Have a look to Technet Microsoft to enable the default ADFS login page. With ADFS 4.0 on Windows Server 2019, the PasswordLess feature is now available. That involves you can login on ADFS by just providing the Username and the OTP. The username provided must match a valid account in the AD.

6.1 Configuration for ADFS 3.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.


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

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 and click on Ok.

Your ADFS server is now configured with OpenOTP. You can go on your ADFS login page:

Click on Sign in button, enter your credentials and click on Sign in.

On the next page, an OTP will be asked.

OTP Policy

Here, AD FS was configured so that OpenOTP is the only option for a secondary factor, and OpenOTP is configured to require an OTP sent by mail to the user only. Enter your secondary factor to complete the test.

OpenOTP User Activation

Your account should be activated for OpenOTP. Look the following How-To to activate an account: OpenOTP User Activation. A Token has to be enrolled on the user account before testing OTP authentication.

6.2 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.

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

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.

Multi-factor policies at the ADFS level will now contact RCDevs plugin for MFA authentication.

We will now create a Multi-Factor policy called OpenOTP. Right click on Access Control Policies under the ADFS management console and then click Add Access Control Policy.

Name your Access Control Policy, on my side OpenOTP and click on Add button to configure the policy. On my side, I will allow every user and require a multi-factor authentication.

This part is done, you can click on OK.

We will now configure a relying party trusts on the ADFS to apply our policy to the default ADFS login page (https://ADFS_INSTANCE_NAME/adfs/ls/idpinitiatedsignon)

Right click on Relying Party Trusts and click on Add Relying Party Trusts.

You are now in Relying Party Trusts Wizard. On the first page, select the option Claims aware and then click Start.

On the next screen, you have to select the data source. Choose the 3rd option to configure the data source manually and click Next.

On the next screen, name your Relying Party and click on Next:

The next configuration page is optional. If required configure it and click on Next.

On the next page, select Enable support for the SAML 2.0 WebSSO protocol and configure your URL according to your ADFS server and click on Next.

On the next screen, you have to configure your Identifier. Configure your Identifier, click Add and Next.

On the next configuration page, you have to choose an access control policy. I have previously created a policy called OpenOTP so I choose this one:

The configuration of the Relying Party Trust is now finished. Click on Next and Close.

Multi-Factor Authentication is now configured for the default ADFS login page. We will now perform an authentication.

Click on Login and the next page will prompt you the following:

Click on Continue button and the next page will ask you to enter your OTP:

Provide your OTP and you are logged on.

6.3 PasswordLess Configuration for ADFS 4.0

Windows Server 2019 brings some changes to ADFS. Two of these are especially interesting for use cases with OpenOTP:

  • External Authentication Providers as Primary authentication method : OpenOTP can now be used as the first authentication factor, allowing you to not expose AD password as the first factor. Furthermore, since OpenOTP ADFS plugin can validate both AD password and a 2nd factor, it can be configured as primary authentication provider.

  • Password Authentication as additional Authentication : You can optionnaly change the default authentication flow from sername + password followed by OTP, to username + OTP followed by password. In that scenario, the second factor is the AD password. This is especially useful for preventing the AD account from being locked due to a brute force attack on the password of a leaked username.

6.3.1 ADFS OpenOTP Plugin as Primary Authentication Method

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

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.

Enable it for access you want to protect with OpenOTP :

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

Click Next button :

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

Provide the OTP and your are logged in.

6.3.2 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 :

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 :

I provide my password and then I’m connected :

6.5 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 than 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 :

Click on Record button, the microphone is triggered and then provide your VOICE password and you are logged in. More information on VOICE authentication and registration are available on the following documentation

7. Uninstalling the OpenOTP Authentication Provider

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

8. Troubleshooting

To pinpoint a problem in your AD FS/OpenOTP setup, you can start with the Windows Event viewer: “Applications and Services Logs”, then “AD FS”, then the “Admin” log. Also look at /opt/webadm/logs/webadm.log, or the equivalent in the WebADM interface (under the “Database” section).

If the provider registration failed, you can manually register OpenOTP Authentication provider by executing the following command through powershell and adjusting the version number of OpenOTP_ADFS plugin :

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

9. Video Demonstration


Play Video on Youtube