Install the Okta Credential Provider for Windows

After downloading the installer, complete the following steps.

To copy information from the application configuration during the installation process, keep a browser open on the Microsoft RDP (MFA) applications General tab.


Okta supports standard, silent installation and mass deployment.

Topics:

Standard installation

  1. Navigate to the directory where the installer was downloaded.
  2. Extract the files from the .zip archive
  3. As administrator, run Setup.exe.
  4. Follow the prompts to complete the installation:
  5. Info

    The installer package contains the C++ Runtime libraries. The installer prompts you to install these redistributable runtime libraries if it is not present, or to repair it, if present.
    The installer prompts for the Visual C++ 14 Runtime Libraries, as shown below

    ClosedScreenshot

  6. On the App Configuration dialog, populate the client ID, a client secret, and Okta URL , as shown below. ClosedScreenshot

    App Configuration screen

    To obtain these values, in a browser navigate the Microsoft RDP (MFA) app in Okta. Select the General tab, scroll down to the Client Credentials section 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>.okta.com.

    Enter this information in the App Configuration screen, shown above and click Next.

  7. Click Next and Close to complete the installation.
  8. In the second App Configuration screen that opens, select from the following two options, as shown below. ClosedScreenshot

    • Filter Credential Provider – this option provides a workaround when multiple credential providers are installed on a server. If selected, this option makes the Okta MFA Credential Provider the only method for applying MFA to RDP connections and does not permit unauthenticated users to select which credential provider to use.
    • RDP Only – By default, the installed credential provider inserts Okta MFA between both an RDP and a local authentication event. Checking this box will remove Okta MFA from local (interactive) logons.
    • (EA version only) Display Okta password reset link (self service) -Checking this box will add an option to the Windows sign-on screen for end users to reset their password via Okta.
  9. 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. ClosedScreenshot

Silent installation

  1. Navigate to the directory where the installer was downloaded.
  2. Extract the files from the .zip archive.

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

    vcredist_x64.exe /install /quiet /norestart

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

    Parameters

    CLIENT_ID – find this value on the General tab of the Microsoft RDP (MFA) application in Okta. Can also be edited manually in the RDP agent config file.

    CLIENT_SECRET – find this value on the General tab of the Microsoft RDP (MFA) application in Okta. Resetting the ClientSecret will require reinstallation of the agent as the value in the config file is encrypted. Can also be edited manually in the RDP agent config file.

    OKTA_URL – Your org URL. Must use the format https://org_name.okta.com. HTTPS is required. Also supported are *.okta-gov.com, *.oktapreview.com or *.okta-emea.com.

  5. Modify additional properties

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

    Property Definition Default Value Suggested Value
    FilterCredentialProvider

    This property provides a workaround when multiple credential providers are installed on a server. If true the Okta MFA Credential Provider is the only method for applying MFA to RDP connections and does not permit unauthenticated users to select which credential provider to use.

    Setting FilterCredentialProvider to true and RdpOnly to false will cause the agent to prompt for MFA if required by the policy.

    false -
    InternetFailOpenOption

    Sets authentication flow behavior if network connectivity is lost. When true, a user attempting to authenticate across RDP is not challenged for MFA and is granted access based on password alone; when false, a user attempting to authenticate across RDP is not granted access because the credential provider cannot reach the Okta service.

    InternetFailOpenOption governs proper access if the target machine does not have Internet access for MFA.

    Set this property to true if Internet connectivity is a frequent issue.

    false -
    RdpOnly

    By default, the installed credential provider inserts Okta MFA between both an RDP and a local authentication event. Setting this property to true removes Okta MFA from local (interactive) logons.

    Setting FilterCredentialProvider to true and RdpOnly to false will cause the agent to prompt for MFA if required by the policy.

    false -
    WidgetTimeOutInSeconds The number of seconds before timeout. To prevent the possibility that Windows might close the RDP session, this value must be smaller than the idle timeout set in Windows. 60 30
    ErrorTimeOutInSeconds The timeout after which the RDP session is closed when an error message is displayed. 30 30
    EnforceTimeoutVersionAgnostic Enforce timeout for Windows 2012, 2016 or 2019.  false true
    SslPinningEnabled Validate the public key of the Okta server to which the agent is connecting. true true
    DisplayPasswordResetLink

    If you upgraded from the version 1.1.4 to a later version, you must add this property.

    Display link to reset Active Directory password. false true

    To modify these properties, edit the file rdp_app_config.json that is typically located in the C:\Program Files\Okta\Okta Windows Credential Provider\config folder, or use the following power shell script.

    $rdpAppConfig = Get-Content 'C:\Program Files\Okta\Okta Windows Credential Provider\config\rdp_app_config.json' -raw | ConvertFrom-Json
    $rdpAppConfig.RdpOnly =([System.Convert]::ToBoolean('true'))
    $rdpAppConfig | ConvertTo-Json | Set-Content  'C:\Program Files\Okta\Okta Windows Credential Provider\config\rdp_app_config.json'

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

    Info

    Note

    This script was tested with Powershell versions, 3, 4, and 5.
    To determine Powershell version on your system, open Powershell as administrator and enter$PSVersionTable.

Mass Deployment

Use the Microsoft psexec64 tool to execute commands on remote machines. Modify the following command for a mass deployment:

psexec64 <IP of the machine to deploy> -u <AD admin user> -p <AD admin password> msiexec /i <//machine/share/OktaWindowsCredentialProvider.msi> CLIENT_ID="<client id>" CLIENT_SECRET="<client secret>" OKTA_URL="https://yourdoman.okta.com" /qn /l*v <path for installation log>

Where:

  • IP of the machine to deploy, <AD admin user> and <path for installation log> with appropriate values for your organization.

  • the client secret and client ID to match your application
  • yourorg with the name of your Okta organization.

Verify timeout settings

To ensure that MFA works as expected, verify that the Okta sign in session times out before the Windows session.

Note the following:

  • By default, the Okta widget timeout session is set to 60 seconds.
  • Determine the timeout duration in your Windows environment then set the session timeout duration for the Okta widget to be shorter than the Windows timeout session.
    Info

    Important

    Set up a test in the environment by manually timing the session duration for both Windows and Okta to ensure that the timeout duration specified for each work as expected.

To configure the Okta widget timeout session duration:

  1. Navigate to C:\Program Files\Okta\Okta Windows Credential Provider\config
  2. Using an editor of your choice, open: rdp_app_config.json.
  3. Add the following properties and values to the file.
    Delineate each entry with a comma:
    • "WidgetTimeOutInSeconds": 30
    • "ErrorTimeOutInSeconds": 30

    • "EnforceTimeoutVersionAgnostic": false
    Info

    Note

    You may specify another value for timeout as long as it is lower than your Windows session timeout duration.