Duo Windows Command Line Protection

Duo Windows Command Line Protection is a Beta feature.

Overview

Duo Windows Command Line Protection provides multi-factor authentication (MFA) for command-line tools like PowerShell and SSH on Windows systems.

Duo Windows Command Line Protection adds MFA protection for the following logon scenarios:

• Windows PowerShell.
• Windows OpenSSH server logons using SSH.
• Windows OpenSSH server logons using SFTP.

Requirements

Windows Versions

Duo Windows Command Line Protection supports both client and server operating systems.

Clients:

• Windows 10
• Windows 11

Servers:

• Windows Server 2019
• Windows Server 2022
• Windows Server 2025

Ensure your system's time is correct before installing Duo.

Prerequisites

• .NET Framework 4.8.0 Runtime or compatible
• OpenSSH for Windows: Required if using the system as an SSH server.
• Windows Remote Management (WinRM): Must be enabled for PowerShell usage.

Enable Windows Remote Management (WinRM)

Enable WinRM before installing Duo Windows Command Line Protection if the system will be used for PowerShell Remoting. Run the following command from an elevated PowerShell prompt on the target system:

Enable-PSRemoting –Force

For additional details about this command see Enable-PSRemoting.

System Processor

Duo Windows Command Line Protection supports only 64-bit Intel/AMD architectures.

Duo Windows Command Line Protection does not support devices with ARM processors, like the Surface Pro X.

Duo Factor Support

Duo Windows Command Line Protection supports these factor types for online MFA:

SSH

• Duo Push
  • Verified Duo Push (verification codes only)
• Duo Mobile Passcodes
• SMS Passcodes
• Hardware Token OTP passcodes (including Yubikey OTP)
• Phone Call
• Bypass Codes

PowerShell

• Duo Push
  • Verified Duo Push (verification codes only)
• Phone Call

SFTP

• Duo Push (Verified Duo Push not supported)
• Phone Call

Feedback display to console and keyboard interaction is prevented during SFTP connection, which limits supported MFA factors.

Enroll a User First

Duo Windows Command Line Protection doesn't support inline self-service enrollment for new Duo users. Unenrolled users, that is, users that do not yet exist in Duo with an attached 2FA device, must be created manually by an administrator, imported by an administrator or self-enrolled through another application which supports Duo’s self-service enrollment (see Test Your Setup) before those users can log in with Duo Windows Command Line Protection.

The Duo username (or username alias) should match the Windows username. When you create your new application in Duo the username normalization setting defaults to "Simple", which means that the if the application sends the usernames "jsmith," "DOMAIN\jsmith," and "jsmith@domain.com" to Duo at login these would all resolve to a single "jsmith" Duo user.

Duo Windows Command Line Protection supports Duo Push and verified Duo Push, phone callback, and passcodes generated by Duo Mobile, a hardware token, received via SMS, or provided by a Duo administrator as authentication methods. Duo users must have one of these methods available to complete 2FA authentication.

If the user creating PowerShell, SSH, or SFTP connections after Duo Windows Command Line Protection is installed does not exist in Duo, the user will not be able to authenticate.

We recommend using bulk enrollment or directory sync to send your users unique self-enrollment links via email. Read the enrollment documentation to learn more.

First Steps

Before moving on to the deployment steps, it's a good idea to familiarize yourself with Duo administration concepts and features like options for applications, available methods for enrolling Duo users, and Duo policy settings and how to apply them. See all Duo Administrator documentation.

1. Sign up for a Duo account.

2. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.

3. Locate the entry for Duo Windows Command Line Protection with the "2FA" label in the catalog. Click the + Add button to create the application and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications with Duo and additional application options.

4. No active Duo users can log in to new applications until you grant access. Update the User access setting to grant access to this application to users in selected Duo groups, or to all users. Learn more about user access to applications. If you do not change this setting now, be sure to update it so that your test user has access before you test your setup.

   This setting only applies to users who exist in Duo with "Active" status. This does not affect application access for existing users with "Bypass" status, existing users for whom the effective Authentication Policy for the application specifies "Bypass 2FA" or "Skip MFA", or users who do not exist in Duo when the effective New User Policy for the application allows access to users unknown to Duo without MFA.

5. We recommend setting the New User Policy for your application to Deny Access, because no unenrolled user may complete Duo enrollment via this application.

6. Download the Duo Windows Command Line Protection installer package. View checksums for Duo downloads here.

Verified Duo Push for Duo Windows Command Line Protection

Available in: Duo Essentials, Duo Advantage, and Duo Premier

Duo Windows Command Line Protection supports Verified Duo Push with a numeric code. Verified Duo Push requires Duo Mobile 4.16.0 or later on Android 8+ or Duo Mobile 4.17.0 or later on iOS 16+, activated for Duo Push.

Applying an Authentication Methods policy enabling Verified Duo Push with a verification code to a Duo Windows Command Line Protection application will require users to enter the verification code into the Duo Mobile app when performing a Duo Push to authenticate.

To enable Verified Duo Push for Duo Windows Command Line Protection:

1. Create a new custom policy or update an existing policy which enables both the Require Verified Duo Push and Require users to enter a verification code options in the Authentication Methods policy settings. Click Save Policy when done.

2. Apply the custom policy to your Duo Windows Command Line Protection application. If you made the change in your global policy then the setting applies to all your Duo Windows Command Line Protection applications.

   The policy setting takes immediate effect — there is no need to reinstall Duo Windows Command Line Protection.

With this policy setting applied, users must enter the verification code shown in the Duo for Duo Windows Command Line Protection text prompt into the Duo Mobile authentication request.

Run the Installer

To install Duo Windows Command Line Protection:

1. Launch the Duo Windows Command Line Protection MSI from an elevated command prompt (right-click "Command Prompt" and select the "Run as Administrator" option). Accept the license agreement and continue.

2. Verify that you want to install Duo Windows Command Line Protection for Duo Windows SSH and Duo Powershell. Click Next.

   

3. Enter your Integration key, Secret key, and API hostname from the Command Line Protection application page when prompted. Click Next.

   

   If the Bypass Duo authentication when offline option is unchecked, then Duo Windows Command Line Protection will "fail closed" when Duo Security cloud services are unreachable and users will not be able to access protected federated resources. Check the box if you want users to be able to access protected applications without Duo authentication if Duo's cloud service is unreachable. This setting can be changed post-install from the registry.

   Duo Windows Command Line Protection sends a user's Windows sAMAccountName to Duo's service by default. To send the userPrincipalName to Duo instead, check the Use UPN username format box.

   If you enable the UPN username format option, you must also change the properties of your Duo Windows Command Line Protection application in the Duo Admin Panel to change the "Username normalization" setting to None. Otherwise, Duo drops the domain suffix from the username sent from the client to our service, which may cause user mismatches or duplicate enrollment.

4. Click Finish.

Silent Installation

You can also install Duo Windows Command Line Protection silently. Learn more.

Configuration

To enable Duo for PowerShell, you must configure the PowerShell Execution Policy.

Configure the PowerShell Execution Policy

To configure the PowerShell Execution Policy:

• Ensure the execution policy on the server allows running signed scripts. Typically, this is set to AllSigned or RemoteSigned:
  • AllSigned: Requires all scripts and configuration files to be signed by a trusted publisher.
  • RemoteSigned: Requires scripts downloaded from the internet to be signed by a trusted publisher.

Run the following command to configure the execution policy:

Set-ExecutionPolicy AllSigned -Scope LocalMachine

or:

Set-ExecutionPolicy RemoteSigned -Scope LocalMachine

Customize Duo Windows Command Line Protection Behavior

You may also configure additional options (for example, shared or specific behavior settings, PowerShell Remote Sessions, Windows OpenSSH ForceCommand).

Configure Shared Settings

Configure shared settings for Duo Windows Command Line Protection at the following registry path:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Duo Security\DuoCommandLineProtection

Configure Settings For a Specific User

Configure individual settings for Duo Windows Command Line Protection at the following registry path:

HKEY_CURRENT_USER\SOFTWARE\Duo Security\DuoCommandLineProtection

Configurable Settings

Edit the Windows Registry to override default settings. The following configurable options are available:

Example registry file:

Windows Registry Editor Version 5.00 
[HKEY_CURRENT_USER\Software\Duo Security\DuoCommandLineProtection] 
"Prompts"=dword:00000002 
"AutoPush"=dword:00000000 
"LogLevel"=dword:00000000

To import settings from a registry file, run the following command:

reg import c:\temp\MyCopyOfDuoCommandLineProtectionUserSettings.reg

To remove the registry key and all settings below it, run the following command:

reg DELETE "HKEY_CURRENT_USER\Software\Duo Security\DuoCommandLineProtection" /f 

Configure PowerShell Remote Sessions

The installer for Duo Windows Command Line Protection configures Duo for the default Powershell session configuration named ‘microsoft.powershell’.

Enable Duo MFA for Other PowerShell Configurations

To register a session configuration with Duo MFA as the startup script, run the following commands:

$DuoAuthenticationScript = 'c:\Program Files\Duo Security\DuoCommandLineProtection\DuoAuthenticate.ps1'

Register-PSSessionConfiguration -Name TestDuo -StartupScript $DuoAuthenticationScript

Configure Windows OpenSSH ForceCommand

To run multiple commands during SSH authentication, use one of the following:

• Create a Combined Command File: Combine multiple commands into a single script and set it as the ForceCommand:

  ForceCommand "C:\MyServerDir\CombinedCommandFile.bat"

• Chain Commands: Use & to chain multiple commands:

  ForceCommand "C:\Program Files\Duo Security\DuoCommandLineProtection\login_duo.exe" --context SSH & "C:\temp\DuoWinSsh\echo_out.bat"

• Ensure logic in subsequent commands verifies Duo MFA success. For example,

  if %ERRORLEVEL% EQU 0 echo "Authentication successful"

Test Your Setup

With the default automatic push behavior, you will receive an automatic push or phone callback.

When automatic push is off, you'll receive a text-based prompt for additional verification.

Enter the number corresponding with the authentication method you want to use and complete Duo authentication on that device, or enter a passcode.

If the effective authentication methods policy requires Verified Duo Push with a verification code, enter the verification code shown into Duo Mobile on the selected device in response to the Duo Push request. Learn more about completing Verified Duo Push authentication on Android or iOS/iPadOS.

Duo Secret Rotation

If you need to reset the client secret for Duo Windows Command Line Protection after installation try the Duo Secret Rotation tool.

Logging

Log files are saved to the %temp% directory for each user, with a separate log file created for each MFA context. See Configurable Settings to learn how to adjust the logging level.

Troubleshooting

Need some help? Take a look at our Duo Windows Command Line Protection Knowledge Base articles or Community discussions. For further assistance, contact Support.