Installing the PingID integration for Windows login using CLI

Install PingID integration for Windows login through the command-line interface (CLI).

Before you begin

Adding any multi-factor authentication (MFA) method is a procedure that carries the risk of being locked out of the machine. See Prerequisites for installing PingID integration for Windows login before proceeding.

About this task

Running the installer program for PingID integration for Windows login from the command line is useful for deploying to multiple machines in batch mode.

Steps

On the PingID Downloads page, go to Integrations, and download and extract PingID for Windows login.

Using the parameters table below, from the Command Prompt, create a .bat or .cmd file containing the command for the PingID integration for Windows with the parameters you require. Alternatively, run the installer directly from the command prompt for a list of parameters.

To integrate PingID integration for Windows login through PingFederate, you must include the /PingFedAddress=<baseurl> parameter.

Choose from:

Install using the pingid.properties file to supply parameter values.

<Full filepath of the installer for PingID integration for Windows>\PingIDWindowsLogin_<ver>.exe
/SILENT /VERYSILENT /SUPPRESSMSGBOXES /SP- /LOG=<Full output log filepath>  /orgSettingsFilePath= <Full pingid.properties filepath> /OfflineAuthType /OfflinePolicy  <[Optional parameters]>

Install without using the pingid.properties file and supply the /orgAlias, /orgKey, /authenticatorAddress, /idpUrl, and /token parameter values on the command line.

<Full filepath of the installer for PingID integration for Windows>\PingIDWindowsLogin_<ver>.exe
/VERYSILENT /SUPPRESSMSGBOXES /SP- /LOG=<Full output log filepath>  /orgAlias=<organization's alias string>
/orgKey=<organization's key string>  /authenticatorAddress=<URL of PingID data center>  /idpUrl=<URL of server used for PingID API requests>  /token=<API key identifier>  /OfflineAuthType /OfflinePolicy  <[Optional parameters]>

Example:

C:\Users\Admin\Downloads\PingIDWindowsLogin_28.exe  /VERYSILENT /SUPPRESSMSGBOXES
/SP- /LOG=C:\Users\Admin\Temp\Logs\PingIDWindowsLogin.log  /orgSettingsFilePath=C:\Users\Admin\Downloads\pingid.properties
/OfflineAuthType=3 /OfflinePolicy=0 /NORESTART

This example instructs the installer to configure the PingID integration for Windows login, with the following settings:

Run the installer executable, located in the Downloads folder.
Do not display the background window and installation progress window (/VERYSILENT parameter).
Do not display message boxes and prompts (/SUPPRESSMSGBOXES and /SP- parameters).
Retrieve settings from the organization’s pingid.properties file, located in the Downloads folder (/orgSettingsFilePath parameter).
Send the log output to a customized destination (/LOG parameter).
Allow PingID Mobile App and FIDO2 security key for offline (manual) authentication (/OfflineAuthType parameter). At least one manual authentication type must be paired for the user to authenticate (/OfflinePolicy parameter).

Do not automatically restart the machine at the end of the installation process (/NORESTART parameter).

The command-line parameters are described in the following table.

Parameter Description

/SILENT

If a restart is necessary and the /NORESTART command isn’t used, it prompts with a Reboot now? message box. When using this parameter, the installation progress window is displayed.

/VERYSILENT

If a restart is necessary and the /NORESTART command isn’t used (see below), it reboots without asking. When using this parameter, the installation progress window is not displayed.

/SP-

Disables the This will install… Do you wish to continue? prompt at the beginning of the installation.

/SUPPRESSMSGBOXES

Instructs the installer to suppress message boxes. It only has an effect when combined with /SILENT or /VERYSILENT. The default response in situations where there’s a choice is:

Yes in Keep newer file? situations.
No in File exists, confirm overwrite situations.
Abort in Abort/Retry situations.
Cancel in Retry/Cancel situations.
Yes (continue) in DiskSpaceWarning, DirExists, DirDoesntExist, NoUninstallWarning, ExitSetupMessage, and ConfirmUninstall situations.
Yes (restart) in FinishedRestartMessage and UninstalledAndNeedsRestart situations.

/LOG=<Full output log filepath>

/LOG without an assigned value causes the installer to create a log file in the user’s TEMP directory, detailing file installation and actions taken during the installation process.
/LOG=<Full output log filepath> allows you to specify a fixed path or filename to use for the log file. If a file with the specified name already exists, it is overwritten. If the file cannot be created, the installer aborts with an error message.

/orgSettingsFilePath=<Full pingid.properties filepath>

The full filepath of the PingID properties file. For example, C:\Users\admin\Downloads\pingid.properties. The PingID properties file is referenced from this location during the installation process. It is mandatory to specify either:

/orgSettingsFilePath

Or all of the following parameters:

/orgAlias
/orgKey
/authenticatorAddress
/idpUrl
/token

If any of the above parameters are specified, and /orgSettingsFilePath is also specified on the command line, then the values are retrieved from the pingid.properties file only, and the values of these other parameters specified on the command line are ignored.

/orgAlias=<organization’s alias string>

The organization’s alias. This value is an entry in the PingID properties file. If the /orgSettingsFilePath parameter is not specified, it is mandatory to provide the /orgAlias parameter. If both the /orgSettingsFilePath and /orgAlias are specified, the value is retrieved from the pingid.properties file, and the value of the /orgAlias parameter is ignored.

/orgKey=<organization’s key string>

The organization’s base64 key. This value is an entry in the PingID properties file. If the /orgSettingsFilePath parameter is not specified, it is mandatory to provide the /orgKey parameter. If both the /orgSettingsFilePath and /orgKey are specified, the value is retrieved from the pingid.properties file, and the value of the /orgKey parameter is ignored.

/authenticatorAddress=<URL of PingID data center>

The URL of the PingID data center to which the organization is associated. It is the URL that is listed on the line in the pingid.properties file that begins with authenticator_url=. If the /orgSettingsFilePath parameter is not specified, it is mandatory to provide the /authenticatorAddress parameter. It is ignored if /orgSettingsFilePath is also specified.

When the /orgSettingsFilePath=<Full pingid.properties filepath> parameter is not supplied, the /authenticatorAddress value defaults to the North America data center. Administrators of organizations using the Europe or Australia and New Zealand data centers should ensure that they provide the relevant /authenticatorAddress value on configuration.

/idpUrl=<URL of server used for PingID API requests>

URL of the server used for PingID API requests. Take this value from the idp_url entry in the PingID properties file. If the /orgSettingsFilePath parameter is not specified, it is mandatory to provide the /idpUrl parameter. It is ignored if /orgSettingsFilePath is also specified.

/token=<API key identifier>

The identifier of the API key. This value is an entry in the PingID properties file. If the /orgSettingsFilePath parameter is not specified, it is mandatory to provide the /token parameter. It is ignored if /orgSettingsFilePath is also specified.

/proxyAutoDetect=<0 or 1>

Automatically detect the proxy settings. Possible values:

0 = Disabled
1 = Enable automatic detection of proxy settings

/scriptProxyAddress=<URL>

When the organization uses a PAC script for automatic proxy configuration, the/scriptProxyAddress parameter should be specified using the http:// or https:// convention. /scriptProxyAddress is the proxy script URL, for example, http://proxy.company.com:8083//proxy.pac.

/proxyAddress=<proxy’s URL>

When the connection is behind a proxy, the /proxyAddress parameter must be specified using the http:// or https:// convention.

/proxyAddress is the URL address of the proxy, for example, http://1.1.1.1:8080.

If the proxy requires credentials for authentication, the /proxyUserName and /proxyPassword parameters must be specified.

/proxyUserName=<proxy’s username>

When the connection is behind a proxy, and the proxy requires credentials for authentication, the /proxyUserName and /proxyPassword parameters must be specified.

The proxy’s username must be supplied as the value of the /proxyUserName parameter.

/proxyPassword=<proxy’s password>

When the connection is behind a proxy, and the proxy requires credentials for authentication, the /proxyUserName and /proxyPassword parameters must be specified.

The proxy’s password must be supplied as the value of the /proxyPassword parameter.

/proxyBypassList=<comma-separated list of IP addresses or DNS names>

The /proxyBypassList option can be used to specify that the communication with PingFederate should not go through the proxy that you configured. The value should be a list of one or more computers, separated with commas. The format can be domain name or IP address. For example, /proxyBypassList="pingfed.example.com" or /proxyBypassList="pingfed.example.com,250.15.147.17".

/ignoreConnectionErrors

The installer attempts to address the PingID authenticator heartbeat as an initial part of the installation flow, to confirm connectivity. When there is no response, the installer ends the flow with an error status, before installing any of the elements. The /ignoreConnectionErrors parameter may be used to bypass this status, and to continue the installation, even without connectivity.

/authenticationType=<0, 1 or 2>

/authenticationType configures the installation for when to apply PingID authentication on logins via the PingID integration for Windows. Possible values:

0: Both RDP and local logins (default, when not specified).
1: Only RDP logins.
2: Only local logins.

Any other value causes the installation to abort.

/excludeLocalUsers=<0 or 1>

/excludeLocalUsers configures whether to apply PingID authentication to local user logins. Possible values:

0: Local users must authenticate with PingID.
1: Disable PingID authentication for local users.

This parameter is now replaced by /excludeLocalAccounts and /excludeMicrosoftAccounts.
If 1, /excludeLocalUsers is set to 1, /excludeLocalAccounts and /excludeMicrosoftAccounts are automatically set to 1.
Domain users are always required to authenticate using PingID.

/excludeLocalAccounts=<0 or 1>

/excludeLocalAccounts defines whether to apply PingID authentication to local user logins:

0: Use PingID authentication for local user logins as well
1: Do not use PingID authentication for local user logins

/excludeMicrosoftAccounts=<0 or 1>

/excludeMicrosoftAccounts enables you to include or exclude Microsoft accounts used to access the Microsoft devices and services associated with a specific user.

0:Apply PingID authentication to Microsoft accounts.
1: Do not apply PingID authentication to Microsoft accounts.

/offlineAuthType=<0, 1, 2 or 3>

The /offlineAuthType specifies whether to allow PingID offline (manual) MFA, and defines the manual authentication methods that can be used. Possible values:

0: Do not allow MFA for offline authentication.
1: Allow offline MFA using PingID mobile app only.
2: Allow offline MFA using a FIDO2 security key only.
3: Allow offline MFA using either PingID mobile app or a FIDO2 security key.

This parameter is only available when installing PingID integration for Windows login v2.3 or later.

/RSA_PADDING=<oaep or none>

Use oaep to specify that OAEP padding should be used in the encryption for offline authentication (default).
If you do not want to use OAEP padding for offline authentication, use none.

/offlinePolicy=<0, 1>

/offlinePolicy configuration defines whether it is possible to bypass MFA if the user is offline. Options available for this parameter depend on the values selected in the /offlineAuthType parameter as follows:

If /offlineAuthType=0: offline (manual) authentication is not allowed and the /offlinePolicy options are:
- 0: The user is blocked.
- 1: PingID bypasses MFA during sign on.
If /offlineAuthType=1, 2, or 3: offline (manual) authentication is allowed and /offlinePolicy options are:
- 0: At least one allowed authentication method must be paired for the user to authenticate with offline MFA, otherwise the user is blocked.
- 1: If the user does not have at least one allowed authentication method for offline authentication paired with their account, PingID bypasses MFA during login.

This parameter is only available when installing PingID integration for Windows login 2.3 or later.

/domainPostfix=<@organization’s domain name>

/domainPostfix configures the installation to append the value supplied in this parameter, to the username at login time. A suffix, such as @domain.com, can be defined, however, a prefix, such as domain\, cannot be defined.

Enter the leading "@" before the domain name, for example [.parmname]/domainPostfix=@somewhere.com. This parameter has a maximum length of 50 characters, including the leading "@".

/MultipleDomain=<0 or 1>

/MultipleDomain allows the user to log in from multiple domains. This option is available with PingID for Windows login 2.2 and later. Options include:

0: Use of multiple domains is not permitted. (default)
1: Multiple domains are permitted. This option should not be used when /usernameMapping is set to None and a /domainPostfix is not specified.

/usernameMapping==UPN/SAM/SID/UserName/None

Select the attribute that you want to use to identify the user. The examples show how the username is mapped in PingID

None (default): Use the legacy username parsing convention. This can be either with or without /domainPostfix. Example:
- /domainPostfix set to @domain.com: jsmith@domain.com
- /domainPostfix not specified: jsmith

If you don’t specify /domainPostfix, do not set the /MultipleDomains parameter to 1.
This option isn’t recommended in environments with multiple domains or environments where PingID is also used to sign on locally.

SID: Use the objectSID. For example, S-1-5-21-668608636-2615149724-2645577550-1112
UPN: Use the userPrincipalName. For example, jsmith@domain.com
SAM: Use the Domain Name as prefix, or the computer name when logged in locally, and then the SAM Account Name. For example, DOMAIN\jsmith
UserName: Use the SAM Account Name only. For example, jsmith

/DIR=<installation destination folder’s full filepath>

The default installation location for the PingID integration for Windows login is C:\Program Files\Ping Identity\PingID\WindowsLogin. If you want the installation in a different folder, specify the /DIR parameter with the destination value.

/PingFedAddress=<baseurl>

The PingFederate Base URL used to integrate PingID for Windows login through PingFederate. This field must be included when integrating through PingFederate, as in the following example.

/PingFedAddress=https://10.132.102.92:9031

/CPWhiteList ={CP_GUID1};{CP_GUID2}

Enables you to exclude one or more credential providers that are not PingID credential provider (CP) from being filtered out by PingID integration with Windows login. Enter the credential provider GUID for each credential provider that you want to exclude, separated by a semicolon. PingID MFA does not work with any credential provider that is on the CP allow list.

/thirdPartyCredentials=<0 or 1>

Enables integration with a third party credential provider, such as McAfee Drive Encryption credential provider. Options include:

0: Do not integrate (default).
1: Integrate with McAfee Drive Encryption credential provider.

/HttpRequestTimeout=<timeinms>

Defines the HTTP request timeout value. Possible values between 1000-30000 ms.

The value configured for HTTP Timeout does not influence the timeout for embedded browser requests.

/NORESTART

Prevents the installer from restarting the system following a successful installation.

The /NORESTART parameter is not an override. In some cases, the operating system (OS) will still require a restart to proceed with installation because of events like the OS installing a newer version of software, such as Visual C++ Runtime. If a restart is required, the installation logs will display the following:The computer needs to be restarted before the setup can continue. Please restart the computer and run the PingID setup again.

The /NORESTART parameter allows the user to continue working without restarting their machine. Windows login client is not fully installed until the machine is restarted. To prevent issues when the user locks their machine (prompting Windows login client to start functioning), is recommended that the user restart their machine as soon as possible after the installation.

If the /NORESTART parameter is omitted, a successful installation automatically triggers a machine restart.

/DeprecatedSecurityKeys=<Allow, Inform, or Delete>

In version 2.8 of the Windows login integration, an improved implementation was introduced for the use of security keys while offline. The /DeprecatedSecurityKeys parameter allows you to specify how PingID should relate to the security keys paired previously:

Allow: Allow users to continue using these keys (this option isn’t recommended)
Inform: Allow users to continue using these keys, but inform them that these keys should be manually deleted
Delete: Automatically delete the keys that were paired before the change was introduced

If the /DeprecatedSecurityKeys parameter is omitted, the default behavior is Inform.

/AllowFullPermissionsPropertiesFile

If you include the /AllowFullPermissionsPropertiesFile option during installation, PingID will allow you to use the full-permissions properties file (rather than the restricted-permissions properties file intended for use with Windows login). However, it is strongly recommended that you refrain from doing so. Using the full-permissions properties file with Windows login is a security risk (for details, see CVE-2022-23717).

/SkipMFAGracePeriod

Include /SkipMFAGracePeriod if you want to define a period following authentication during which the user isn’t asked to authenticate again if they lock their computer. The maximum period is 15 minutes. The period is defined in seconds so the range of values you can use is 1-900.

Use this option with caution because it leaves the computer with a lower level of protection for the defined period.

Result:

The next time the user signs on to the Windows machine, they must authenticate with PingID.

Optional: The downloaded pingid.properties file can be deleted once the installation has completed.

The OrgData1, OrgData2, … fields in the HKEY_LOCAL_MACHINE\SOFTWARE\Ping Identity\PingId\PingIdCredProv registry are encrypted and should not be edited.
To verify the installation was successful, test that the user can sign on to the Windows machine using their password and PingID MFA.

PingID Administration Guide