Secrets User Guide

Overview of the secrets vault

Each room in Tehama has its own Secrets Vault.

The secrets vault for each room is used to provide secure storage of access credentials, secrets and firewall rules for room assets.

What is an asset?

An asset is a resource or service in your infrastructure (internal network, cloud, ...) that you want to access from your room. An asset may be local to a Desktop in your room, or located remotely.

Configuration for each asset must be added to your room's secrets vault in order to make it accessible from the Desktops.

What is a firewall rule?

See the firewall rules. When assets are added to the secrets vault, inferred firewall rules may be generated.

What is a secret?

There are three types of secrets.

  • Generic secrets that define static access credentials for a generic asset, (a resource or a service). These are stored directly in the vault.

    Generic secrets contain the IP address/port for the asset, if remote, along with username and password information.

    Firewall exceptions may be added for the IP address/port of the asset when the secret is first configured in the vault.

  • Secrets that define db 'roles', capable of generating dynamic, time-limited db-access credentials for a database server 'service' whose configuration is stored in the vault.

    One of these 'secrets' ('roles') defines how to create a role in a particular database server (a service) that is connected to through given connection information (ip, port, root user, password, etc). The service will also specify the lease (length of the lifetime) of an instance of the role.

    For example, a 'secret/role' may define the role of 'superuser' in a MySQL db, where the underlying service specifies that all instances of 'secrets/roles' defined for it will expire one hour after being instantiated.

    By selecting a 'secret/role' in the secrets vault, you generate a time-limited instance of the role defined by the 'secret/role'. The username and password for the newly generated instance are shown to the user. The instance will be deleted when its lifetime is over (when its lease has expired).

    Firewall exceptions may be added for the IP address/port of the database server (and possibly other elements) when it is first configured in the vault.

  • Secrets that define SSH credentials, capable of generating dynamic, time-limited SSH signed-certificates for a user, using a Certificate Authority (CA) key pair that has been stored in the vault.

    See the SSH Overview for background information.

    The public key of the CA key pair must be listed in the TrustedUserCAKeys on the server for which you wish to grant SSH access. The private key of the CA key pair is stored, encrypted, in the vault and is used to sign certificates for the user defined in the secret.

    Firewall exceptions may be added for the IP address/port of the targeted server when the CA key pair is first configured in the vault.


Accessing the secrets vault

The secrets vault is accessible from:

  • the Desktop Agent's SECRETS tab (in each Desktop instance) (full access)
  • the Tehama client's (Web UI) ROOMS tab
    • Under the CONFIGURE tab in the Secrets side-bar item (full access)
    • Under the WORK tab in the Secrets side-bar item (read-only access)

There are slight differences in the UI depending on whether you access it from the Desktop Agent or from the Tehama client.

This is the landing page for the secrets vault from the Desktop Agent:

Vault

The side-bar on the left of the page lists the different types of assets that can be stored in the secrets vault. Clicking on an item in the side-bar displays the list of assets of that type that are currently stored in the vault, and provides buttons to add or remove them.

This is the landing page for the secrets vault from the Tehama client, under the CONFIGURE tab:

Vault

The list in the centre of the page lists the different types of assets that can be stored in the secrets vault. Clicking on an item in this list displays the list of assets of that type that are currently stored in the vault, and provides buttons to add or remove them. Return to this landing page by clicking on the word "Secrets" in the breadcrumb at the top of the asset-type page.

NOTE: The breadcrumbs will be prefaced with "Secrets" when the interface is viewed from the Tehama client, but not when viewed from the Desktop Agent.


Configuring the secrets vault

The secrets vault is configurable from the Tehama client landing page. Click on the settings icon secrets vault settings icon found at the top right of the page. You will see the CONFIGURE SECRETS dialog.

Configure Secrets dialog

By default, users are allowed to copy credentials from the secrets vault from both the Tehama client (Web UI) and the Desktop Agent.

To disable access to credentials from the Tehama client, disable the "Allow copying of credentials" toggle. The users will still be able to access credentials from the Desktop Agent in any desktop associated with the room.


Managing Generic assets in the secrets vault

Folders for 'Generic' assets are simply containers used to group assets. These can be nested, each folder containing both assets and other folders.

The breadcrumb at the the top of page indicates where you are in the folder structure.

e.g.: If the breadcrumb reads GENERIC, then you are viewing the top-level.

e.g.: If the breadcrumb reads GENERIC > ACME ASSETS > SUB ASSETS, then you are viewing the "Sub Assets" folder found under the "Acme Assets" folder which is located at the top-level of the "Generic Assets".

To navigate to a folder in the current folder, click on the folder's name in the list. You will see the list of assets/folders added under that folder and the breadcrumb displayed at the top of the page will add the folder you selected to its end.

To navigate back, click on folder name in the breadcrumb where you wish to go. For example, to navigate back to the top-level, click on GENERIC in the breadcrumb. You will see the list of assets/folders added to the top-level.

Add a folder to generic assets

Navigate to the parent folder where you wish to add the new folder. (Generic asset folders can be nested.) Click on ADD FOLDER, enter a folder name, then click on CREATE. The new folder will appear in the list of generic assets for its parent folder.

Add a generic asset

Navigate to the folder in which you wish to add the asset.

Click on ADD ASSET, enter the following:

  • Asset Name
  • Username (optional - name of a user configured in the targeted service)
  • Password (optional - password for the user)
  • Select Yes or No for the question Would you like to display password in plaintext?
  • Description (optional)
  • If you choose to Include a firewall exception, enter:
    • IPv4 CIDR block (address of the service - note ip:port is added as a firewall exception)
    • Port (range or single port)

Click on CREATE, then the asset will appear in the list of assets/folders added under the folder.

View a generic asset

Navigate to the folder to which the asset was added. Click on the entry for the asset. The asset's information will be displayed. It can be copied. If you opted not to display the password in plaintext when creating the asset, clicking on the button COPY PASSWORD will copy the password to the clipboard.

Remove a generic folder or asset

Navigate to the folder or asset you want to remove, click on the trash-can icon (trashcan-icon) at the end of its entry, then click on DELETE.


Managing Database assets in the secrets vault

MySQL, MSSQL, PostgreSQL, Cassandra and MongoDB folders:

For all of the database asset types, a folder represents a 'service', which contains the connection information for a database server (ip, port, root user, password, etc), along with its leasing configuration.

All folders are found under the top-level of their respective asset-type.

The breadcrumb at the the top of page indicates which folder you are in.

e.g.: If the breadcrumb reads MYSQL, then you are viewing the list of folders at the top-level of the MySQL assets.

e.g.: If the breadcrumb reads MYSQL > MYSQL ON EC2 IN US-EAST-1, then you are viewing the list of secrets/roles in the "MySQL on EC2 in us-east-1" folder.

To navigate to a folder from the top-level, click on the folder's name in the list. You will see the list of secrets/roles added under that folder and the breadcrumb will end with the folder name.

To navigate back to the top-level, click on the left-most item in the breadcrumb, e.g.: MYSQL. You will see the list of folders added to the top-level of the asset type and the breadcrumb drop all but its first part.


Below find database-specific instructions to do the following tasks for each database type:

  • add a folder
  • view/edit a folder configuration
  • add an asset to the folder
  • view an asset in the folder
  • remove an asset from the folder

MySQL Assets

MSSQL Assets

PostgreSQL Assets

Cassandra Assets

MongoDB Assets


Managing SSH assets in the secrets vault

SSH folders:

You, as the owner (user with the admin role) or manager of the room's connected organization, can create an SSH folder to facilitate user connections by users of the room to servers in the connected organization's network1.

1. The connected organization configures the room's 'Network Access' to be either 'Internet Only' or 'Tehama Gateway'. When set to 'Internet Only', the network is an internet based network constrained by the room's firewall rules. When set to 'Tehama Gateway', the network is the private network where the room's Tehama Gateway is installed, with access constrained by the room's firewall rules.

An 'SSH' folder represents an 'ssh-signing-service', which contains ssh connection info for a particular server:

  • the server's ip address and port (optional);
  • a firewall exception for the server (optional);
  • a Certificate Authority (CA) key pair, which has been trusted on the server; and
  • default leasing configuration (the expiry info used by the CA for signing SSH public keys).

All SSH folders are found under the top-level for the SSH.

See the SSH Overview for background information on the SSH protocol, Certificate Authorities, and how they are used.

Create as many SSH folders as you need for the Room.

Note, although the interface is set up to provide a one-to-one relationship between a CA and a server, you might use one CA to facilitate access to one group of servers and another one for another group of servers equally well. Just be sure to have the CA trusted in all applicable servers and to generate firewall exceptions for all applicable servers.

The breadcrumb at the the top of page indicates which SSH folder you are in. Navigate the folders similarly to the folders for the database-type assets.

Add an SSH folder (an ssh-signing-service - CA, server-info, firewall-exception etc) to SSH assets page

Navigate to the secrets SSH page. Click on the ADD SSH FOLDER button, then enter the following in the ADD SSH FOLDER dialog to create a new SSH folder:

  • Folder name (this will be the name you see in the list of folders on the SSH page)
  • Description (optional)
  • To enter a default lease (default expiry time for the certificates the CA will generate) deselect This option specifies whether to use the default lease or not. and enter the following values:
    • Default Lease (default expiry time of the secret's generated signed-certificates)
    • Default Maximum Lease (default maximum expiry time)

Click on CREATE, then enter the following in the CONFIGURE <folder name> dialog to create the Certificate Authority for this folder and to specify the server it is meant to be used for:

  • To add a CA and info for the server it will be used for, select Include connection configuration and enter the following values:
    • To supply your own SSH key pair instead of having the tool generate one for you, select Generate SSH key pair and enter the following values:
      • SSH Public CA Key (to be added to list of TrustedCAUserKeys on the server to be ssh'ed to)
      • SSH Private CA Key (to be stored, encrypted, in the vault - used to sign certificates)
    • To create a firewall exception (like a custom firewall rule), select Include a firewall exception and enter the following values:
      • IPv4 IP address (of the server to be ssh'ed to - note, IP:port is added as a firewall exception)
      • Port(s) (associated with the connection being established on the server)
      • Asset Name (the name given to the asset created to generate the firewall exception)

Click on CONFIRM, then the folder will appear in the list of SSH assets.

Note, if you opted to include a firewall exception, then your new folder will contain an entry representing that firewall exception. This is analogous to a custom firewall rule. The entry will have as a name the value you put in the Asset Name field.

View/Edit an SSH folder configuration

Click on the info icon at the top right of the assets list to view the default and maximum lease values for the folder and also to see the public key for the folder's CA.

Click on the gear wheel icon at the top right of the assets list to edit the folder configuration.

Note, if you include a new firewall exception (for a different server, for example) while editing, it will create a new firewall exception entry. Any entries in the asset list for previously create firewall exceptions will remain in the list until you select and delete them.

Add CA to list of TrustedUserCAKeys on the server

You must add the public key for the folder's CA to the list of TrustedUserCAKeys on the server it is to be used to connect to.

To get the CA's public key, go into the folder (by clicking on the folder's name), then click on the info icon at the top right of the assets list.

See the section How does a server 'trust' a CA? of the SSH Overview for details on how to add this key to the server's list of TrustedUserCAKeys.

Add an SSH secret

Navigate to the SSH folder in which you wish to add the secret.

Click on ADD SSH SECRET, enter the following:

  • Secret Name (a string representing this secret - for example something identifying the role on the server that users of this secret will be assuming when they log in)
  • Username (the username for the account that users of this secret will log in to on the server)
  • To override the default lease values specified in the CA (the folder), enter values into the following fields:
    • Default Lease (default expiry time of secret/role instances - overrides value set in SSH folder)
    • Default Maximum Lease (default maximum expiry time - overrides value set in SSH folder)

Click on CREATE, then the secret will appear in the list of assets added under the folder.

Note, the connected organization is responsible for the creation of the account for username on the targeted server. If the server has configured 'authorized principals', the connected organization must ensure that this username is added to the list of principals.

Generate a signed SSH Certificate

Before starting, generate an SSH key pair (or you could reuse existing ones). See the section How are SSH keys (public and private) generated? of the SSH Overview.

Identify the secret you wish to use to sign your SSH key pair's public key - that is, to generate your signed SSH certificate from the public key of your SSH key pair. This will be the secret created for the role (username) on the server that you want to log in as.

Navigate to the SSH folder to which that secret was added. Click on the entry for the secret. In the dialog that appears, enter the SSH Public Key that you wish to have signed by the CA. Click on OK.

The dialog will now display both the username and the newly generated Signed Key. They can be copied.

The expiry time for the signed key is the Default Lease time entered for the folder when it was created, unless it was overridden in the secret itself.

Note, the lease applies to the signed SSH certificate used during the ssh login, not the ssh session. The room firewall does not terminate an ssh session based on the lease parameter. However, an expired certificate cannot be used to ssh login, the user will need to re-create/re-generate the certificate once it has expired to ssh login again.

Use your signed SSH Certificate

Do the following:

  • Put the signed public key into the same folder as its associated private key.
  • SSH into the server, See the section How do you SSH into a server? of the SSH Overview, using:
    • the private key
    • the ip of the server specified in the folder (note, the server must have trusted the CA)
    • the username entered when the secret was created.

If there are connectivity problems, verify that there is an appropriate firewall rule in place to allow the connection, either in the folder, or in the custom firewall rules.

Remove an SSH folder or secret or firewall exception

Navigate to the folder or secret or firewall exception you want to remove, click on the trash-can icon (trashcan-icon) at the end of its entry, then click on DELETE.