SSH Terminal Administration

Introduction

This document discusses using an SSH terminal with DelineaSecret Server.

Feature Summary

• Connect using SSH to a terminal hostname and port to log in to terminal and run commands

• Display custom terminal banner after successful connection

• Display available commands on successful login (display again with man command)

• Log in to the terminal as a Secret Server user (SSH Proxy must be enabled)

• Can set an inactivity timeout. Can be set to disabled or with a two-minute minimum.

• Start a terminal connection and launch in a single line. For example:

  ssh <user>@<ss_ip> -t launch <secret_id>

• Use two-factor authentication (2FA) for access (optional)

• Use the SSH terminal interface to Secret Server for viewing and launching secrets

• Use these commands:

  • Man command to display detailed command description
  • Search command to display matching secrets
  • Cat command to display secret details of with specified secret ID
  • Launch command to begin a Proxy launch session with specified secret ID

• Use up and down keystrokes for command history

• Supports custom SSH command menus and session recording logging

Requirements

System Requirements

• Secret Server 10.7.000000 Secret Server
• Secret ServerProfessional or Platinum Edition license

Recommended

RabbitMq Site Connector

Secret Server Permission Requirements

Admin:

• Administer Configuration
• Administer Proxying Configuration
• View Configuration
• View Proxying Configuration

User: View Secret

Configuring SSH Terminal

Enabling SSH Terminal on Secret Server

1. Prerequisites:

   • Must meet Admin permission requirements (see Secret Server Permission Requirements)
   • Secret ServerProfessional or Platinum Edition license

2. Navigate to Secret Server > Admin > Proxying.

   

3. Click the Edit button.

4. Type your SSH proxy configuration settings (see Configuring SSH Proxies for Launchers):

   1. Enable SSH Proxy (required to use SSH terminal).

   2. (optional) Enable Proxy New Secrets by Default.

   To launch a secret via the terminal, the secret must have proxy enabled. Only SSH-based credentials can be launched in the terminal.

   3. Click to enable SSH Terminal.

   4. (optional) Customize the Terminal banner for your environment.

   5. (optional) Click to enable Terminal Inactivity Timeout (in seconds).

   6. The resulting settings should look something like this:

      

5. Specify the IP address for nodes (and engines) that will run SSH proxy:

   1. Navigate to Admin > Proxying > Nodes.

   2. Set the SSH Public Host. This is the public hostname or IP that the client launcher connects to. In most cases, this is the same as the SSH bind address; however, there are cases where the public IP or host differs from the private IP that Secret Server should bind to, such as NAT or Amazon EC2 instances.

   3. Set the SSH Bind IP Address. This defaults to (0.0.0.0). The IP Address of the network adapter that the Secret Server SSH listener should bind to. This should not be localhost or 127.0.0.1. If you are not sure which bind IP address to use, you may use 0.0.0.0, which binds to all IPv4 interfaces on the machine.

Enabling Terminal on Secret Server Distributed Engine

SSH terminal can also run on each proxy-enabled distributed engine (DE) site.

1. Go to Admin > Proxying > Sites.

2. Click to select Proxy Enabled.

3. Type an SSH Port.

4. Go to Admin > SSH Proxy > Engines.

5. Type the Hostname and IP Address (description above).

6. Type the SSH Bind Address (description above).

Logging into the SSH Terminal

1. From any SSH terminal, connect to hostname or IP address and port, as specified in the SSH Proxy Configuration page. Use the DE hostname or IP if connecting to an engine. Examples:

   ssh 127.0.0.1 -p 22

   ssh user54@127.0.0.1 -p 22

2. If not provided in the SSH connect command, enter your Secret Server username and password at the Login as: prompt.

3. If successful, you will see the terminal banner displayed, along with a list of available commands.

Increasing Maximum Concurrent Logins for Users

Logging in to SSH terminal counts against the number of concurrent Secret Server sessions a user is allowed. For example, if Maximum concurrent logins per user is set to "1" and the user john.smith is logged into the Secret Server Web user interface, then john.smith logs into SSH terminal, his first Web session will end, and he will have to log in again to use the Web user interface.

To increase the maximum concurrent logins per user:

1. Go to Admin > Configuration. The Configuration page appears.

2. Click the Login tab.

3. Click the Edit button at the bottom of the page. The page becomes editable.

4. Click the Maximum concurrent logins per user dropdown list and select the desired number.

5. Click the Save button.

SSH Terminal Login with Two Factor Authentication

SSH terminal is considered a Web service and can be used with two factor authentication (2FA). To enable 2FA for terminal:

1. Follow the steps under Two-Factor Authentication to set up 2FA.

2. Go to Admin > Configuration > Login > Require Two Factor for these Login Types and select one of these:

   • Website and Web Service Login

   • Web Service Log on Only

3. Enable 2FA on the Secret Server user by going to Admin > Users > Select a user > Edit > Two Factor and select the 2FA option.

   FIDO2 authentication is not supported in this version of SSH terminal.

4. From any SSH terminal, connect to hostname or IP address and port, as specified in the SSH Proxy Configuration page. Use the distributed engine hostname or IP if connecting to an engine. Examples:

   ssh 127.0.0.1 -p 22

   ssh username@127.0.0.1 -p 22

5. If not provided in the SSH connect command, enter your Secret Server username and password at the Login as: prompt.

6. You will be prompted for a PIN or custom challenge message by your 2FA provider. Example:

   login as: duouser<Enter>

   Using keyboard-interactive authentication:

   duouser@127.0.0.1's password: uewori#$%tdtd<Enter>

   Using keyboard-interactive authentication:

   Pin Code: 3787<Enter>

7. If successful, you will see the terminal banner displayed, along with a list of available commands.

Escaping Special Characters

When manipulating secrets containing special characters, such as single quotes and double quotes, you must escape those characters in the command.

Example: To search for an item with a space in the name, put the name in single or double quotes:

search "My Secret" or search 'My Secret'

Example: To search for an item with a single quote embedded in the name, there are two options:

• Encase the term in double quotes:

  search "Bob's Secret"

• Escape the single quote with a backslash:

  search 'Bob\'s Secret'

Example: Similarly, to search for an item with a double quote embedded in the name, there are two options:

• Encase the term in single quotes:

  search '"Weird" Secret'

• Escape the internal double quotes with a backslash:

  search "\"Weird\" Secret"

Terminal Commands

man

Syntax

man [command name]

Description

Displays command help for specific or all commands. Man is short for manual.

Examples

man

Short help for all commands.

man cat

A detailed description of the cat command.

search

Syntax

search [-st] <search_text> [-f <folder_id>] [-fav] [-r] [-sf <search_field>] [-skip <skip_results>] [-s] [-t <secret_template_id>] [-take <max_results>]

Description

Returns a list of Secret Server secrets by keyword, which you can filter using several command-line switches.

Parameters

-st <search_text>

Required. Text to search for. -st is optional. Returns 25 results by default. Use -take to change from the default.

-f <folder_id>

ID of the secret folder to limit the search to.

-fav

Only search "favorite" secrets.

-r

Ignore restricted secrets in the search. Restricted secrets are included by default.

-s

Ignore subfolders in the search. Subfolders are included by default.

-sf <search_field>

ID of the secret field to limit the search to. Potential fields, which vary by secret template, can include the following examples:

• Address1
• Address2
• Address3
• Blog
• CardType
• City
• Combination
• Contact Number
• Country
• Email Address
• ExpirationDate
• Fax
• First Name
• FullName
• Home Phone
• Last Name
• Machine
• Mobile Phone
• Notes
• Number
• Password
• Pin
• PinCode
• Server
• SSN
• State
• Username
• Website
• Work Phone
• Zip

-skip <skip_results>

Skip this number of initial results. Useful for processing "pages" of results.

-t <secret_template_id>

Only search secrets based on the template with this template ID.

-take <max_results>

Take a total of only this number of results. Useful for processing "pages" of results. Defaults to 25 results.

Examples

search -st admin

Find a list of secrets matching "admin." Returns 25 results (the default).

search admin

Same search using alternate syntax. -st is not required.

search -st jones -fav

Find a list of "favorite" secrets matching "jones" in any field Returns 25 results (the default).

search admin -take 50

Outputs a list of secrets matching "admin", up to 50 results.

search Zardoz -take 50 - skip 50 -sf "Secret Name"

Find a list of secrets with "Zardoz" in the "Secret Name" field. Return 50 results, starting with the 51st secret found.

search admin -skip 25 -r

Find a list of secrets matching "admin" in any field. Return 25 results, which is the default. Skip the first 25 results. Ignore restricted secrets.

cat

Syntax

cat [-s|-id|-secret-id] <secret_id> [-c|-comment <comment_or_access_request>] [-t|-ticket <ticket_number>] [-ticketsystemid <ticket_system_id>]

Description

• Displays information on a secret. The available information depends on the secret's template. cat is short for concatenate.

• Catches access errors, such as "comment required" or "requires approval", and displays them on the terminal

• Audits "view" comments.

• Provides launch connection command instructions. Shows the correct launch parameter and a connection string (if the terminal connection and the site on the secret do not match).

Parameters

[-s|-id|-secret-id] <secret_id>

Required. The secret ID. Three optional switches.

[-c|-comment <comment_or_access_request>]

The text for the comment or access request.

[-t|-ticket <ticket_number>]

The ticket number for the request.

[-ticketsystemid <ticket_system_id>]

The unique ticket system ID.

Examples

cat 24

Display the contents of the secret with the ID 24. Only works after access is approved.

cat -id 24

Alternate syntax. Display the contents of the secret with the ID 24.

cat -id 25 -comment "Viewing this secret"

Add a "view" comment to, and then display the contents of the secret with the ID 25.

cat -id 26 -comment "Requesting view access to install software" -ticket 123 -ticketsystemid 2

Add an "access request" comment to the secret with the ID 26. Assign the request the ticket number 123 and the ticket system ID of 2 to that request.

launch

Syntax

launch [-s|-id|-secret-id] <secret_id> [-m|-Machine <machine_name>] [-c|-comment <view_comment_or_approval_request_reason>] [-t|-ticket <ticket_number>] [-ticketsystemid <ticket_system_id>]

Description

• Creates a proxy connection to the machine
• Secret must have proxy enabled
• Supports launch from secrets with private keys
• Audits launches

Parameters

[-s|-id|-secret-id] <secret_id>

Required. The secret ID. Three optional switches.

[-c|-comment <comment_or_access_request>]

The text for the comment or approval request.

[-m|-Machine <machine_name>]

Machine name for the launch. This may be required if a customized secret template does not contain a machine field or a launcher requires a machine entry on launch.

[-t|-ticket <ticket_number>]

The ticket number for the request.

[-ticketsystemid <ticket_system_id>]

The unique ticket system ID.

Examples

launch 24

Begins the SSH proxy session with the secret with the ID 24 and the specified credentials and machine. Only works after access is approved.

launch -id 24

Alternate syntax. Begins the SSH proxy session with the secret with the ID 24 and the specified credentials and machine. Only works after access is approved.

launch -id 25 -comment "Launching this secret"

Submits a "view" comment to the secret with ID 25. Begins the SSH proxy session with secret credentials and machine.

launch -id 26 -machine XYZ -comment "Requesting view to launch temporary sudo account for the XYZ machine"

Submits an "access request" comment to the secret with ID 26 on the machine XYZ with the ticket number 123 and ticket system ID 2.

Launching a Secret with the SSH Terminal

Launching a Secret on a Local Site

1. To launch, the secret must be:

   • Enabled for proxy (Secret Server > Secret > Security > Enable Proxy)
   • Shared with the terminal user

2. Log in to the terminal with Secret Server user credentials:

   

3. If the secret ID is unknown, search for the desired secret with the search command:

   

4. To view secret detail, get the secret ID from search results, and run

   cat <secret_id>

   

5. To launch the secret, enter the launch command as specified in the last line of secret details:

   launch <secret_id>

   

6. To exit the launch session and return to the terminal, type exit.

   

7. To exit the terminal session, type exit again.

Launching a Secret on a Distributed Engine Site

1. To launch, the secret must be:

   • Enabled for proxy (Secret Server > Secret > Security > Enable Proxy)

   • Shared with the terminal user

2. Log in to the terminal with Secret Server user credentials:

   

3. If secret ID is unknown, search for the desired secret with the search command:

   

4. To view secret detail, get the secret ID from search results, and run

   cat <secret_id>

   

5. Note that the connection is not made, and instructions are displayed for logging into another distributed engine terminal to launch the secret.

6. Note the suggested parameters in the Launch Instructions.

7. Type exit and press <Enter> to disconnect from the current session:

   

8. Open a new SSH session suggested parameters:

   ssh <secret_server_username>@<engine_hostname_or_ip> -p <Port> -t launch <secret_id>

9. Enter the password to log in, and the secret should immediately launch.

Launching a Secret upon Terminal Connection

1. To launch, the secret must be:

   • Enabled for proxy (Secret Server > Secret > Security > Enable Proxy)

   • Shared with the terminal user

2. If the secret ID and connection string is known, you can log in and immediately launch the secret with the following command:

   ssh <secret_server_username>@<hostname_or_ip> -p <Port> -t launch <secre_id>

3. If you do not know that connection string, log into terminal and run:

   cat <secret_id>

4. Look at the Launch Instructions at the end of secret details, and note the parameters.

SSH Terminal Launching with a Custom SSH Command Allowlist

Secret Server terminal can launch secrets with custom SSH Command restrictions. For detailed instructions on SSH command menus, please see Managing Superuser Privilege.

1. Go to Admin > See All. The Administration page appears.

2. Click the SSH Command Menus link. The SSH Command Menus page appears.

3. Click the Create New button.

4. Type a name, description and the SSH commands:

   

   Once one or more command menus have ben created, access can be controlled to individual Unix SSH secrets.

5. On the Security tab of a secret that can use a proxied SSH session, proxy must be enabled, as well as command menu restrictions. If Allow Owners Unrestricted SSH Commands is enabled, any user who is an owner of the secret has unrestricted use of the launched session. That is, that user is able to type in commands as in a normal SSH session. Additionally, other groups can be assigned the unrestricted role as well.

6. In the following example, the "admin" group is unrestricted, and everyone who is not in that admin group is restricted to only being able to run the allowlisted commands that are specified in the user command menu created above.

   

   When you click the Edit link:

   

   And click the dropdown list to select Allowlisted Commands:

   

7. A user who is subject to SSH command restrictions is presented with a screen similar to the following when launching this secret from Secret Server terminal:

   

   The user simply enters the number of the command menu to see available commands or types "?" to display the options again:

   

   Only the commands listed can be run by this user. The user can either enter the number of the command to be run, or the name of the command, which is the word to the left of the equal = sign. Other options are available (as shown) to navigate through the available command menus, display help, or exit the session.

SSH Terminal Launching with Session Recording

Secret Server SSH terminal launches also support session recording for session client or server data. When a user launches a secret with session recording enabled through SSH terminal, session data is available in the Secret Audit tab as session data.

To enable session recording:

1. Go to Admin > Configuration. The Configuration page appears.

2. Click the Session Recording tab.

3. Click the Edit button at the bottom of the page. The page becomes editable.

4. Ensure the Enable Session Recording check box is selected.

5. Modify other settings as desired.

6. Click the Save button.

To enable session recording on a secret:

1. Open a secret.

2. Click the Security tab.

3. Click the Edit link to the right of the Session Recording Enabled setting. The Edit Security popup page appears.

4. Click to select the Session Recording Enabled check box.

5. Click the Save button.

To view session data following a terminal secret launch:

1. Open a secret.

2. Click the Audit tab.

3. Find the LAUNCH action in the table.

4. Click the View SSH Session Log link.

SSH Key Pairs for Terminal

Overview

SSH key pairs allow users to authenticate to Secret Server terminal without using a password. The user generates a key pair in Secret Server, at which time the private key can be downloaded by the user locally in the format they require. The key pair generation process is the only time the private key will be provided to the user. If this private key is lost, the user must log back into Secret Server and generate a new public/private key pair.

Limitations

• Currently users can only authenticate to Secret Server using SSH keys by using Secret Server's SSH terminal.
• Only PuTTY and OpenSSH keys can be generated.

Enabling Users to use SSH Key Pairs to Authenticate

There are three requirements for enabling Public SSH Keys:

• SSH Proxy is enabled in Secret Server.
• SSH Terminal is enabled in SS.

• SSH key integration is enabled in SS's Configuration > Login settings. To do so:

  1. Unix Authentication Method: choose Public Key only, Password or Public Key or Password and Public Key to enable SSH key pair authentication.
  2. Once done, the admin can also set an optional expiration time frame for the public SSH keys, which applies to all users.

Once these 3 requirements have been met, users can use the main navigation to create SSH key pairs.

Creating SSH Key Pairs

An SSH key pair consists of a private key and a public key. Only the public key is stored in the user's settings—the private key downloaded during generation is not saved inside Secret Server and should only be available to the user, to remain secure.

During terminal login, if the user provides a private key for authentication, Secret Server validates the provided private key against the user's available (and enabled) saved public keys. If a key pair match is found, the authentication succeeds (or the next required authentication step, for example a password prompt, is shown).

For security reasons, only users can create their own SSH key pairs. However, Secret Server Administrators can deactivate any user's public SSH keys as follows:

1. Navigate to the Public SSH Keys page using the main navigation at the top right of the page.

2. Click the Create SSH Key button above the grid, then fill out the form in the popup page.

3. Click the Create SSH Key button in the popup. After a moment you will be able to save the private key.

Administering Public SSH Keys

1. Navigate to the User by going to Admin > Users.

2. Locate the user in the dropdown list and select it.

3. On the General tab click the Administer Public SSH Keys button. You can now deactivate the user's public SSH keys.

Using SSH Keys for Authentication (PuTTY Example)

1. In PuTTY, fill in the Session view to match your SSH proxy connection settings in Secret Server.

2. In the SSH > Auth section of PuTTY, add the private key file that was saved when generating the key in Secret Server.

3. You will be prompted to enter your passphrase for the key if one was set.

4. You will be prompted to enter your password if Unix Authentication Method also requires a password.