Connect through PSM for SSH

<ssh client> [-t] [-i <PrivateKeyFile>] [-L <LocalPort>:127.0.0.1:<TunnelingServerPort>] <VaultUser>@<TargetUser>[#<DomainAddress>]@<TargetAddress>[#<TargetPort>[#<ForwardPort>]]@<ProxyAddress>

 [<Command>]

• Parameters are separated by ‘@’.

• Required parameters are separated from optional parameters by ‘#’ (hash sign).

  You can customize the default delimiters that are used by PSM for SSH (‘@’, ‘#’). For example, you can change the ‘@’ delimiter to enable connections with a domain or other user names that include this character. For information about configuring PSM for SSH syntax delimiters see PSM for SSH Syntax Delimiter-Integrated .

• To use this syntax, the InstallCyberArkSSHD parameter must be set to Integrated. For more information, refer to InstallCyberArkSSHD.

The syntax described in Option 1 can be extended. This syntax starts with a general delimiter and can have additional parameters configured at the end. There are two preconfigured general delimiters: + and |.

For example:

or:

The additional parameters can be added in a +key+value form or |key|value form. In the above examples, ticketid is the key name of the parameter and <TicketID> is the actual value of the parameter.

Each parameter has its preconfigured name and some additional aliases. The full list of parameter names and aliases can be found in the description for Option 3.

In this option, you can provide all connection parameters in a +key+value form or |key|value form. Each parameter has its own preconfigured alias. The names and aliases can be used interchangeably.

The following table contains all possible parameter names with their aliases.

Following is an example syntax using aliases:

<ssh client> [-t] [-i <PrivateKeyFile>] [-L <LocalPort>:127.0.0.1:<ForwardPort>] <VaultUser> @<TargetUser>#<DomainAddress>@<TargetAddress>#<TargetPort>[#ForwardPort>]@<TargetPassword>@<ProxyAddress>

 [<Command>]

• Parameters are separated by ‘@’.

• Required parameters are separated from optional parameters by ‘#’ (hash sign).

  You can customize the default delimiters that are used by PSM for SSH (‘@’, ‘#’). For example, you can change the ‘@’ delimiter to enable connections with a domain or other user names that include this character. For information about configuring PSM for SSH syntax delimiters see PSM for SSH Syntax Delimiters-Original.

The following table explains the parameters used above.

To connect to your target systems through PSM for SSH while authenticating with a password (CyberArk, LDAP or RADIUS):

<ssh client> <VaultUser>@<TargetUser>#<DomainAddress>@<TargetAddress>#<TargetPort>@<TargetPassword>@<ProxyAddress>

SSH privileged SSO session

The following example initiates an SSH privileged SSO session. The command contains all the information that is required to log onto the target system through PSM for SSH.

ssh john@root@target.ciscorouter.com@psmp.proxymachine.com

In this example, a Vault user called john will access the Vault and retrieve an account for the root user on the target system, target.ciscorouter.com. As this command does not specify a port, the default port 22 and protocol SSH will be used.

John will be prompted for his Vault password so that PSM for SSH can retrieve information that is required to connect to the target machine. The account stored in the Vault for the target system is configured for Privileged SSO and contains the password or private SSH key that is required to access the target system. Therefore, the user will be logged on to the target system transparently without needing to specify any more credentials.

Telnet privileged SSO session

The following example initiates a Telnet privileged SSO session.

ssh john@root@target.ciscorouter.com#23@psmp.proxymachine.com

Similar to the previous example, a Vault user called john will access the Vault and retrieve an account for the root user on the target system, target.ciscorouter.com. However, this command specifies port 23, which indicates Telnet protocol.

John will be prompted for his Vault password so that PSM for SSH can retrieve information that is required to connect to the target machine.

As in the previous example for Privileged SSO, the account stored in the Vault for the target system contains the password or the private SSH key that is required to access the target system and the user will be logged on transparently without needing to specify any other credentials.

The following example initiates a non-privileged session.

ssh john@root@target.ciscorouter.com#2222@targetciscorootpass@psmp.proxymachine.com

In this example, a Vault user called John will access the Vault and retrieve an account for the root user on the target system, target.ciscorouter.com. This command specifies port 2222, so SSH protocol will be used.

This example shows a non-privileged SSO session, meaning that the account stored in the Vault for the target system is not configured for Privileged SSO and does not contain the password. Therefore, the password of the target system is specified in the command, targetciscorootpass. If this password is not specified in the command, the user is prompted for it so that PSM for SSH can complete the connection to the remote machine. John will also be prompted for his Vault password so that PSM for SSH can retrieve information that is required to connect to the target machine.

You can connect directly to a target machine with a UNIX domain/NIS account through PSM for SSH. To access target machines with a domain/NIS account, specify the domain machine in the command.

The following example shows how to access a target machines with a Domain/NIS account.

ssh john@root#mycompany.com@target.mycompany.com@psmp.proxymachine.com

In this example, a Vault user called john will access the Vault and retrieve a domain account for the root user in the mycompany.com domain to access the target system, target.mycomany.com.

John will also be prompted for his Vault password so that PSM for SSH can retrieve information that is required to connect to the target machine.

If the target user is not specified, you will be prompted for it and then can specify the target user and the domain machine as shown in the following example:

Target user is required (to use domain account, specify <target_user>#domain_address>).
Target user: root#mycompany.com

You can connect directly to a target machine with an SSH certificate through PSM for SSH. To access target machines with an SSH certificate, specify the name that identifies the group where your target system belongs in the command.

The following example shows how to access a target machine with an SSH certificate .

ssh john@root#production@target.mycompany.com@psmp.proxymachine.com

In this example, a Vault user called john will access the Vault and retrieve a short lived SSH certificate for the root user to access the target system, target.mycomany.com, which is part of the production group of target machines. For details, see Just in Time access with short-lived SSH certificates.

John will also be prompted for his Vault password so that PSM for SSH can retrieve information that is required to connect to the target machine.

If the target user is not specified, you will be prompted for it and then can specify the target user and the domain machine as shown in the following example:

Target user is required (to use domain account, specify <target_user>#domain_address>).
Target user: root#mycompany.com

If the SSH client supports the ability to pass the connecting user’s password, for example plink, you can specify the Vault password as the SSH password, as shown in the following example:

plink –pw <vault password> john@root@target.ciscorouter.com#2222@psmp.proxymachine.com

In this example, a Vault user called john will access the Vault and retrieve an account for the root user on the target system, target.ciscorouter.com. This command specifies port 2222, so SSH protocol will be used.

The account stored in the Vault for the target system is configured for Privileged SSO and contains the password. Therefore, it’s not necessary to specify the target password in this command. John’s Vault password is included in the command, so he will not be prompted for it.

1. At a command line, run the command to access a target machine through PSM for SSH.

   <ssh client> [-i <PrivateKeyFile>] <VaultUser>@<TargetUser>#<DomainAddress>@<TargetAddress>#<TargetPort>@<TargetPassword>@<ProxyAddress>

    

   The private SSH key can be provided with the –i option or with any standard SSH tool or client configuration.

2. You are prompted for any parameters, mandatory or optional, that you did not specify in the command line. If the SSH key authentication is successful, you will not be prompted for a password.

   If SSH key authentication was refused, and password authentication is allowed for SSH connections on the PSM for SSH server, you will be prompted for a password.

The following example initiates an SSH privileged SSO session using SSH key authentication.

ssh –i ~/.ssh/id_rsa john@root@target.ciscorouter.com@psmp.proxymachine.com

In this example, a Vault user called john will authenticate to PSM for SSH with a private SSH key stored in the ~/.ssh/id_rsa file. Then, he will access the Vault and retrieve an account for the root user on the target system, target.ciscorouter.com.

The account stored in the Vault for the target system is configured for Privileged SSO and contains the password or private key that is required to access the target system. Therefore, the user will be logged on to the target system transparently without needing to specify any more credentials.

As this command does not specify a port, the default port 22 and SSH protocol will be used.

• This functionality cannot be used when Commands Access Control is enabled.

• You can only use this functionality if the connection does not require a logon account.

To support the following workflows, make sure you specify -t in the syntax to display the remote terminal so that you can provide information when prompted:

• RADIUS challenge-response

• Reason for access

• Connection without specifying all mandatory syntax parameters

• Non-privileged SSO sessions without specifying the password in the syntax

• Integration with enterprise ticketing systems

The following example shows how to initiate an SSH privileged SSO session and execute a command on the target machine.

ssh john@root@target.ciscorouter.com@psmp.proxymachine.com 'service sshd restart'

In this example, a Vault user called john will access the Vault and retrieve an account for the root user on the target system, target.ciscorouter.com. As this command does not specify a port, the default port 22 and protocol SSH will be used. Once the session on the target machine has been initiated, the service sshd restart command will be executed and the session will be closed.

Use the following syntax to copy files securely from your local machine to a target machine:

scp <path-on-end-user-machine> <VaultUser>@<TargetUser>%<DomainAddress>@<TargetAddress>%<TargetPort>@<TargetPassword>@<ProxyAddress>:<path-on-target-machine>

Notes:   

• Parameters are separated by ‘@’.

• In SCP syntax, ‘#’ (hash) cannot be used as a delimiter. By default, required parameters are separated from optional parameters with '#' (hash). To use optional parameters in SCP, configure a different delimiter to replace the ‘#’ (hash). In the above syntax, '%' is used as a delimiter to separate required and optional parameters.

  For information about configuring PSM for SSH syntax delimiters see PSM for SSH Syntax Delimiter-Integrated or PSM for SSH Syntax Delimiters-Original.

For a complete explanation of the PSM for SSH syntax parameters, refer to PSM for SSH Parameters.

In the following example, a Vault user called john will connect as user root to the target machine, which is 10.10.10.5, through a proxy machine whose IP address is 10.10.10.200, and copy a file called readme.txt from the /home directory on the user’s local machine to the /tmp directory on the target machine.

scp /home/readme.txt john@root@10.10.10.5@10.10.10.200:/tmp

On your local machine, use the following syntax to copy files securely from a remote machine to your local machine:

scp <VaultUser>@<TargetUser>%<DomainAddress>@<TargetAddress>%<TargetPort>@<TargetPassword>@<ProxyAddress>:<path-on-target-machine> <path-on-end-user-machine>

Notes:   

• Parameters are separated by ‘@’.

• In SCP syntax, ‘#’ (hash) cannot be used as a delimiter. By default, required parameters are separated from optional parameters with '#' (hash). To use optional parameters in SCP, configure a different delimiter to replace the ‘#’ (hash). In the above syntax, '%' is used as a delimiter to separate required and optional parameters.

   

  For information about configuring PSM for SSH syntax delimiters see PSM for SSH Syntax Delimiter-Integrated or PSM for SSH Syntax Delimiters-Original.

For a complete explanation of the PSM for SSH syntax parameters, refer to PSM for SSH Parameters.

In the following example, a Vault user called john will connect as user root to the target machine, which is 10.10.10.5, through a proxy machine whose IP address is 10.10.10.200, and will copy all files and directories recursively from the /tmp directory on the target machine to the /home directory on the user’s local machine.

scp –r john@root@10.10.10.5@10.10.10.200:/tmp /home

Use the following syntax to copy files securely from your local machine to a target machine:

rsync <path-on-end-user-machine> <VaultUser>@<TargetUser>%<DomainAddress>@<TargetAddress>%<TargetPort>@<TargetPassword>@<ProxyAddress>:<path-on-target-machine>

In the following example, a Vault user called john will connect as user root to the target machine, which is 10.10.10.5, through a proxy machine whose IP address is 10.10.10.200, and copy the /tmp directory recursively from the user’s local machine to the /home directory on the target machine.

rsync -avzh -r /tmp john@root@10.10.10.5@10.10.10.200:/home/

On your local machine, use the following syntax to copy files securely from a remote machine to your local machine:

rsync <VaultUser>@<TargetUser>#<DomainAddress>@<TargetAddress>#<TargetPort>@<TargetPassword>@<ProxyAddress>:<path-on-target-machine> <path-on-end-user-machine>

In the following example, a Vault user called john will connect as user root to the target machine, which is 10.10.10.5, through a proxy machine whose IP address is 10.10.10.200, and will copy all files and directories recursively from the /tmp directory on the target machine to the /home directory on the user’s local machine.

rsync -avzh -r john@root@10.10.10.5@10.10.10.200:/tmp /home/

1. After running the command to access a target machine through the PSM for SSH, you will be prompted to type a reason for connecting. Specify the reason and press Enter.

   

2. The PSM for SSH will now retrieve the password or SSH key, and the reason you specified will be stored in the audit log.

You can use AD Bridge capabilities to provision users transparently on a target machine and connect to it through PSM for SSH.

The following example shows how to initiate a privileged session using AD Bridge capabilities.

ssh john@10.10.10.5@10.10.10.200

In this example, a Vault user called john will access the Vault and retrieve an account to access a machine whose IP address is 10.10.10.5 through a proxy machine whose IP is 10.10.10.200. If this user does not exist on the target machine, it will be created transparently and this user will be able to access the target machine through PSM for SSH.