Configuring the On-Prem MFA Agent Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Configuring the On-Prem MFA Agent
Published: Jan 31, 2018   -   Updated: Jun 22, 2018




Okta Windows Credential Provider

The Okta Windows Credential Provider prompts users for MFA when signing in to supported Windows servers with an RDP client. It supports all Okta-supported MFA factors except Windows Hello and U2F tokens.

This article contains the steps to install the Okta credential provider for Windows. The following four items are also required:

  • The server must not be behind a proxy.
  • Use of a supported Windows server, specifically 2016 Windows Server, Windows Server 2012, Windows Server 2012 R2, Windows Server 2008, and Windows Server 2008 R2.
  • The Windows server on which the Okta credential provider is installed must have an active internet connection with port 443 open.
  • The installing account must have administrative rights to install the OKTA Windows Credential Provider Agent, Visual C++ Redistributable and .NET 4.0+.
  • End users must have enrolled their MFA tokens previously, by choosing an MFA option for their account when signing in to Okta the first time or after a reset. End user cannot enroll a token during an RDP sign in. End users with unenrolled tokens receive an authentication failed response from Okta when attempting to sign into an RDP server.
  • For information on enabling TLS 1.2 in .NET and in Microsoft Internet Explorer browsers, see Okta ends browser support for TLS 1.1.

Installation Overview

To install, begin in Okta and verify or set up policies. Then, install the agent on the Windows server, return to Okta to create an app and assign users, and finally, test the setup. The installation contains three major installation steps and one testing step. Be sure to complete the testing after the installation.

Step 1 – Configure Okta

Before installing the Okta credential provider for Windows, your org must have the following three items configured.

  1. Configured MFA factors that include the factor to use for RDP sign in. For instructions, see MFA.htm.
  2. A group for the end users who will authenticate RDP sign ins. For instructions, see Group Types Used in Okta.
  3. Add the Microsoft RDP app

    On the Applications page, select Add Application and enter Microsoft RDP (MFA) in the search box. Then, add the application. On the General tab, assign any desired application label. You can assign people to the app now or later, as described in step 3, below.

Step 2 – Install the Okta Windows Credential Provider Agent on a Windows server

Org admins can download the OKTA Windows Credential Provider Agent at https://<your-org-name> , where <your-org-name> is your Okta domain. After obtaining the file, complete the following four steps. During the installation process, keep Okta open in another window on the Microsoft RDP (MFA) application screen. You can perform a standard installation or a silent installation.

Standard installation
  1. On the Windows server, extract the files from the .zip archive and run Setup.exe. Follow the prompts to complete the installation.

    Note: The package contains the C++ installer. The installer prompts your to install it if it is not present, or to repair it, if it is present. Then, the installer prompts for the Visual C++ 14 Runtime Libraries, as shown below. Screenshot


  2. During the installation, the App Configuration screen displays, requesting a client ID, a client secret, and an Okta URL, as shown below. Screenshot


    To obtain this information, return to the Microsoft RDP (MFA) app in Okta. On the General tab, scroll down to the Client Credentials section to see the values for the client ID and the client secret. The Okta URL is the URL your org uses to reach Okta in the format https://<yourorg>

    Enter this information in the App Configuration screen, shown above. Then, click Next and Close to complete the installation.

  3. To verify the installation, lock the machine. In the sign-in screen that appears, verify that the Okta icon appears as a sign-in option, as shown below on a Windows Server 2012 R2. The screen is slightly different in Windows Server 2016. Screenshot


Silent installation
  1. Extract the files from the .zip archive.

  2. On the Windows server, run the following command from the vcredist_x64 folder of the unzipped archive.

    vcredist_x64.exe /install /quiet /norestart

  3. Run the following command to install Okta Windows Credential Provider silently.

    msiexec /qb /log log.txt /i OktaWindowsCredentialProvider.msi CLIENT_ID="cid" CLIENT_SECRET="cs" OKTA_URL="https://a.b.c"


    CLIENT_ID – find this value on the General tab of the Microsoft RDP (MFA) application in Okta.

    CLIENT_SECRET – find this value on the General tab of the Microsoft RDP (MFA) application in Okta.

    OKTA_URL – your full Okta org name, including https://.

  4. Modify additional properties

    In addition to the parameters you added in the previous step, modify the following properties to ensure MFA is always enforced.

    "WidgetTimeout" : 30
    "EnforceTimeoutVersionAgnostic": true
    "ErrorTimeOutInSeconds": 30,
    "SslPinningEnabled": true

    To modify these properties, use the following power shell script.

    $lib=[System.Reflection.Assembly]::LoadFile("C:\Program Files\Okta\Okta Windows Credential Provider\bin\Newtonsoft.Json.dll")
    $configStr=Get-Content -Path "C:\Program Files\Okta\Okta Windows Credential Provider\config\rdp_app_config.json"
    $t=New-Object -TypeName Newtonsoft.Json.Linq.JValue -ArgumentList true
    $config.Add("EnforceTimeoutVersionAgnostic", $t)
    $newConfig=[Newtonsoft.Json.JsonConvert]::SerializeObject($config, $format)
    Echo $newConfig > "C:\Program Files\Okta\Okta Windows Credential Provider\config\rdp_app_config.json"

    Note: You can run this script from the same location you ran the installation in step 2, above.

Step 3 – Assign users to the Microsoft RDP (MFA) app in Okta

If you have users that do not need to provide MFA to sign in to the server, assign them to the app, but exclude them from the app-based sign on policy for the Microsoft RDP (MFA) app. The App-SignOn Policy is the only policy that is relevant to the Microsoft RDP App.

  1. In the Microsoft RDP (MFA) app in Okta, select the Sign On tab. In the Settings section, select Edit and choose the Application username format to assign to users of this app. In the example below, AD SAM account name is chosen, but you can make any choice.Screenshot


    Important: When the end user signs in to the Windows server, the application user format must match exactly.

  2. Select the Assignments tab and assign the app to users or groups. After selecting Assign, enter the user name. For more information on assigning apps, see Assign Applications.

    Important: The user name entered here must match the format you selected in the preceding step. For example, in the case that the full UPN for a user is in the format, and you entered AD SAM account name for the username format above, enter only the name portion of the UPN for the user name. The portion of the UPN is included in the AD SAM account name.

  3. Select Done when finished. Your system is completely configured.

Testing – Verify MFA for RDP sessions

This verification process is the end-user sign in process.

  1. Sign in to a machine which has the RDP client installed. Be sure that this machine can connect to the server into which you want to make a remote connection.

  2. Enter the server name for the RDP client, your username, and password and then, click Connect.

  3. In the RDP sign in screen that opens, sign in as the user that has the Microsoft RDP (MFA) application assigned in Okta.

    Important: In both cases, the value for user must match the user name that was used when the app was assigned in Okta.

  4. All users, including those that just set up MFA in the preceding step, are prompted to choose the MFA factor to use for authentication.

  5. After providing the second factor, verify the RDP connection to the Windows server. If you cannot sign in, see the Troubleshooting section below.

  1. If you see the MFA Bypass screen shown below when signing into the server, verify in Okta that the user is included in an MFA policy. Screenshot


    Note: An App-SignOn Policy is the only policy that is relevant to the Microsoft RDP App.

  2. If you see the Display Failed screen shown below when signing into the server, verify the following: Screenshot


    • The client ID, the client secret, and the Okta URL are configured correctly.
    • The username entered into the Windows server sign in matches the username in Okta.
  3. If you cannot RDP into a server, verify that it is setup to accept remote connections in the System Properties screen, as shown below. Screenshot