Install the Okta Credential Provider for Windows

Install the Okta Credential Provider for Windows using any of these installation methods: standard, silent, or mass deployment.

See Okta MFA Credential Provider for Windows for installation requirements.

The Sign-In Widget (third generation) doesn't support multifactor authentication for third-party agents.

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++ and .NET runtime libraries as required.
  4. On the App Configuration dialog, enter a client ID, client secret, and your Okta org URL. You can find these values in the Microsoft RDP (MFA) app in Okta. Select the General tab and then go to the Client Credentials section.
  5. Click Next.
  6. Click Next and then Close to complete the installation.
  7. In the second App Configuration dialog, select from the following options:
    • Filter Credential Provider: If you select this agent, it's the only method used to apply MFA to RDP connections. Unauthenticated users can't select a credential provider. This option provides a workaround when a server has multiple credential providers installed.
    • RDP Only: By default, the installed credential provider inserts Okta MFA between an RDP and a local authentication event. Selecting this option removes Okta MFA from local (interactive) sign-in flows.
    • (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.
  8. Verify the installation by locking the machine. If successfully installed, the sign-in page shows Okta as a sign-in option.

Silent installation

  1. Verify that the Microsoft Visual C++ Redistributable and the .NET Framework have been installed.
  2. Go to the location where you downloaded the installer.
  3. Extract the files from the .zip archive.

  4. Run either of the following commands to install Okta Credential Provider for Windows 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 the 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 to enforce MFA. Edit the rdp_app_config.json file. By default, it's in the C:\Program Files\Okta\Okta Windows Credential Provider\config folder. You can also use this PowerShell script. Run this script from the same location where you extracted the .zip archive:

    $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'

    Property

    Definition

    Default value

    Suggested value

    FilterCredentialProvider

    If you set this value to true, it's the only method used to apply MFA to RDP connections. Unauthenticated users can't select a credential provider. This property provides a workaround when a server has multiple credential providers installed.

    Setting this property to true and RdpOnly to false causes the agent to prompt for MFA if the policy requires it.

    		false-
    InternetFailOpenOption

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

    If you set this property to true, users who authenticate across RDP aren't challenged for MFA and are granted access based on password alone.

    If you set this property to false, users who authenticate across RDP aren'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 an RDP and a local authentication event. Setting this property to true removes Okta MFA from local (interactive) sign-in flows.

    Setting FilterCredentialProvider to true and this property to false causes the agent to prompt for MFA if the policy requires it.

    		false-
    WidgetTimeOutInSeconds

    The number of seconds before a timeout. To prevent Windows from closing the RDP session, set this to a smaller value than the idle timeout set in Windows.

    The default Okta widget timeout session is 60 seconds. The maximum value is 120 seconds.

    		6030
    ErrorTimeOutInSecondsThe timeout duration after which the RDP session is closed when an error message appears.3030
    EnforceTimeoutVersionAgnosticEnforce timeout durations for Windows versions 2012, 2016, or 2019. falsetrue
    SslPinningEnabledValidate the public key of the Okta server to which the agent is connecting.truetrue
    DisplayPasswordResetLink

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

    		Display a link to reset the Active Directory password.falsetrue
    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.

    When this property is set to false, the user's session terminates instead of disconnects. Any unsaved data may be lost.

    		false-

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>

Modify the elements of the command 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 those used by your application.
  • Replace yourdomain with the name of your Okta organization.