Windows Credential Provider for MFA

Prerequisites

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

Proxy Configuration: The Okta Credential Provider for Windows does not support a discrete proxy configuration but will obey system level proxy configurations. To understand management of proxies on Windows machines, refer to www.technet.com.
The Windows machine used for installation 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+.
Inline enrollment is not supported.
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 users 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.
Configured MFA factors that include the factor to use for RDP sign in. For instructions, see MFA.

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.

Supported Operating Systems

Windows Server 2019 - v1.3.0 and later.
Windows Server 2016
Windows Server 2012
Windows Server 2012 R2
Windows Server 2008
Windows Server 2008 R2

Supported Factors

The following MFA Factors are supported:

Okta Verify

Note

Okta Verify supports Send push automatically and Do not Challenge for the next X hours options. These options are managed locally via browser cookies. If the browser is configured to automatically clear cache and cookies on window close then these settings would need to be set again anytime a new browser window is opened or any time cache and cookies are cleared.
Voice Call
On-Prem MFA (RSA)
Email
SMS Authentication
Google Authenticator
YubiKey
Symantec VIP
Security Question
Custom TOTP Authentication

Step 1 – Configure Okta

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

Configured MFA factors that include the factor to use for RDP sign in. For instructions, see MFA.
A group for the end users who will authenticate RDP sign ins. For instructions, see Group Types Used in Okta.
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 below.

Important

RDP fails with the error message Multifactor Authentication 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.

Step 2 – Install the Okta Credential Provider for Windows

From the link on the Okta Settings >Downloads page, download link for Okta Windows Credential Provider Agent. After downloading the installer, complete the following 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

On the Windows server:
1. Download the installer from the MFA Plugins and Agents section of Settings > Downloads
2. Extract the files from the .zip archive
3. Run Setup.exe.
4. Follow the prompts to complete the installation.
Note

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 it is present. Then, the installer prompts for the Visual C++ 14 Runtime Libraries, as shown below
Screenshot
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. 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>.okta.com.

Enter this information in the App Configuration screen, shown above and click Next. Then, click Next and Close to complete the installation.
In the second App Configuration screen that opens, select from the following two options, as shown below. Screenshot
- 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.
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

Extract the files from the .zip archive.
On the Windows server, run the following command from the vcredist_x64 folder of the unzipped archive.
vcredist_x64.exe /install /quiet /norestart
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.

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.

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.

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

All users who login to any machine that has the Credential Provider installed will need to be assigned to the Microsoft RDP (MFA) app. By default, the App Sign-On policy for this app prompts for MFA every login. I

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 Okta username is selected but you can make any choice.Screenshot

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.
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 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.
Navigate to the Sign on tab to configure Sign on rules specific to this app.
On the Sign On tab scroll to the Sign On Policy section.
The App Sign-On policy for this app is set to prompt for MFA for every login.
Create a new sign on rule if you do not want to prompt some or all of your users for MFA.
Assign users to the new rule and leave the ‘Prompt for factor’ checkbox unchecked.

Note
Okta sign on policy does not apply to Microsoft RDP App. Only the app sign on policy as defined in this step is evaluated.
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.

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.
Enter the name for the RDP client, your username, and password and then, click Connect.
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
All users, including those that just set up MFA in the preceding step, are prompted to choose the MFA factor to use for authentication.
After providing the second factor, verify the RDP connection to the Windows server. If you cannot sign in, see the Troubleshooting section below.

(Optional) Set up a Proxy for the System Account

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

Download pstools from Microsoft at https://docs.microsoft.com/en-us/sysinternals/downloads/pstools.
Run the command
psexec -i -s "c:\program files\Internet Explorer\iexplore.exe"
Open Internet options > Connections > LAN Settings
Set the proxy server and port.
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.

Troubleshooting

If you see the MFA Bypass screen shown below when signing in, 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.
If you see the Display Failed screen shown below when signing in, verify the following: Screenshot
- 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.
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

If you see System.Net.WebException similar to that shown below:

System.Net.WebException: The underlying connection was closed: An unexpected error occurred on a send.
. . . 
System.IO.IOException: Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host. 
. . . 
System.Net.Sockets.SocketException: An existing connection was forcibly closed by the remote host.

Cause is an older version of TLS, Required version is TLS 1.2.
Open a PowerShell terminal as administrator and execute the following script:

$is64bit = [IntPtr]::Size * 8 -eq 64
Write-Host "Is 64-bit script: $is64bit"
#helper function to check for if 0x800 bit is set
function checkTls12Bit([Int] $regValue) {
    return ($regValue -band 0x800) -ne 0x800
}

function setRegKeyToBitValue([string] $regBranch, [string] $regKey) {
    $current = Get-ItemProperty -Path $regBranch
    $regValue = $current.$regKey
    if ($regValue -eq $null -or (checkTls12Bit $regValue) ) {
        if ($regValue -eq $null) {
	        $regValue = 0x800
	     } else	{
             $regValue = $regValue -bor 0x800
 	     }

	     $p = New-ItemProperty $regBranch -Name $regKey -PropertyType DWord -Value $regValue -ErrorAction Stop -Force
	     Write-Host "Updated $regBranch\$regKey value to $regValue" 
	     return $true
	 }
	Write-Host "$regBranch\$regKey value is $regValue. No change."
	return $false
}

function setRegKeyToValueOfOne([string] $regBranch, [string] $regKey) {
    $current = Get-ItemProperty -Path $regBranch
	if ($current.$regKey -ne 1) {
		$p = New-ItemProperty $regBranch -Name $regKey -PropertyType DWord -Value 1 -ErrorAction Stop -Force
		Write-Host "Updated $regBranch\$regKey value to 1"
		return $true
	 }
	Write-Host "$regBranch\$regKey value is 1. No change."
	return $false
}

#setup .net tls settings
function setupTls4NET([boolean]$is64bit, [string]$regBranch, [string]$reg32bitBranch) {
# https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls
    $updated = setRegKeyToValueOfOne $regBranch "SchUseStrongCrypto"
	$updated = (setRegKeyToValueOfOne $regBranch "SystemDefaultTlsVersions") -or $updated

	if ($is64bit) {
    	$updated = (setRegKeyToValueOfOne $reg32bitBranch "SchUseStrongCrypto") -or $updated
		$updated = (setRegKeyToValueOfOne $reg32bitBranch "SystemDefaultTlsVersions") -or $updated
	}

	return $updated
}							
# https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/how-to-determine-which-versions-are-installed

$version = Get-ItemProperty -Path "HKLM:\Software\Microsoft\NET Framework Setup\NDP\v4\Full" -Name Release
# 394254 - .NET Framework 4.6.1, which is the current target of the installer
if ($version.Release -ge 394254)  {
    $ev = [environment]::Version
	$v = "v" + $ev.Major + "." + $ev.Minor + "." + $ev.Build
	$updated = setupTls4NET $is64bit "HKLM:\SOFTWARE\Microsoft\.NETFramework\$v" "HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\$v"
# https://support.microsoft.com/en-ca/help/3140245/update-to-enable-tls-1-1-and-tls-1-2-as-a-default-secure-protocols-in

	$updated = (setRegKeyToBitValue "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp" "DefaultSecureProtocols") -or $updated
	$updated = (setRegKeyToBitValue "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings" "SecureProtocols") -or $updated

	# updated the 32-bit branches if we are on 64-bit machine
	if ($is64bit) {
		$updated = (setRegKeyToBitValue "HKLM:\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp" "DefaultSecureProtocols") -or $updated
		$updated = (setRegKeyToBitValue "HKLM:\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings" "SecureProtocols") -or $updated
	}

	# current user settings
	$updated = (setRegKeyToBitValue "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings" "SecureProtocols") -or $updated

	# local system account
	$userSid = ".DEFAULT"
	$updated = (setRegKeyToBitValue "Registry::HKEY_USERS\$userSid\Software\Microsoft\Windows\CurrentVersion\Internet Settings" "SecureProtocols") -or $updated

	if ($updated) {
		Write-Host "Done. Updated required settings."
	}
	else
	{
	    Write-Host "Done. No updates are required."
	}
}
							else 
							{
							Write-Host "No changes were made. Your version of .NET Framework is earlier version than 4.6.1, please upgrade."
}

Logging

Windows logs can be helpful when troubleshooting.
The log file for Windows Credential provider can be found in
C:\Program Files\Okta\Okta Windows Credential Provider\logs
The log contains error messages, warnings and other information that may be helpful when troubleshooting.

MFA for Windows Credential Provider

Overview

Installation