MFA for Active Directory Federation Services (ADFS)

Supported Factors

The following MFA Factors are supported:

Part 1 – Pre-configuration: Configure MFA Factor Enrollment in Okta

Before beginning the installation, be sure the MFA Factors to use with ADFS are configured in Okta.

Note

You can skip this step if you have already configured factor enrollment.

Login to your Okta org.
Navigate to Security > Multifactor.
Select the Factor Types tab, then select the factors you want to enable in your org.
Select the Factor Enrollment tab and set up a policy to prompt for MFA (this can be scoped to users who will need to provide MFA for ADFS logins).

Part 2 – Create the Microsoft ADFS (MFA) application in Okta

Login into your Okta org as an administrator.
Navigate to Applications > Applications, then click Add Application.
Search for the Microsoft ADFS (MFA) application, and then click Add.
On the General tab for the Microsoft ADFS app, specify an Application Label relevant to your organization, then click Next.
On the Sign-On options page, ensure the OpenID Connect is selected and enter an appropriate Redirect URI, then click Done.

Important

Ensure that the Redirect URI ends with a training forward slash. For example https://yourdomain.com/.
Select the Sign on tab of the newly created Microsoft ADFS application and confirm that the sign-on mode is OpenID Connect.

Part 3 – Enable Cross-Origin Resource Sharing (CORS) in your Okta org

Note

For more information about CORS, see CORS Overview.

Login to your Okta org.
Navigate to Security > API.
Select the Trusted Origins tab, then click CORS.
Select Add Origin.
Enter the following information:
- Name
- Origin URL: This can be your ADFS service name.
- Check the box for CORS Type, then click Save.

Part 4 – Install the Okta ADFS Plugin on your ADFS Server

Return to, or login to your Okta org.
Navigate to Settings > Downloads.
Scroll to the MFA Plugins and Agents section.
Click the Download Latest button to download the Okta MFA provider for ADFS agent,

Note: The version history describes all version of this plugin.
Unzip the archive, and run setup.exe as administrator.
Click Next to start the installation.
Log back into your Okta org, then navigate to the Microsoft ADFS (MFA) application application you created earlier (Part 2).
Select the General tab and locate the values for Client ID and Client secret.
The Okta ADFS Adapter install will prompt you for values for ClientId, ClientSecret, and Okta URL (this is your org name with the https prefix). For example:
- ClientId: 90aSt67bHgyW9bv
- ClientSecret: 80hglw7bw46hNoTpbnAyqzihouyzia
- OktaURL: https://atkodemoorg.oktapreview.com
(Optional) Elect to register the Okta ADFS Adapter

To register, select the box shown below.

If you are installing in a Federation Server Farm,do not check Register Okta ADFS Adapter. Refer to the manual registration procedure detailed in the Farm Installation Addendum.
Specify the drive and folder where you want to install the Okta MFA Adapter.
You will be notified that the install for the ADFS Plugin has completed. Click Close.
If you are installing in a Federation Server Farm,do not check Register Okta ADFS Adapter. Refer to the manual registration procedure detailed in the Farm Installation Addendum.

Part 5 – Enable the Okta MFA Provider in ADFS

Log onto your ADFS server.
Open the ADFS management console.
Windows Server 2012
1. Right click Authentication Policies and select Edit Multi-factor Authentication Methods....
2. Select the Multi-factor tab.
3. In the Select additional authentication factors section, check Okta MFA provider.
  And then click OK.
Windows Server 2016
1. Expand Service > Authentication Methods.
2. Right-click on Authentication Methods.
3. Click Edit Multi-factor Authentication Methods....
4. Select Okta MFA Provider, then click OK.
Select Access Control Policies..
Select Add Access Control Policy.
Enter a Name and Description, then click Add.
In the Rule Editor, configure a policy as required for your organization. Ensure that you include the and require multifactor authentication option in your rule editor. Click OK.

Part 6 – Add the Access Control Policy to a Relying Party Application

The following instructions are for ADFS 4. Instructions for ADFS 3 are available from Microsoft at Access Control Policies in Windows Server 2012 R2 and Windows Server 2012 AD FS.

In the ADFS management console, go to Relying Party Trusts.
Right-click on the application, then select Edit Access Control Policy.
In the Settings section, click Edit. Choose the Application username format that you want to assign to users that will require this application.
Select the policy you created in the previous step, then click OK.

Part 7 – Assign the Microsoft ADFS (MFA) Application in Okta

Log into your Okta org.
Navigate to Applications, then select the Microsoft ADFS (MFA) application you created earlier.
Select the Assignments tab, then select the individual users or groups to whom this application will be assigned.
Ensure that the username assigned in the application matches the username that users will use for their ADFS initiated logins.
When you are finished with the application assignments, click Done.

Part 8 – Verify the Okta MFA prompt when logging into ADFS

Login to the test device to verify the Okta MFA prompt for ADFS login.
Navigate directly to your ADFS login page (Id- initiated login), or login directly to an application that has been configured for SSO via ADFS (Service Provider-initiated login).
After entering your credentials, you will either be redirected to your ADFS login page, or be prompted for Okta MFA if you started with IdP-initiated login.
The example below shows service provider initiated login via Office 365:
IdP Discovery at Office 365
Username/Password at ADFS
MFA by Okta embedded in ADFS

Enable Open ID Connect with existing ADFS installations

To enable an existing application to use OpenID Connect:

Navigate to your ADFS application and select the Sign On tab.
Select OpenID Connect.
Ensure that the redirectURI parameter is set correctly.
Important
Ensure that the Redirect URI ends with a training forward slash. For example https://yourdomain.com/.
Upgrade any existing ADFS plug-ins to version 1.7.0 or later
Note: Be sure to remove the Okta MFA Provider from the Authentication Policy in ADFS before running any plug-in upgrades.
After the upgrade completes, ensure that your application still functions normally.
Using a text editor, open the okta_adfs_adapter.json file and modify it to set "useOIDC":true.
Note: By default the okta_adfs_adapter.json file can be found in c:\Program Files\Okta\Okta MFA Provider\config\okta_adfs_adapter.json.

Using a text editor copy and create the following Microsoft Powershell script and save as ApplyConfigurationSettingChanges.ps1.

# ApplyConfigurationSettingChanges.ps1
[System.Reflection.Assembly]::Load("System.EnterpriseServices, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")

$BinDir = "C:\Program Files\Okta\Okta MFA Provider\bin"
$ConfigDir = "C:\Program Files\Okta\Okta MFA Provider\config"

Start-Service adfssrv

# Remove Okta MFA Provider
$providers = (Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
$providers.Remove("OktaMfaAdfs") 
Set-AdfsGlobalAuthenticationPolicy -AdditionalAuthenticationProvider $providers

# Unregister 
Unregister-AdfsAuthenticationProvider -Name "OktaMfaAdfs" -Confirm:$false -ErrorAction Stop

# restart the ADFS service
Restart-Service adfssrv -Force

# register MFA adapter again
$OktaMfaAssamply = [Reflection.Assembly]::Loadfile($BinDir + "\OktaMfaAdfs.dll")
$typeName = "OktaMfaAdfs.AuthenticationAdapter, OktaMfaAdfs, Version=" + $OktaMfaAssamply.GetName().Version + ", Culture=neutral, PublicKeyToken=3c924b535afa849b"
Register-AdfsAuthenticationProvider -TypeName $typeName -Name "OktaMfaAdfs" -Verbose -ConfigurationFilePath "$ConfigDir\okta_adfs_adapter.json"

# restart the service
Restart-Service adfssrv -Force

# Enable Okta MFA adapter
$providers = (Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
$providers.Add("OktaMfaAdfs") 
Set-AdfsGlobalAuthenticationPolicy -AdditionalAuthenticationProvider $providers

If required change the values of the BinDir and ConfigDir variables to match your environment.
As administrator open a Microsoft PowerShell and execute the script ApplyConfigurationSettingChanges.ps1.
Verify that the user can authenticate.

You have successfully upgraded your application plug in to use OpenID Connect.

Farm Installation Addendum

In a Federation Server Farm environment, Administrator are required to follow these additional installation steps to ensure successful installation of the adapter.

Background

The installer stores the Client Secret as a protected string. That protected string is generated using a machine specific key.

When ADFS is setup in a server farm, the configuration file is replicated among farm member servers. As a result the final configuration file will contain a single client secret that can only be decrypted by one server; the last server on which the installation was completed.

If the ADFS server farm is using the WID database and not a SQL database you will also need to promote each server to be the primary server during the installation. For this reason we recommend starting the installation on the current primary server, if you start on the primary server and follow the sequence as described below you will complete the installation on the original primary server returning it to its primary state. Identify the current primary server with the powershell command Get-AdfsFarmInformation.

Note

If the ADFS server farm is using the WID database and not a SQL database you will also need to promote each server to be the primary server during the installation. We recommend starting the installation on the current primary server, if you start on the primary server and follow the sequence as described below you will complete the installation on the original primary server returning it to its primary state. Identify the current primary server with the powershell command Get-AdfsFarmInformation

Detailed Procedure

If using a local database farm (WID) and the current computer is NOT the primary server in the farm promote it to primary by executing this command on server:
Set-AdfsSyncProperties -Role PrimaryComputer
Perform the installation as described above on the first server.
Open the okta_adfs_adapter.json file (%ProgramFiles%\Okta\Okta MFA Provider\config) with a text editor such as Notepad:
1. Copy the client secret value (truncated secret shown)
2. Paste the value in a separate file
3. Repeat Step 2 on the remaining servers in the environment
4. Proceed to Step 4 when you’ve completed the preceding steps on all of the servers in the farm.
Combine the values in a modified configuration file:
1. From the original primary server
2. Promote the server back to primary:
  Set-AdfsSyncProperties -Role PrimaryComputer
3. Open the okta_adfs_adapter.json file:
  If UAC is on make sure your editor is running as administrator
4. Copy/Paste the entire contents of your seperate file that contains the protected secrets from the other servers.
5. Shown below are the four protected strings from my servers and the full configuration file from the first (and now primary) server in one file.
6. Arrange the list of protected strings into a json array (note the last element in the array does not end with a comma).
7. Replace the clientSecret string value of your complete configuration file with the array you just created.
8. Note: Indentation and new line formatting is optional
9. Optional: Use a json lint tool to validate the json is well formed. Online versions are available, use at your own discretion. For example: https://jsonlint.com/.
Replace the configuration file with the modified version on the last server:
- Replace the okta_adfs_adapter.json file on the last server with the newly created config file.
- Note: you may need to run notepad as a administrator
Manually re-register the Adfs Authentication Provider:
- Sample Script:
  $a=[System.Reflection.Assembly]::LoadFile("C:\Program Files\Okta\Okta MFA Provider\bin\OktaMfaAdfs.dll")
  $file=[String]::Format("OktaMfaAdfs.AuthenticationAdapter, {0}", $a.GetName().FullName)
  Unregister-AdfsAuthenticationProvider -Name "OktaMfaAdfs"
  Register-AdfsAuthenticationProvider -Name "OktaMfaAdfs" -TypeName $file -ConfigurationFilePath "C:\Program Files\Okta\Okta MFA Provider\config\okta_adfs_adapter.json"

Troubleshooting

Incorrect CORS installation
If you see this message when logging into ADFS, ensure you have enabled CORS in your Okta org (Part 3 in the setup guide).
Incorrect Farm installation
During installation you encounter an error 1001 PS0033 “cmdlet cannot be executed from a secondary server in a local database farm.
If you encounter this error closely follow the instructions in the Farm Installation addendum, especially the steps that discuss WID (windows internal database) and promoting each server to be primary.
incompatible proxy
During login, after MFA, users received an "unable to connect" message.
The ADFS plugin can use a proxy to interact with Okta. By default the the ADFS agent uses the WinHTTP proxy.
Some customers may be using the IE proxy.

To ensure that the ADFS plugin is using the correct proxy:
1. Open a command prompt window.
2. Execute the netsh winhttp show proxy command.
3. Examine the result of the command which will be one of: no proxy, winhttp or ie.
4. For customers using IE, specify IE as proxy source using a command similar to:
  netsh winhttp import proxy source=ie
5. Also ensure that the https://<yourorg>.okta<preview>.com is not blocked by company firewalls.

Un-install Okta MFA for ADFS

To uninstall Okta MFA for ADFS

IdP Discovery at Office 365
Username/Password at ADFS
MFA by Okta embedded in ADFS