Credential Provider for Windows

Overview

The Okta Credential Provider for Windows prompts users for MFA when signing in to supported Windows servers and workstations with an RDP clientEssentially, a client is anything that talks to the Okta service. Within the traditional client-server model, Okta is the server. The client might be an agent, an Okta mobile app, or a browser plugin. .

This is an Early AccessEarly Access (EA) features are opt-in features that you can try out in your org by asking Okta Support to enable them. Additionally, the Features page in the Okta Admin Console (Settings > Features) allows Super Admins to enable and disable some EA features themselves. feature. To enable it, use the Early Access Feature Manager as described in Manage Early Access and Beta features .

Additionally, with the EA feature, end usersIn Okta literature, we generally refer to "end users" as the people who have their own Okta home page (My Applications), using apps to authenticate into all of their apps. End users do not have any administrative control. When we refer to "users" we are generally referring to the individual(s) who have administrative control. can reset their Active DirectoryActive Directory (AD) is a directory service that Microsoft developed for the Windows domain networks. It is included in most Windows Server operating systems as a set of processes and services. Initially, Active Directory was only in charge of centralized domain management. passwords without contacting their administrators. This is done with the Reset Okta Password link on the sign-on screen.

ClosedPrerequisites

Note the following requirements before installing the Okta Credential Provider for Windows:

Important Note

Important

TLS 1.2 is required. For information on enabling TLS 1.2 in .NET and in Microsoft Internet Explorer browsers, see Okta ends browser support for TLS 1.1.

ClosedSupported Operating Systems
  • Windows Server 2016
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows Server 2008
  • Windows Server 2008 R2
ClosedSupported Factors

The following MFA Factors are supported:

 

Installation

Sign in to Okta and verify or set up policies. Install the agent on the Windows server and return to Okta to create an appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. and assign users. Test the setup once the installation has been successful. The installation contains three major installation steps and one testing step. Be sure to complete the testing after the installation.

ClosedStep 1 – Configure Okta

Before installing the Okta credential provider for Windows, your orgThe Okta container that represents a real-world organization. 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.

    Important: RDP fails with the error message Multifactor AuthenticationAuthentication is distinct from authorization, which is the process of giving individuals access to system objects based on their identity. Authentication merely ensures that the individual is who he or she claims to be, but says nothing about the access rights of the individual. Authentication methods and protocols include direct auth, delegated auth, SAML, SWA, WS-Fed, and OpenID Connect. Failed if the user that tries to RDP into a server with the RDP agent installed that does not match an Microsoft RDP (MFA) App username.

ClosedStep 2 – Install the Okta Credential Provider for Windows

From the link on the Okta Downloads page, download link for Okta Windows Credential Provider Agent (version 1.1.3). 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.

ClosedStandard installation

  1. On the Windows server, extract the files from the .zip archive provided to you by Okta Support 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. ClosedScreenshot

  2. During the installation, two App Configuration screen display appear. The first requests a client ID, a client secret, and an Okta URL, as shown below. ClosedScreenshot

    App Configuration screen

    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>.okta.com.

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

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

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

ClosedSilent 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"

    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 *.oktapreview.com or *.okta-emea.com.

  4. 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 both Windows 2012 and 2016.  false true
    SslPinningEnabled Validate the public key of the Okta server to which the agent is connecting. true true
    DisplayPasswordResetLink

    This property applies only to the Beta version, 1.2.1. If you upgraded from the GA version 1.1.4 to Beta 1.2.1, 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 test with Powershell versions, 3, 4, and 5. To find the version of Powershell on your system, use $PSVersionTable.

ClosedMass 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 adminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. 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>

.replacing

  • 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.
ClosedConfigure 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 make this specification, edit the file rdp_app_config.json that is typically located in the C:\Program Files\Okta\Okta Windows Credential Provider\config folder. Toggle the InternetFailOpenOption value to one of the following values.

true – if internet connectivity is lost, a user attempting to authenticate across RDP is not challenged for MFA and is granted access based on password alone.

false – if internet connectivity is lost, a user attempting to authenticate across RDP is not granted access because the credential provider cannot reach the Okta service.

Info

Note

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

ClosedVerify Windows and Okta widget 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. Edit the following file using an editor of your choice: 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.

 


ClosedStep 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, 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.ClosedScreenshot

    Sign On Methods screen

    Info

    Important

    When the end user signs in, the application user format must match exactly.

    Best practice: Okta recommends using a username prefix, as Windows uses the SAMAccountName for login.

  2. Select the Assignments tab and assign the app to users or groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups.. After selecting Assign, enter the user name. For more information on assigning apps, see Assign Applications.

    Info

    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 name@yourorg.com, 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 @yourorg.com portion of the UPN is included in the AD SAM account name.

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


ClosedTesting – 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 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.

    Info

    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.

Closed(Optional) Set up a Proxy for the System Account

Complete the following steps to set up a proxy for the system account.

  1. Download pstools from Microsoft at https://docs.microsoft.com/en-us/sysinternals/downloads/pstools.
  2. Run the command
    psexec -i -s "c:\program files\Internet Explorer\iexplore.exe"
  3. Open Internet options > Connections > LAN Settings
  4. Set the proxy server and port.
  5. Click OK, and then, click OK again on the Internet options dialog.

After completing this setup, the system responds as follows

  • If the proxy is running, users can access the okta widget for MFA and sign in.
  • If the proxy is not running, users receive the message Multifactor Authentication Failed, and the system log shows a connectFailure error.
ClosedTroubleshooting

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

    MFA Bypass screen

    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 in, verify the following: ClosedScreenshot

    • The client ID, the client secret, and the Okta URL are configured correctly.
    • The username entered into the Windows 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. ClosedScreenshot

    System Properties screen

ClosedLogging

Windows logs can be helpful when troubleshooting.
The log file for Windows Credential provider can be found in
${USERPROFILE}\AppData\Local\Okta\Okta MFA Provider\logs\OktaMfaAdfs.log

For example:
C:\Users\GroupManagementAcnt$\AppData\Local\Okta\Okta MFA Provider\logs

The log contains error messages, warnings and other information that may be helpful when troubleshooting.
In addition, Windows Events may contain helpful information related to the errors and failures.

Top

© 2019 Okta, Inc All Rights Reserved. Various trademarks held by their respective owners.