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.

    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 assets in the secrets vault

Overview of vault structure - Folders and Navigation

MySQL, MSSQL, PostgreSQL, Cassandra and MongoDB folders:

For all asset types except "Generic" and "SSH", 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.

Generic asset folders:

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.

SSH folders:

An 'SSH' asset folder represents an 'ssh-signing-service', which contains ssh connection information for a server (ip, port, Certificate Authority (CA) key pair) along with its leasing configuration.

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

The breadcrumb at the the top of page indicates which folder you are in. Navigation is similar to the database-type assets.


Below find asset-type specific instructions to do the following tasks:

  • 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

Generic Assets

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.


MySQL Assets

Add a MySQL folder

Navigate to the secrets MySQL page. Click on the ADD MYSQL FOLDER button, then enter the following in the ADD MYSQL FOLDER dialog:

  • Folder name
  • Description (optional)
  • Select Yes or No for the question Would you like to display password in plaintext?
  • Default Lease (default expiry time of secret/role instances)
  • Default Maximum Lease (default maximum expiry time)

Click on CREATE, then enter the following in the CONFIGURE <folder name> dialog:

  • If you choose to Include connection configuration, enter:
    • Administrator Username (for the admin user of the targeted MySQL server)
    • Administrator Password (for the admin user of the MySQL server)
    • IPv4 IP address (of the MySQL server - note, IP:port is added as a firewall exception if you choose to include a firewall exception)
    • Port (of the MySQL server)
    • TLS/SSL (checked if TLS/SSL is to be used for establishing connections with the server)
    • If you choose to Include a firewall exception, enter:
      • Asset Name (the name given to the asset created to generate the firewall exception)
  • If you choose to Include lease configuration, enter:
    • Default Lease (default expiry time of secret/role instances)
    • Default Maximum Lease (default maximum expiry time)

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

View/Edit a MySQL 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.

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

Add a MySQL secret/role

Navigate to the folder in which you wish to add the secret/role.

Click on ADD MYSQL SECRET, enter the following:

  • Secret Name
  • Creation SQL (sample SQL for user creation provided in UI)
  • If revoke-user statements are required:
    • Revocation SQL (default behaviour is to delete the user)

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

Generate a MySQL secret/role instance

Navigate to the folder to which the secret/role was added. Click on the entry for the secret/role. The username and password for the newly created secret/role instance will be displayed. They can be copied. If you opted not to display the password in plaintext when creating the folder, clicking on the button COPY PASSWORD will copy the password to the clipboard.

Note, once this modal is dismissed, there is no way to retrieve this information. Clicking on the entry for the secret/role again will generate a different instance.

The expiry time for the instance is the Default Lease time entered for the folder when it was created.

Remove a MySQL folder or secret/role

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


MSSQL Assets

Add a folder to MSSQL assets

Navigate to the secrets MSSQL page. Click on the ADD MSSQL FOLDER button, then enter the following in the ADD MSSQL FOLDER dialog:

  • Folder name
  • Description (optional)
  • Select Yes or No for the question Would you like to display password in plaintext?
  • Default Lease (default expiry time of secret/role instances)
  • Default Maximum Lease (default maximum expiry time)

Click on CREATE, then enter the following in the CONFIGURE <folder name> dialog:

  • If you choose to Include connection configuration, enter:
    • Administrator Username (for the admin user of the targeted MSSQL server)
    • Administrator Password (for the admin user of the MSSQL server)
    • IPv4 IP address (of the MSSQL server - note, IP:port is added as a firewall exception if you choose to include a firewall exception)
    • Port (of the MSSQL server)
    • Administrator's Database
    • TLS/SSL (checked if TLS/SSL is to be used for establishing connections with the server)
    • If you choose to Include a firewall exception, enter:
      • Asset Name (the name given to the asset created to generate the firewall exception)
  • If you choose to Include lease configuration, enter:
    • Default Lease (default expiry time of secret/role instances)
    • Default Maximum Lease (default maximum expiry time)

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

View/Edit a MSSQL 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.

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

Add a MSSQL secret/role

Navigate to the folder in which you wish to add the secret/role.

Click on ADD MSSQL SECRET, enter the following:

  • Secret Name
  • Creation SQL (sample SQL for user creation provided in UI)

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

Generate a MSSQL secret/role instance

Navigate to the folder to which the secret/role was added. Click on the entry for the secret/role. The username and password for the newly created secret/role instance will be displayed. They can be copied. If you opted not to display the password in plaintext when creating the folder, clicking on the button COPY PASSWORD will copy the password to the clipboard.

Note, once this modal is dismissed, there is no way to retrieve this information. Clicking on the entry for the secret/role again will generate a different instance.

The expiry time for the instance is the Default Lease time entered for the folder when it was created.

Remove a MSSQL folder or secret/role

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


PostgreSQL Assets

Add a folder to PostgreSQL assets

Navigate to the secrets PostgreSQL page. Click on the ADD POSTGRESQL FOLDER button, then enter the following in the ADD POSTGRESQL FOLDER dialog:

  • Folder name
  • Description (optional)
  • Select Yes or No for the question Would you like to display password in plaintext?
  • Default Lease (default expiry time of secret/role instances)
  • Default Maximum Lease (default maximum expiry time)

Click on CREATE, then enter the following in the CONFIGURE <folder name> dialog:

  • If you choose to Include connection configuration, enter:
    • Administrator Username (for the admin user of the targeted PostgreSQL server)
    • Administrator Password (for the admin user of the PostgreSQL server)
    • IPv4 IP address (of the PostgreSQL server - note, IP:port is added as a firewall exception if you choose to include a firewall exception)
    • Port (of the PostgreSQL server)
    • Administrator's Database
    • TLS/SSL (checked if TLS/SSL is to be used for establishing connections with the server)
    • If you choose to Include a firewall exception, enter:
      • Asset Name (the name given to the asset created to generate the firewall exception)
  • If you choose to Include lease configuration, enter:
    • Default Lease (default expiry time of secret/role instances)
    • Default Maximum Lease (default maximum expiry time)

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

View/Edit a PostgreSQL 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.

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

Add a PostgreSQL secret/role

Navigate to the folder in which you wish to add the secret/role.

Click on ADD POSTGRESQL SECRET, enter the following:

  • Secret Name
  • Creation SQL (sample SQL for user creation provided in UI)
  • If revoke-user statements are required:
    • Revocation SQL (default behaviour is to delete the user)

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

Generate a PostgreSQL secret/role instance

Navigate to the folder to which the secret/role was added. Click on the entry for the secret/role. The username and password for the newly created secret/role instance will be displayed. They can be copied. If you opted not to display the password in plaintext when creating the folder, clicking on the button COPY PASSWORD will copy the password to the clipboard.

Note, once this modal is dismissed, there is no way to retrieve this information. Clicking on the entry for the secret/role again will generate a different instance.

The expiry time for the instance is the Default Lease time entered for the folder when it was created.

Remove a PostgreSQL folder or secret/role

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


Cassandra Assets

Add a folder to Cassandra assets

Navigate to the secrets Cassandra page. Click on the ADD CASSANDRA FOLDER button, then enter the following in the ADD CASSANDRA FOLDER dialog:

  • Folder name
  • Description (optional)
  • Select Yes or No for the question Would you like to display password in plaintext?
  • Default Lease (default expiry time of secret/role instances)
  • Default Maximum Lease (default maximum expiry time)

Click on CREATE, then enter the following in the CONFIGURE <folder name> dialog:

  • If you choose to Include connection configuration, enter:
    • Administrator Username (for the admin user of the targeted Cassandra server)
    • Administrator Password (for the admin user of the Cassandra server)
    • IPv4 IP address (of the Cassandra server - note, this is added as a firewall exception if you choose to include a firewall exception)
    • CQL Protocol Version
    • If you choose to Include a firewall exception, enter:
      • Asset Name (the name given to the asset created to generate the firewall exception)
  • If you choose to Include lease configuration, enter:
    • Default Lease (default expiry time of secret/role instances)
    • Default Maximum Lease (default maximum expiry time)

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

Under that new folder, there will be a sub-folder called "Default_Assets" (an exception to the rule that all folders are found at the top level). This is just a container folder. It contains a list of 'Generic' type assets used by Cassandra that require firewall exceptions. The list consists of:

  • CQL_Native_Transport_Asset
  • Internode_Communication_Asset
  • JMX_Asset
  • Thrift_Client_API_Asset
  • TLS_Internode_Communication_Asset

View/Edit a Cassandra 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.

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

Add a Cassandra secret/role

Navigate to the folder in which you wish to add the secret/role.

Click on ADD CASSANDRA SECRET, enter the following:

  • Secret Name
  • Creation SQL (sample SQL for user creation provided in UI)
  • If CQL statements to rollback are required:
    • Rollback CQL (default behaviour is to delete the user)
  • If lease is required for the role:
    • Lease (defaults to '1h')
  • If consistency level is required:
    • Consistency (default to 'Quorum')

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

Generate a Cassandra secret/role instance

Navigate to the folder to which the secret/role was added. Click on the entry for the secret/role. The username and password for the newly created secret/role instance will be displayed. They can be copied. If you opted not to display the password in plaintext when creating the folder, clicking on the button COPY PASSWORD will copy the password to the clipboard.

Note, once this modal is dismissed, there is no way to retrieve this information. Clicking on the entry for the secret/role again will generate a different instance.

The expiry time for the instance is the Lease time entered for the secret/role when it was created.

Remove a Cassandra folder or secret/role

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


MongoDB Assets

Add a folder to MongoDB assets

Navigate to the secrets MongoDB page. Click on the ADD MONGODB FOLDER button, then enter the following in the ADD MONGODB FOLDER dialog:

  • Folder name
  • Description (optional)
  • Select Yes or No for the question Would you like to display password in plaintext?
  • Default Lease (default expiry time of secret/role instances)
  • Default Maximum Lease (default maximum expiry time)

Click on CREATE, then enter the following in the CONFIGURE <folder name> dialog:

  • If you choose to Include connection configuration, enter:
    • Administrator Username (for the admin user of the targeted MongoDB server)
    • Administrator Password (for the admin user of the MongoDB server)
    • IPv4 IP address (of the MongoDB server - note, IP:port is added as a firewall exception if you choose to include a firewall exception)
    • Port (of the MongoDB server)
    • Administrator's Database
    • TLS/SSL (checked if TLS/SSL is to be used for establishing connections with the server)
    • If you choose to Include a firewall exception, enter:
      • Asset Name (the name given to the asset created to generate the firewall exception)
  • If you choose to Include lease configuration, enter:
    • Default Lease (default expiry time of secret/role instances)
    • Default Maximum Lease (default maximum expiry time)

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

View/Edit a MongoDB 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.

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

Add a MongoDB secret/role

Navigate to the folder in which you wish to add the secret/role.

Click on ADD MONGODB SECRET, enter the following:

  • Secret Name
  • Roles (sample roles definition provided in UI)
  • Database

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

Generate a MongoDB secret/role instance

Navigate to the folder to which the secret/role was added. Click on the entry for the secret/role. The username and password for the newly created secret/role instance will be displayed. They can be copied. If you opted not to display the password in plaintext when creating the folder, clicking on the button COPY PASSWORD will copy the password to the clipboard.

Note, once this modal is dismissed, there is no way to retrieve this information. Clicking on the entry for the secret/role again will generate a different instance.

The expiry time for the instance is the Default Lease time entered for the folder when it was created.

Remove a MongoDB folder or secret/role

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


SSH Assets

Add a folder to SSH assets

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

  • Folder name
  • Description (optional)
  • If you choose not to select This option specifies whether to use the default lease or not.
    • 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:

  • If you choose to Include connection configuration, enter:
    • If you do NOT choose the option Generate SSH key pair
      • 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)
    • If you choose to Include a firewall exception, enter:
      • 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)
  • If you choose to Include lease configuration, enter:
    • Default Lease (default expiry time of the secret's generated signed-certificates)
    • Default Maximum Lease (default maximum expiry time)

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

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.

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

Add an SSH secret

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

Click on ADD SSH SECRET, enter the following:

  • Secret Name
  • Username
  • If not using default lease from SSH folder
    • 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.

Generate a signed SSH Certificate

Navigate to the folder to which the secret was added. Click on the entry for the secret. In the dialog that appears, enter the SSH Public Key that you wish to sign. 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 asset.

Remove an SSH folder or secret

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