Okta MFA for Active Directory Federation Services (ADFS)

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 application, 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. Skip the Assign to People page for now, you'll return to this after making a few application modifications.

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. The Okta ADFS Plugin is available at https://okta.oktapreview.com/static/adfs/OktaADFSAdapter-1.5.9.zip. Select the link to download the file, unzip the archive, and run setup.exe.

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

2. Click Next to start the installation.

   

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

   

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

   

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

   

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

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

   

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

   

9. 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.
   Note: Ensure that the redirectURI parameter is set correctly.
   
   

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.

During the Early AccessEarly Access (EA) features are opt-in features that you can try out in your org by asking Okta Support to enable them. Additionally, the Features page in the Okta Admin Console (Settings > Features) allows Super Admins to enable and disable some EA features themselves. (EA) phase of this deployment an administrator will be required to follow these additional steps during the installation to have a successful installation of the adapter in a Federation Server Farm environment.

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.

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 a local database farm (WID) and If 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.