Configure the CyberArk Identity AD FS 4.0 MFA Plugin

The CyberArk MFA Plugin for AD FS 4.0 adds MFA as an Authentication Method to the Microsoft AD FS 4 Global Authentication Policy, enabling users to authenticate with AD FS and CyberArk MFA when the MFA authentication policy is applied.

The plugin supports MFA with AD FS 4 on Windows Server 2016.

Prerequisites

Step 1: Configure MFA on your CyberArk tenant.

Create an MFA authentication profile and apply it to your users via policy for users to authenticate with MFA using the plugin. Refer to Get started with Multi-factor Authentication for details.

The CyberArk MFA plugin for AD FS 4.0 supports the following mechanisms from the Challenge 1 column of an Authentication Profile:

  • Email

  • SMS

  • Phone call

  • Security question(s)

  • Mobile Authenticator

  • OATH OTP Client

  • 3rd Party Radius Authentication

Step 2: Download and extract the plugin.

If you have multiple AD federation servers in a farm, download and extract the plugin on each server.

  1. Log in to the Admin Portal and download the plugin zip file from the downloads tab.

  2. Extract the plugin zip file to a convenient location. The following files should be extracted:

    • DLL – Idaptive.Multifactor.Authentication.dll

    • Support Package – Newtonsoft.json.dll

    • Config File – IdaptiveConfig.json

Step 3: Update the config file.

If you have multiple AD federation servers in a farm, this procedure should be done on the primary federation server.

  1. Open IdaptiveConfig.json in any text file editor on your machine.

  2. Update the tenant value with your CyberArk tenant name.

  3. Save and close the file.

Step 4: Create the Event Log and Source.

  1. Open Windows Powershell.

  2. Type the following command to create the Event Log and Source for Microsoft Windows Event Viewer.

    New-EventLog -LogName "Idaptive" -Source "Idaptive MFA Plugin"
    

Step 5: Prepare the AD FS system(s).

Preparing the AD FS system(s) involves moving the Global Assembly Cache (GAC) tool to the same directory where you extracted the CyberArk MFA AD FS plugin.

  1. Locate gacutil.exe.

    For example: %homedrive%\Program Files (x86)\Microsoft SDKs\Windows\v8.0A\bin\NETFX 4.0 Tools\

  2. Copy the x64 folder containing gacutil.exe, as well as the 1033, en-US (optional), and the other localized resource folder below the NETFX 4.0 Tools location, to a convenient location.

    For example, C:\Idaptive\.

  3. Copy the CyberArk plugin files extracted in Download and extract the plugin.to the same folder location as gacutil.exe i.e. x64 folder (For example, C:\ Idaptive).

The Relying Party Trust should be added to apply Access Control Policy.

Configuration

Step 1: Add the assembly files to the GAC.

Perform the following steps for each AD FS federation server in the farm to add the .dll files to the GAC.

  1. Open the Command Prompt.

  2. Move to the folder containing gacutil.exe:

    cd C:\Idaptive\x64\

  3. Add the relative package dll, before adding the Assembly file:

    .\gacutil.exe /if .\Newtonsoft.Json.dll

  4. Add the Assembly file dll , for example:

    .\gacutil.exe /if .\Idaptive.Multifactor.Authentication.dll

    To view the resulting entry in the GAC, type:

    .\gacutil.exe /l Idaptive.Multifactor.Authentication

    The following output should be visible in the resulting entry in the GAC :

    Microsoft (R) .NET Global Assembly Cache Utility.  Version 4.0.30319.0
    Copyright (c) Microsoft Corporation.  All rights reserved.
    The Global Assembly Cache contains the following assemblies:
    Idaptive.Multifactor.Authentication, Version=1.0.0.0, Culture=neutral, PublicKeyToken=74058d6158a2092a, processorArchitecture=MSIL
    Number of items = 1

Step 2: Register Idaptive as an authentication provider in AD FS.

Open a Windows PowerShell command window on your AD FS server and enter the following commands to register Idaptive as an authentication provider in AD FS.

PS C:\>$typeName = "Idaptive.Multifactor.Authentication.IdaptiveAdapter, Idaptive.Multifactor.Authentication, Version=1.0.0.0, Culture=neutral, PublicKeyToken=74058d6158a2092a, processorArchitecture=MSIL”
PS C:\>Register-AdfsAuthenticationProvider -TypeName $typeName -Name “Idaptive Multifactor Authentication” -ConfigurationFilePath "C:\Idaptive\x64\IdaptiveConfig.json"
PS C:\>net stop adfssrv
PS C:\>net start adfssrv
If you are using a federation server farm that uses Windows Internal Database, you must execute these commands on the primary federation server in the farm.

If you have the device registration service enabled in your AD FS environment, also execute the following (optional):

PS C:\>net start drs

To verify the registered provider, use the following command:

PS C:\>Get-AdfsAuthenticationProvider

This shows your provider as one of the providers in the system.

Step 3: Create the AD FS authentication policy that invokes the Idaptive MFA adapter.

  1. Open the AD FS Management snap-in (from the Server Manager Tools menu).

  2. Click Authentication Methods.

  3. In the center pane, under Multi-Factor Authentication, click the Edit link.

  4. Under Select additional authentication methods at the top of the page, check the box for Idaptive Multifactor Authentication, then click Apply.

  5. Check the results using the following commands:

    • Get-AdfsGlobalAuthenticationPolicy.

      You should see Idaptive as one of the Additional Authentication Provider values.

    • Get-AdfsAdditionalAuthenticationRule.

      You should see the rules for Extranet and Intranet configured as a result of your policy selection in the administrator UI.

      If you can not find any output, run following command in PowerShell:

      Set-AdfsAdditionalAuthenticationRule -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "true"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );'

Step 4: Add Access Control Policies to authenticate using the MFA Plugin.

To apply access control policies to relying party trust, first set the ADFSAdditionalAuthenticationRule of ADFS to null.

Perform the following steps to test the Idaptive MFA Adapter. Make sure all the prerequisites are completed and the MFA plugin is configured.

  1. Open ADFS management Console, and click Access Control Policies.

  2. Right-click Access Control Policies and then select Add Access Control Policy.

  3. Click Add to open the Rule Editor Window.

  4. Click from specific groups.

  5. Click Security groups radio button from the Select groups window.

  6. Enter the group you want to permit for authentication, then click Check Names.

    This checks if the User Group is present in the directory or not. If it is present, the group is added. Click OK.

  7. Select and require multifactor authentication then click OK.

  8. Make sure the Access Control Policy is added successfully and then click OK.

Step 5: Authenticate with MFA using the Idaptive adapter.

Perform the following steps to test the Idaptive MFA adapter:

  1. In the AD FS snap-in > Authentication Methods > Primary Authentication Methods, click Edit. (You can also click the Primary tab from the Multi-factor policy UI.)

  2. Ensure Forms Authentication is the only option checked for both the Extranet and the Intranet authentication method, then click Apply and OK.

  3. Open the IDP initiated sign-on html page, (https://<fqdn>/adfs/ls/idpinitiatedsignon.htm) and sign in with valid AD user credentials in your test environment.

  4. Enter credentials for primary authentication.

    You should see the MFA forms page with challenge questions. The following challenges from the Challenge 1 column of an Authentication Profile are supported:

    • Email

    • SMS

    • Security question(s)

    • Phone call

      If you have more than one adapter configured, you will see an MFA choice page.

Clear the AD FS policy

Follow this procedure if you want to remove the CyberArk MFA Plugin. For example, if you want to update the plugin, you must first remove the existing one.

Step 1: Clear all MFA-related checkboxes in Edit Authentication Methods, then click OK and then Apply.

Step 2: Unregister Idaptive as an MFA provider.

PS C:\> Unregister-AdfsAuthenticationProvider –Name “Idaptive Multifactor Authentication”
PS C:\>net stop adfssrv
PS C:\>net start adfssrv

Step 3: Remove the assembly from the GAC.

  1. Open Command Prompt.

  2. Move to the folder containing gacutil.exe:

    cd C:\Idaptive\x64\

  3. Use the following command to find the fully qualified strong name of the entry:

    .\gacutil.exe /l Idaptive.Multifactor.Authentication

  4. Then use the following command to remove it from the GAC:

    You may also use the following short command to remove assembly from GAC :

    .\gacutil.exe /u Idaptive.Multifactor.Authentication

For additional details about deploying authentication adapters to AD FS, see https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/development/ad-fs-build-custom-auth-method?redirectedfrom=MSDN.