Connect through PSM for SSH
This topic describes transparent connections to SSH target systems through PSM for SSH.
Overview
The Privileged Session Manager for SSH (PSM for SSH) enables you to connect to remote SSH systems and devices with a native user experience through any SSH client, such as plink, PuTTY, SecureCrt.
You require the Use accounts and List accounts permissions in the Safe to connect transparently to remote machines.
You can authenticate to the Vault through PSM for SSH using the following methods:
- CyberArk password
- LDAP
- RADIUS including Challenge-Response
- SSH Key
- Smart card authentication
For information about configuring authentication methods that will be available for PSM for SSH connections in your environment, refer to Authentication Methods.
To use SSH Key or Smart card with MFA caching in Integrated mode, you must have SSH 7.8 or higher installed on the PSM for SSH machine. |
PSM for SSH Command
This section describes how to access target machines using the PSM for SSH commands.
PSM for SSH can be used by any ssh client using one of the following syntaxes:
<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:
<ssh client> [-t] [-i <PrivateKeyFile>] [-L <LocalPort>:127.0.0.1:<TunnelingServerPort>] <VaultUser>@<TargetUser><DomainAddress>@<TargetAddress><TargetPort>[#<ForwardPort>][+ticketid+<TicketID>][+ticketingsystem+<TicketingSystem>]@<ProxyAddress> [<Command>] |
or:
<ssh client> [-t] [-i <PrivateKeyFile>] [-L <LocalPort>:127.0.0.1:<TunnelingServerPort>] "|<VaultUser>@<TargetUser><DomainAddress>@<TargetAddress><TargetPort>[#<ForwardPort>][|ticketid|<TicketID>][|ticketingsystem|<TicketingSystem>]@<ProxyAddress>" [<Command>] |
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.
<ssh client> [-t] [-i <PrivateKeyFile>] [-L <LocalPort>:127.0.0.1:<TunnelingServerPort>] +vaultuser+<VaultUser>+targetuser+<TargetUser>[+domainaddress+<DomainAddress>]+targetaddress+<TargetAddress>[+targetport+<TargetPort>][+forwardport+<ForwardPort>][+ticketid+<TicketID>][+ticketingsystem+<TicketingSystem>]@<ProxyAddress> [<Command>] |
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.
Parameter name | Alias |
---|---|
vaultuser | vu |
targetuser | tu |
domainaddress | da |
targetaddress | ta |
targetport | tp |
forwardport | fp |
ticketid | ti |
ticketingsystem | ts |
Following is an example syntax using aliases:
<ssh client> [-t] [-i <PrivateKeyFile>] [-L <LocalPort>:127.0.0.1:<TunnelingServerPort>] +vu+<VaultUser>+tu+<TargetUser>[+da+<DomainAddress>]+ta+<TargetAddress>[+tp+<TargetPort>][+fp+<ForwardPort>][+ti+<TicketID>][+ts+<TicketingSystem>]@<ProxyAddress> [<Command>] |
<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.
For a full description of the parameters used in this syntax, see PSM for SSH Parameters.
The following table explains the parameters used above.
Parameter |
Description |
Required |
||||||
---|---|---|---|---|---|---|---|---|
-t |
Displays the terminal of the target machine on the user's local screen. |
No |
||||||
[-i <PrivateKeyFile>] |
The path of the file from which the private key for SSH key authentication is read. This is an optional parameter and must be specified when SSH key authentication is used. For more information about this parameter and the different ways to specify private SSH keys, refer to SSH documentation. For information about SSH key authentication to the Vault, refer to Authenticate to the Vault through PSM for SSH using a Private SSH Key. |
No |
||||||
Integrated mode: [-L <LocalPort>:127.0.0.1:TunnelingServerPort] Non-integrated mode: [-L <LocalPort>:127.0.0.1: |
A standard SSH parameter that enables port forwarding setup (SSH tunneling). For details, see SSH Tunneling for PSM for SSH. |
No |
||||||
<VaultUser> |
The name of the user running this command. Support of @ character. Your user name may include one @ character. For example, if your user name is john@myDomain, then the @ character in your user name is supported. Any additional @ characters are not supported. |
Yes |
||||||
<TargetUser> |
The name of the account that will be used on the target system. For example, root. Note: This parameter is case sensitive.
|
Yes |
||||||
<DomainAddress> |
Value this field according to your environment:
Note: This parameter is case sensitive. |
No |
||||||
<TargetAddress> |
The address of the target system in any of the following formats:
|
Yes | ||||||
<TargetPort> |
The connection port used to access the system. If this is not specified in the account properties, it will be taken from this parameter’s value. If neither of these ports is specified, the default port is used.
The protocol (SSH or Telnet) is set according to the specified port. |
No, but if you are using the SSH tunneling (port forwarding) flow this field is required to be valued with 22. |
||||||
<ForwardPort> |
The port of the target machine where data transferred through the tunnel is forwarded. This is the same value as the <ForwardPort> specified above, and is only relevant for SSH tunneling. |
No |
||||||
<TargetPassword > |
The password of the target account. |
No |
||||||
<ProxyAddress> |
The IP address or DNS of the PSM for SSH machine. For example, 1.1.1.1 or ‘myhost’. |
Yes |
||||||
<TicketID> |
The identifier generated for user by a ticketing system. |
No |
||||||
<TicketingSystem> |
The name of the ticketing system. |
No |
||||||
<Command> |
The command that will be executed on the target machine. For more information, refer to Remote SSH Command Execution through PSM for SSH. |
No |
Authenticate to the Vault
Authenticate to the Vault through PSM for SSH using a password
To connect to your target systems through PSM for SSH while authenticating with a password (CyberArk, LDAP or RADIUS):
1. | At a command line, run the command to access a target machine through PSM for SSH. |
<ssh client> <VaultUser>@<TargetUser>#<DomainAddress>@<TargetAddress>#<TargetPort>@<TargetPassword>@<ProxyAddress> |
2. | You will automatically be prompted for your Vault password and any parameters, mandatory or optional, that you did not specify in the command line. |
In RADIUS authentication, if the RADIUS server is configured to use challenge-response authentication, you will be requested to enter additional logon information, such as additional authentication information from an external token. Only once this additional information is verified, will you be able to access the target system. |
Examples
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>). |
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>). |
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.
Authenticate to the Vault through PSM for SSH using a Private SSH Key
You can connect to target systems through PSM for SSH by authenticating to the Vault with a private SSH key file. This key can be provided with any standard SSH tool or client configuration. A corresponding public SSH key must be assigned to your user in the Vault to allow authentication.
Users can be assigned one or more public SSH keys that are kept for them in the Vault or in the LDAP directory. If one of these keys matches the private SSH key provided by the user during authentication, the connection through PSM for SSH will be approved and the user will be able to access their target system.
Public SSH keys can be managed either in LDAP, or in the Vault. For further information, see Managing Users' Public SSH Keys for Vault Authentication.
-
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.
-
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.
Authenticate to the Vault through PSM for SSH using a Smart Card
You can connect to target systems through PSM for SSH by authenticating to the Vault with a certificate. The certificate can be stored on a smart card such as CAC or PIV cards, or another form factor that will hold the certificate. Alternatively, soft certificates may also be used.
To use smart card authentication, connect with a client that supports migrating certificates to SSH keys, such as Putty CAC.
As with regular SSH key authentication, a public SSH key that corresponds to your certificate must be assigned to your user in the Vault to enable authentication.
For details, see Managing Users' Public SSH Keys for Vault Authentication.
Remote SSH Command Execution through PSM for SSH
In many work environments, it is preferable to give users limited permissions to sensitive servers, for both security reasons and automation purposes.
With remote SSH command execution, administrators can execute specific commands through PSM for SSH without opening an interactive session on the target system. The session is automatically closed after the command's execution.
You can execute commands remotely on target machines over SSH from your local machine through PSM for SSH, using the standard SSH command in the following syntax:
<ssh client> [-t] <VaultUser>@<TargetUser>#<DomainAddress>@<TargetAddress>#<TargetPort>@<TargetPassword>@<ProxyAddress> <Command> |
-
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
If your administrator set the InstallCyberArkSSHDparameter to Integrated during the PSM for SSH installation the following is not supported:
If your administrator set the InstallCyberArkSSHD parameter to Integrated during the PSM for SSH installation, it is not necessary to add the -t. |
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.
Run SSH tunneling on Command
With the SSH tunneling on command feature, you can open a secure tunnel and run a specific command on a single line.
To run a command on a remote machine through an SSH tunnel.
ssh -L <LocalPort>:localhost:<ForwardPort> <VaultUser>@<TargetUser>@<TargetAddress>#sshPort#<ForwardPort> command
The following is an example of the SSH tunnel command.
ssh -L 8000:127.0.0.1:55555 PSMPTestUser@root@10.20.67.37#22#[8000@10.20.66.248|mailto:8000@10.20.66.248] nc -l 8000
Automation Tools Access to *NIX machines through PSM for SSH
With remote SSH commands, you can automate command execution through PSM for SSH on a single target or multiple targets using scripts or automation tools. You can run scripts authenticating with your private SSH keys stored in the Vault (which in turn can be protected and stored securely on a smart card device).
CI/CD tools such as Jenkins or Ansible can also be used to run SSH commands, scripts and playbooks.
Verify that you are correctly configured. For details, refer to Configure Automation Tools Access to *NIX machines through PSM for SSH.
To use Jenkins, replace the <TargetUser>@<TargetAddress> with the PSM for SSH syntax in the job configuration, as shown in Option 1.
For Ansible to interact with the target via PSM for SSH, use the PSM for SSH syntax shown in Option 1.
Copy files securely through PSM for SSH
You can use native SFTP clients, such as WinSCP and FileZilla, or the SCP or Rsync command from your desktop to securely transfer files through PSM for SSH.
Native SFTP client
On the PSM for SSH Server and target machines, ensure that the /etc/ssh/sshd_config file is configured for SFTP usage with the following line uncommented:
subsystem sftp /usr/libexec/openssh/sftp-server
Changing this file requires an sshd service restart.
Do the following to use a native SFTP client to securely transfer files through PSM for SSH:
Field |
Desription |
||
---|---|---|---|
File protocol |
SFTP |
||
Hostname |
The IP address or DNS of the PSM for SSH server through which you want to establish your connection. |
||
Port number |
Default port is 22 |
||
User name |
Set the username using the standard PSM for SSH syntax parameters according to the PSM for SSH syntax:
For a list of valid parameters and their descriptions, see PSM for SSH Parameters |
In the example below, John, a vault user, connects as the root user to the target machine, 10.10.10.5, through a proxy machine with the address of 10.10.10.200. |
Copy files with SCP
You can use the SCP command to securely transfer files through PSM for SSH. When using SCP through PSM for SSH, PSM for SSH will not prompt you for any required parameters that you do not specify. Make sure that you specify all mandatory parameters in the command.
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 |
Copy files with Rsync
You can use the Rsync command to securely transfer files through PSM for SSH.
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/ |
Limitations
-
Command access control does not apply on SFTP sessions (This is also true for InstallCyberArkSSHD = Integrated)
-
Accounts that require a logon account are not supported.
-
Video recording for SFTP sessions is not supported.
If your administrator set the InstallCyberArkSSHD parameter to Yes or No the following limitations apply:
- RADIUS challenge-response is not supported
- Reason for access is not supported
- Integration with enterprise ticketing systems is not supported
Specify a reason for accessing accounts through PSM for SSH
A rule in the Master Policy determines whether users can only retrieve passwords or SSH keys after they specify a reason that explains why they need to retrieve them. If the rule is active, the user is prompted to provide the relevant information before the remote session begins.
When copying files through PSM for SSH , users will not be prompted to specify a reason. If your administrator set the InstallCyberArkSSHD parameter to Integrated, you are prompted if you use SCP. |
Connect through PSM for SSH with Active Directory Users
Users can connect to a UNIX machine through PSM for SSH using their AD credentials. This automatically synchronizes their AD user with a corresponding user in the Vault.
Use the following syntax to access the target machine using AD Bridge capabilities:
<ssh client> <VaultUser>@<TargetAddress>#<TargetPort>@<ProxyAddress> |
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.
If this user does not exist in the Vault, it will be created transparently according to its AD credentials. For more information, refer to AD bridging through PSM for SSH. |