Install the Okta Credential Provider for Windows

Install the provider by using any of the supported installation methods: standard, silent, and mass deployment.

Standard installation

  1. Go to the location where you downloaded the installer.
  2. Extract the files from the .zip archive.
  3. Run setup.exe as an administrator and follow the prompts. Install or repair the Microsoft Visual C++ runtime libraries as required.
  4. On the App Configuration dialog, enter a client ID, client secret, and your Okta URL. Click Next after you've entered the information.

    You can get these values from the Microsoft RDP (MFA) app in Okta. Select the General tab, scroll to the Client Credentials section to find the client ID and the client secret. The Okta URL is the URL that your org uses to reach Okta (for example, https://<yourorg>.okta.com).

  5. Click Next and Close to complete the installation.
  6. In the second App Configuration dialog, select from the following options:
    • Filter Credential Provider: This option provides a workaround when a server has multiple credential providers installed. If selected, the Okta MFA Credential Provider is the only method used to apply MFA to RDP connections. Unauthenticated users can't 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. Selecting this option removes Okta MFA from local (interactive) logons.
    • (EA version only) Display Okta password reset link (self service): Select this to add an option to the Windows sign-on page that allows end users to reset their password through Okta.
  7. Verify the installation by locking the machine. If successfully installed, the sign-in page shows Okta as a sign-in option.

    The appearance of the sign-in page varies between different versions of Windows Server.

Silent installation

  1. Go to the location where you downloaded the installer.
  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 either of the following commands to install Okta Windows Credential Provider silently:

    Method

    Command

    Description

    1

    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) app in Okta. You can also manually edit this value in the RDP agent config file.
    • CLIENT_SECRET: Find this value on the General tab of the Microsoft RDP (MFA) app in Okta. If the client secret is reset, you must reinstall the agent because the secret is encrypted in the agent config file. You can also manually edit this value in the RDP agent config file.
    • OKTA_URL: Your org URL. Use the format https://org_name.okta.com. HTTPS is required. You can also use *.okta-gov.com, *.oktapreview.com, and *.okta-emea.com.

    2

    msiexec /qb /log log.txt /i OktaWindowsCredentialProvider.msi CFGFILE="d:\config.json"

    • The filename in the CFGFILE parameter must be fully qualified.
    • These are contents of the config.json file. Don't encrypt the ClientSecret parameter:

    {

    "Url": "https://org.okta.com",

    "ClientId": "0oa.....n0h7",

    "ClientSecret": "1g3....A_X",

    "RdpOnly": true,

    "SslPinningEnabled": true

    }

  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 enforced:

    Property

    Definition

    Default value

    Suggested value

    FilterCredentialProvider

    This property provides a workaround when a server has multiple credential providers installed. If true, the Okta MFA Credential Provider is the only method used to apply MFA to RDP connections. It doesn't permit unauthenticated users to select which credential provider to use.

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

    false -
    InternetFailOpenOption

    Sets authentication flow behavior if network connectivity is lost. This property governs proper access if the target machine doesn't have internet access for MFA.

    If true, a user attempting to authenticate across RDP isn't challenged for MFA and is granted access based on password alone.

    When false, a user attempting to authenticate across RDP isn't granted access because the credential provider can't reach the Okta service.

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

    The maximum value is 120 seconds.

    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 a link to reset the Active Directory password. false true
    DisconnectSessionOnError When this property is set to true, Okta attempts to disconnect the user’s session if there’s a timeout or an unexpected error. Under the default value, the user’s session terminates instead of disconnects so that unsaved data may be lost. false -

    To modify these properties, edit the file rdp_app_config.json (by default, in the C:\Program Files\Okta\Okta Windows Credential Provider\config folder) or use the following PowerShell 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 where you extracted the .zip archive.

    This script was tested with PowerShell versions 3, 4, and 5. To determine the version of PowerShell 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://yourdomain.okta.com" /qn /l*v <path for installation log>

Elements of the command should be modified as follows:

  • Replace <IP of the machine to deploy>, <AD admin user>, and <path for installation log> with appropriate values for your organization.
  • Replace the <client secret> and <client ID> to match your application.
  • Replace yourdomain with the name of your Okta organization.

Configure behavior if network connectivity is lost

After completing the installation, you can configure the behavior of the authentication flow if network connectivity is lost.

To configure this behavior, edit rdp_app_config.json (by default, in the C:\Program Files\Okta\Okta Windows Credential Provider\config folder). Set InternetFailOpenOption to one of the following values:

  • true: If internet connectivity is lost, a user attempting to authenticate across RDP isn't challenged for MFA and is granted access based on password alone.
  • false: If internet connectivity is lost, a user attempting to authenticate across RDP isn't granted access because the credential provider can't reach the Okta service.

You can also modify any of the other properties listed in Step 4 in the Silent Installation section.

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.

    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. Go to C:\Program Files\Okta\Okta Windows Credential Provider\config
  2. Edit rdp_app_config.json
  3. Add the following properties and values to the file, delineating each entry with a comma:
    • "WidgetTimeOutInSeconds": 30
    • "ErrorTimeOutInSeconds": 30

    • "EnforceTimeoutVersionAgnostic": false

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