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

Sends an automatic push or phone callback regardless of the AutoPush setting.

• 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 created by the installer:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Duo Security\DuoCommandLineProtection

Configure Settings For a Specific User

Configure individual settings for Duo Windows Command Line Protection by creating the following registry key with regedit.exe, the reg command, or registry file import:

HKEY_CURRENT_USER\SOFTWARE\Duo Security\DuoCommandLineProtection

These settings will override the shared defaults for that user.

Configurable Settings

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

Example reg command to disable automatic push for all users of the system:

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Duo Security\DuoCommandLineProtection" /v AutoPush /t REG_DWORD /d 0 /f

Example registry file that creates the registry key and defines settings for a single user:

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

Save the file with a .reg extension, like MyCopyOfDuoCommandLineProtectionUserSettings.reg.

Example reg command to import settings from a registry file:

reg import c:\temp\MyCopyOfDuoCommandLineProtectionUserSettings.reg

Example reg command to delete the single-user registry key and all settings below it:

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.

Advanced Client Configuration With Group Policy

Duo Windows Command Line Protection may be deployed via a Group Policy software installation package. Additional client-side configuration options for Duo may be configured via Active Directory Group Policy.

Please note that Duo Support is unable to troubleshoot issues related to MST transforms, network share permissions, or Group Policy scopes.

To create and apply the Duo Authentication for Duo Windows Command Line Protection Group Policy Object (GPO):

1. Download the Duo Windows Command Line Protection template files and documentation. View checksums for Duo downloads here.

2. Extract the contents of the zip file and copy the files into your domain's Administrative Templates store.

   \\your.domain.local\sysvol\your.domain.local\Policies\PolicyDefinitions\DuoCommandLineProtection.admx
    \\your.domain.local\sysvol\your.domain.local\Policies\PolicyDefinitions\en-us\DuoCommandLineProtection.adml

3. On your domain controller or another system with the Windows Remote Server Administration Tools installed, launch the Group Policy Management console (GPMC).

4. Expand your forest and navigate down the tree to Group Policy Objects. Right-click the Group Policy Objects folder and click New. Enter a name for the new GPO (such as "Duo Windows Command Line Protection Client") and click OK.

5. Right-click the new GPO created in step 4 and click Edit. Navigate to Computer Configuration\Policies\Administrative Templates and expand Duo Windows Command Line Protection.

6. Double-click a setting to configure it. When you've finished configuring settings, close the policy editor.

7. Once returned to the Group Policy Management window, click on the Delegation tab for your new Duo Windows Command Line Protection GPO and then click the Advanced button. Click on the Authenticated Users group in the list and then click Remove.

   Then, click Add... and type in Domain Computers, and then click OK. Check the permissions boxes in the "Allow" column to grant the "Domain Computers" group both Read and Apply group policy permissions. Click OK to apply the new delegated permissions. Verify that "Authenticated Users" no longer appears in the list. Consider preventing read of the GPO by any unprivileged user accounts to prevent exposure of the Duo secret key.

   

8. Apply the new GPO for Duo Windows Command Line Protection to domain member workstations by linking the policy to the desired OU or container.

   

For additional information about using GPOs and administrative templates, please see Microsoft's Group Policy documentation collection.

Please contact Duo Support if you need to configure the Duo Windows Command Line Protection client settings without using Group Policy.

Deploying Duo Windows Command Line Protection to clients using Active Directory

Duo Windows Command Line Protection may be deployed via a Group Policy software installation package, with or without accompanying client-side Duo settings specified in the same GPO.

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

2. Copy the downloaded MSI file (for example, duo-command-line-protection-beta-latest.msi) to your centralized software deployment share. Your software share and the Duo MSI file should be readable by "Domain Computers", as Duo Windows Command Line Protection gets installed during the pre-logon group policy processing phase of the boot process and not under the context of any named user.

   Consider modifying the access permissions of the file share location where you copy the Duo Windows Command Line Protection MSI and MST files to prevent read by user accounts to prevent exposure of the Duo secret key.

3. Create a transform for the installer file by using a table editor tool like Orca (distributed as part of the Windows SDK) to deploy the Duo Windows Command Line Protection client with initial configuration.

   1. If you are using Orca, open the Duo Windows Command Line Protection MSI file in the editor, and go to Transform → New Transform.

   2. Click on the Property table from the table list on the left side of the application. Add the following new rows (by selecting Table → Add Row while the Property table is highlighted). Use your Duo Windows Command Line application's information from the Duo Admin Panel:

      Property	Value
      DUO_IKEY	Your Duo integration key
      DUO_SKEY	Your Duo secret key
      DUO_HOST	Your Duo API hostname

      

   3. Go to Transform → Generate Transform... to create the MST file with your changes.

   4. Close Orca after generating the transform MST file, and do not save any changes to the MSI file itself.

   5. Copy the new transform file to your central application deployment share alongside the Duo Windows Command Line Protection MSI installer. The share with the MST file should not be readable by unprivileged user accounts to prevent exposure of the Duo secret key.

4. In the Group Policy Management console, create a new GPO for Duo Windows Command Line Protection publishing. Navigate to Computer Configuration\Policies\Software Settings\Software installation then right-click and select New > Package. This pops up a file browser window.

5. Use the file browser to navigate to the software deployment share where you put the Duo MSI installer and the MST transform file. Select the MSI file from your software deployment share and choose Advanced as the deployment method.

6. Go to the Modifications tab in the properties window. Click the Add button and select the MST transform you created earlier.

7. Click OK to finish, and the Duo Windows Command Line Protection software package is created. When you've finished, close the policy editor.

8. Apply the new software publishing GPO for Duo Windows Command Line Protection to domain member workstations by linking the policy to the desired OU (Organizational Unit). The target client workstations need a reboot to apply the new GPO settings and install Duo.

Here's a sample software publishing policy for Duo Windows Command Line Protection, showing use of a transform file (duo-command-line-protection-1.0.0.mst).

Learn more about installing software using Group Policy at Microsoft Support.

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.