Enable OpenID Connect with existing Active Directory Federation Services apps

This topic describes how to enable OpenID Connect (OIDC) connections with existing Active Directory Federation Services (ADFS) apps and how to enable the Identity Engine authentication pipeline for OIDC-configured ADFS apps.

Enable OIDC connections with existing ADFS apps

Enable an existing app to use OIDC:
1. In the Admin Console, go to Applications > Applications.
2. Select an ADFS app.
3. Select the Sign On tab.
4. In the Settings section, click Edit.
5. Select OpenID Connect.
6. Enter the Client ID and the Client secret.
7. In the Redirect URI field, enter your redirect URI. Use a forward slash at the end of the URI, like https://yourdomain.com/.
8. Click Save.
Open the ADFS Global Authentication Policy for editing and then select the Multi-factor tab.
Clear the Okta MFA Provider checkbox and then click OK before proceeding to the next step.
Upgrade any existing ADFS plugins to version 1.7.0 or later.
After the upgrade has finished, verify that your app functions normally.
1. Open this file with a text editor:
  C:\Users\<adfs_service_account_name>\AppData\Local\Okta\Okta MFA Provider\config\okta_adfs_adapter.json.
  
  See MFA for Active Directory Federation Services (ADFS) Configuration.
2. Search for the useOIDC property and set its value to true.
3. Save your changes and close the text editor.

Using a text editor, copy and create the following Microsoft Powershell script and save as ApplyConfigurationSettingChanges.ps1. If required, change the values of the BinDir and ConfigDir variables to match your environment.

# 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

Open Microsoft PowerShell as an administrator and execute the script ApplyConfigurationSettingChanges.ps1.
Verify that the user can authenticate.

Enable the Identity Engine authentication pipeline for OIDC-configured ADFS apps

Early Access release. See Enable self-service features.

Okta Identity Engine is the authentication pipeline used by Okta orgs to support features like adaptive authentication policies and a wider range of authenticators. By default, ADFS apps that are configured with OIDC authenticate through Okta's classic authentication pipeline.

You can enable this feature to route authentication for those apps through the Identity Engine pipeline instead. See Authentication policies.

Note: This feature applies only to ADFS apps that are configured to use OIDC. It has no effect on ADFS apps that use MFA as a service.

Before you begin

Review your org's app sign-in policy, as the default ADFS app policy requires a possession factor. When Okta evaluates the policy, the ADFS password authentication is included as part of the policy. If some of your users don't have a possession-type authenticator enrolled, they could be blocked from signing in after you enable this feature.

Before you proceed, create a new app sign-in policy or decide which policy to use for the ADFS app, then enable the feature.

In the Admin Console, go to Settings > Features.
Find the feature Identity Engine in Active Directory Federation Service (ADFS) apps with OpenID Connect (OIDC) and enable it.
Assign the ADFS app to the newly created app sign-on policy or to the existing policy that you want to apply to the ADFS app.

After completing these steps, ADFS apps configured with OIDC authenticate through the Identity Engine pipeline.

Disable the feature

To revert to the classic authentication pipeline, disable the feature in the Admin Console, Settings > Features.

After you revert, the Identity Engine app sign-in policy assignment is ignored, and the app uses the classic app sign-on policy instead.