Farm addendum

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

Topics:

Background

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

When ADFS is used in a server farm, the configuration file is replicated among farm member servers. The final configuration file contains a single client secret that only the last server on which the installation was performed can decrypt.

If the ADFS server farm uses the Windows Internal Database (WID), you need to promote each server to be the primary server during the installation. Okta recommends starting the installation on the current primary server. Complete the following procedures, starting with the primary server. The installation process finishes by installing the adapter on the original primary server, thus returning it to its primary state. You can identify the current primary server with the PowerShell command Get-AdfsFarmInformation

Process Overview

  1. If installing on servers in a WID-based ADFS farm, identify the current primary server and start the sequence from that server.
  2. Install the ADFS plugin. See Install the Okta ADFS Plugin on your ADFS Server.
  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 a local database farm (WID) and the current computer is not the primary server, 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:

    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 after you've completed the preceding steps on each server 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 enabled, run your editor as administrator.

    4. Copy/Paste the entire contents of your separate file that contains the protected secrets from the other servers.

    5. The following shows an example of four protected strings from farm 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:

    7. Replace the clientSecret string value of your complete configuration file with the json array of protected strings:

      Note: Indentation and new line formatting is optional
    8. Optional. Use a json lint tool to validate the json. Online versions are available that you can 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"