MFA for Active Directory Federation Services (ADFS)

The following MFA Factors are supported:

• Okta Verify (Push and TOTP)
• Voice Call
• Security Question
• Google Authenticator
• Duo
• Symantec VIP
• YubiKey
• Email
• On-PremMFA (RSA)
• SMS Authentication
• Custom TOTP Authentication

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.

1. Login to your Okta orgThe Okta container that represents a real-world organization..
2. Navigate to Security > Multifactor.
3. Select the Factor Types tab, then select the factors you want to enable in your org.
4. 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).

   

   

1. Login into your Okta org as an administrator.
2. Navigate to Applications > Applications, then click Add Application.

   

3. Search for the Microsoft ADFS (MFA) application, and then click Add.

   

4. On the General tab for the Microsoft ADFS appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in., specify an Application Label relevant to your organization, then click Next.

5. 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/.

6. Select the Sign on tab of the newly created Microsoft ADFS application and confirm that the sign-on mode is OpenID Connect.

   

Note

For more information about CORS, see CORS Overview.

1. Login to your Okta org.
2. Navigate to Security > API.
3. Select the Trusted Origins tab, then click CORS.

   

4. Select Add Origin.
5. Enter the following information:

   • Name

   • Origin URL: This can be your ADFS service name.

   • Check the box for CORS Type, then click Save.

   

1. Return to, or login to your Okta org.

2. Navigate to Settings > Downloads.

3. Scroll to the MFA Plugins and Agents section.

4. Click the Download Latest button to download the Okta MFA provider for ADFS agentA software agent is a lightweight program that runs as a service outside of Okta. It is typically installed behind a firewall and allows Okta to tunnel communication between an on-premises service and Okta's cloud service. Okta employs several agent types: Active Directory, LDAP, RADIUS, RSA, Active Directory Password Sync, and IWA. For example, users can install multiple Active Directory agents to ensure that the integration is robust and highly available across geographic locations.,

   

   Note: The version history describes all version of this plugin.

5. Unzip the archive, and run setup.exe as administrator.
6. Click Next to start the installation.

   

7. Log back into your Okta org, then navigate to the Microsoft ADFS (MFA) application application you created earlier (Part 2).

   

8. Select the General tab and locate the values for ClientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. ID and Client secret.

   

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

   

10. (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.

11. Specify the drive and folder where you want to install the Okta MFA Adapter.

    

12. You will be notified that the install for the ADFS Plugin has completed. Click Close.

    

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

1. Log onto your ADFS server.
2. Open the ADFS management console.

   

3. Expand Service - Authentication Methods.
4. Right-click on Authentication Methods.
5. Click Edit Multi-factor Authentication Methods....

   

6. Select Okta MFA Provider, then click OK.

   

7. Select Access Control Policies.

   

8. Select Add Access Control Policy.

   

9. Enter a Name and Description, then click Add.

   

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

    

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.

1. In the ADFS management console, go to Relying Party Trusts.
2. Right-click on the application, then select Edit Access Control Policy.

   

3. In the Settings section, click Edit. Choose the Application username format that you want to assign to users that will require this application.
4. Select the policy you created in the previous step, then click OK.

   

   

1. Log into your Okta org.
2. Navigate to Applications, then select the Microsoft ADFS (MFA) application you created earlier.
3. Select the Assignments tab, then select the individual users or groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with 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.

4. When you are finished with the application assignments, click Done.

   

   

1. Login to the test device to verify the Okta MFA prompt for ADFS login.
2. Navigate directly to your ADFS login page (Id- initiated login), or login directly to an application that has been configured for SSOAn acronym for single sign-on. In a SSO system, a user logs in once to the system and can access multiple systems without being prompted to sign in for each one. Okta is a cloud-based SSO platform that allows users to enter one name and password to access multiple applications. Users can access all of their web applications, both behind the firewall and in the cloud, with a single sign in. Okta provides a seamless experience across PCs, laptops, tablets, and smartphones. via ADFS (Service Provider-initiated login).
3. 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

To enable an existing application to use OpenID Connect:

1. Navigate to your ADFS application and select the Sign On tab.
2. 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/.

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

   

4. After the upgrade completes, ensure that your application still functions normally.
5. 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.
   
6. 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
   						

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

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

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

Procedure

1. If installing on servers in a WID based ADFS farm identify the current primary server, start the sequence from there.
2. Perform the installation as described in Part 4 of the Setup Instructions above.
3. Retrieve and copy the protected string values from each server.
4. Combine the values in a modified configuration file.
5. Replace the configuration file with the modified version on the last server.
6. Manually re-register the ADFS Authentication Provider.

Detailed Procedure

1. If using alocal 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

2. Perform the installation as described above on the first server.
3. 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.

4. 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/.

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

6. 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"

1. If you see this message when logging into ADFS, ensure you have enabled CORS in your Okta org (Part 3 in the setup guide).

   

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

   

To uninstall Okta MFA for ADFS

Remove access control policy from ADFS

1. In the ADFS management console navigate to Relying Party Trusts.
2. Right-click on the application.
3. Select Edit Access Control Policy.
4. Select previously added access control policy and remove.

Disable Okta MFA Provider for ADFS

1. Log onto your ADFS server.
2. Open the ADFS management console.
3. Expand Service - Authentication Methods.
4. Right-click Authentication Methods.
5. Click Edit Multi-factor Authentication Methods.
6. Deselect Okta MFA Provider.
7. Select Access Control Policies.
8. Select Prompt for Okta MFA.
9. Delete.
10. Click OK.

Uninstall the Okta ADFS Plugin

1. Click the Windows icon in the lower left cover of the Windows screen.
2. Choose uninstall.
3. Select the Okta MFA Provider.
4. Right click and choose uninstall.

Delete all assignments

Note: This step is optional and can be completed after other steps.

To delete all group and user assignment in your Okta org:

1. Login or return to your Okta org as an administrator.
2. Navigate to Applications,
3. Select the Microsoft ADFS (MFA) application.
4. Select the Assignments tab.
5. Delete all assignments.

Disable Cross-Origin Resource Sharing in your Okta Org

1. Login or return to your Okta org as an administrator.
2. Select Security > API.
3. Select the Trusted Origins tab.
4. Click CORS.
5. Select your origin.
6. Right click and choose Remove.
7. Click Save.

Remove the Microsoft ADFS Application in your Okta org

1. Login or return to your Okta org as an administrator.
2. Navigate to Applications > Applications.
3. Select STATUS Active.
4. For the Microsoft ADFS (MFA) application choose the gear icon and select deactivate.
5. Optional:
   1. Select STATUS INACTIVE
   2. For the Microsoft ADFS application choose the gear icon and select Delete.
   3. Confirm the deletion.