Skip to main content

Reference articleSecrets Vault User Guide

  • Updated

Secrets Vault 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 associated firewall rules for Room assets.

The secret's vault in a Tehama Room can be used to maintain control of privileged credentials, track their access, and eliminate the need to distribute them through potentially insecure channels. The Org Admin user and Org Managers and Room Managers (who are members of the Room) of a Room's connected organization are responsible for adding secrets to the Room's secrets vault. These secrets are used to grant secure access to the assets within the Room's connected-to network. These assets, such as databases, are proprietary information and as such the Room's connected organization controls what is put into the secrets vault for this purpose.

All Room members can use the secrets in a Room's secrets vault. They can use them directly, as in the case of generic secrets, or use them to generate time-limited credentials.

Secrets vault usage scenario:

  • A service consumer (Consumer) wants a service provider (Provider) to perform some work for them on the MySQL database that resides in their private network.
    • Among other things, Consumer wants Provider to:
      • generate reports.
      • update data.

    • Consumer does not want to hand over the root credentials for their MySQL database to Provider. They need a secure and dynamic way to issue temporary and appropriately limited credentials for each task - in short, they need a Tehama Room and secrets vault.

  • Consumer and Provider agree to use Tehama.

    They set up a Tehama Room as follows:

    1. Provider creates a Room in Tehama and invites Consumer to connect their private network to it, which they do.
    2. Consumer logs into the Tehama Web UI and adds a MySQL database folder in the Room's secrets vault.
      • This folder represents their MySQL database.
      • To create this folder, Consumer needs to know:
        • the administrator username and password for the MySQL database (the credentials for the root user).
        • the IP and port of the MySQL server.
        • whether or not the database uses TLS/SSL to establish connections.
        • how long you want dynamically created credentials to last.
      • The above information is securely stored in the newly created folder and cannot be accessed by Provider.
    3. Then, under the MySQL folder just created, Consumer adds a two MySQL database secrets that define MySQL user roles in their MySQL database.
      • The first role is "report-generator":
        • This role has all the permissions necessary to run the MySQL report generation queries. (For example, if a report was "Show all active users", then the role would need to be able to view, read-only the users table in the database, at least, but would not have to be able to modify the table.)
        • to create this secret, Consumer needs to know the SQL statement needed to create such a role.
          e.g.: GRANT SELECT ON users.* TO ...
      • The second role is "data-updater":
        • This role has all the permissions necessary to modify a specified set of tables and keys. (For example, if the data updating to be done was to add middle-name info for users, then the role would need to be able to modify the users table in the database.)
        • to create this secret, SB needs to know the SQL statement needed to create such a role.
          e.g.: GRANT SELECT, UPDATE ON users.* TO ...

    4. Provider adds a member to the Room to perform the data updates and run the reports.
    5. Provider adds a Desktop for the member.

      The Room is now ready for the member to work:

    6. When the member needs to perform the data updates ...
      1. The member connects to the Desktop.
      2. The member goes to the Desktop's Desktop Agent application and generates an instance of the "data-updater" role.
      3. This instance provides a time-limited username and password for Consumer's MySQL database.
      4. The member logs into Consumer's MySQL database with these credentials.
      5. The member performs the data update work and logs out.
      6. After the amount of time specified in the secret, the credentials expire.
    7. When the member needs to perform the recurring task of generating reports ...
      1. The member connects to the Desktop.
      2. The member goes to the Desktop's Desktop Agent application and generates an instance of the "report-generator" role.
      3. This instance provides a time-limited username and password for Consumer's MySQL database.
      4. The member logs into Consumer's MySQL database with these credentials.
      5. The member generates the report and logs out.
      6. After the amount of time specified in the secret, the credentials expire.

The above scenario is just one example of how the secrets vault can be used to protect a company's database 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.

Credentials used to access an asset can be added to your Room's secrets vault. If, as in the usage scenario above, the asset is a database, you can add a secret that defines a role in the database that can be used to generate credentials.

To provide greater control of access to assets, a firewall rule can optionally be associated with the secret so that access to the asset is only available while the secret exists.*

* Be aware of the DNS Filtering feature that is available in Multi-Path Rooms. If this feature is active, be sure to add any domain(s) used to access your secret to the DNS Filtering feature's list of allowed domains.

What is a firewall rule?

See the Firewall Rules User Guide. When credentials for assets are added to the secrets vault, inferred firewall rules may optionally 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' - AKA database secrets, 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.

Note - 'Database secrets' not available in Internet-Only Rooms

Rooms with an Internet-Only connection in their Room infrastructure, that is Rooms with 'Internet-Only' network access, can take advantage of "Generic secrets" and "Secrets that define SSH credentials" in the Tehama Secrets Vault.

But they cannot use the third type of secret - "Secrets that define db roles" - AKA database secrets.

To use "Secrets that define db roles" - AKA database secrets — your Room should have its network access set to 'Multi-Path', with at least one connection configured to your private network, or to 'Tehama Gateway', with a Tehama Gateway installed in your private network, and your database servers, the ones you want to create secrets for, should reside in that connected private network.

This is because database secrets require access to the related database servers. Internet-Only Rooms only provide access to entities available to the public internet. Database servers, normally, are not accessible from the public internet. To allow the Tehama Secrets Vault access to a database server from your Internet-Only Room, you would have to make your database server publicly available, leaving it open to attacks. Therefore, an Internet-Only Room is not a good choice if you need to store database secrets in your Room's Secrets Vault.

See the "View a Room's network access setting" section of the Room/Desktop Connectivity - Types, Status and Settings guide to determine what type of network access your Room has.

Accessing the secrets vault

Only the Org Admin user and Org Managers and Room Managers (who are members of the Room) of a Room's connected organization (owner+connected or connected-only) can see the Room's configurable SECRETS page, found under the CONFIGURE tab of the Room's interface in the Tehama Web UI.

The Org Admin user, the Org Managers and all Room members from any of the organizations in a Room can see the Room's read-only SECRETS page, found under the WORK tab of the Room's interface in the Tehama Web UI and under the SECRETS tab of a connected Desktop session's Desktop Agent application (AKA Workspace Agent).

Check the description of your custom role, to see what access you have to the secrets vault.

The secrets vault is accessible from:

  • the Desktop Agent (full access)

    1. Connect to a Desktop session.
    2. Open the Desktop Agent application.
    3. Click on the SECRETS tab.

  • the Tehama Web UI's ROOMS tab

    1. Log in to the Tehama Web UI.
    2. Click on the ROOMS tab.
    3. Click on the name of the Room you want to access the secrets vault for. You will see the user interface for the Room.
      • To configure secrets (full access)
        1. Click on the Room's CONFIGURE tab.
        2. Select the SECRETS sidebar item.
      • To access secrets for use (read-only access)
        1. Click on the Room's WORK tab.
        2. Select the SECRETS sidebar item.

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

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

Vault

The sidebar 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 sidebar 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 Web UI, 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 Web UI, but not when viewed from the Desktop Agent.

Configuring secrets vault settings

The secrets vault has settings that are configurable from the Tehama Web UI landing page for the configurable secrets vault interface. (See Accessing the secrets vault above.) 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 Web UI and the Desktop Agent.

To disable access to credentials from the Tehama Web UI, 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 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.

* Be aware of the DNS Filtering feature that is available in Multi-Path Rooms. If this feature is active, be sure to add any domain(s) used to access your secret to the DNS Filtering feature's list of allowed domains.

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 three vertical dots under the Actions column in entry, select the "Remove" action, then click on DELETE in the delete dialog.

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 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.: 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 Org Admin or one of the Org Managers or Room Managers (who are members of the Room) 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 network.*

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 top of page indicates which SSH folder you are in. Navigate the folders similarly to the folders for the database-type assets.

 

* The connected organization configures 'Network Access' to be 'Multi-Path', 'Tehama Gateway' or 'Internet Only'.

  • When set to 'Multi-Path', the network consists of resources in the cloud plus an optional set of private networks, all access constrained by the Room's firewall rules, and, optionally, by the Room's DNS Filtering feature.
  • When set to 'Tehama Gateway', the network consists of resources in the cloud plus the private network where the Room's Tehama Gateway is installed again, all access constrained by the Room's firewall rules.
  • When set to 'Internet Only', the network consists of resources in the cloud, again with access constrained by the Room's firewall rules.

 

** Be aware of the DNS Filtering feature that is available in Multi-Path Rooms. If this feature is active, be sure to add any domain(s) used to access your secret to the DNS Filtering feature's list of allowed domains.

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.

* Be aware of the DNS Filtering feature that is available in Multi-Path Rooms. If this feature is active, be sure to add any domain(s) used to access your secret to the DNS Filtering feature's list of allowed domains.

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. Also, check to see if the DNS Filtering feature that is available in Multi-Path Rooms is active. If this feature is active, be sure to add any domain(s) used to access your secret to the DNS Filtering feature's list of allowed domains.

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 three vertical dots under the Actions column in entry, select the "Remove" action, then click on DELETE in the delete dialog.

Related articles