Protecting API test assets by using secrets

Secrets are key-value pairs that are created for your project in HCL DevOps Test Hub (Test Hub) under a secrets collection. You can create secrets collections for your project that enable you or members in your project to use secrets at test runtime either in Test Hub or in desktop clients.

The secrets collections in a project in Test Hub has a separate access control list managed by the members with access to the secrets collections. Controlling access to secrets means controlling access to applications and systems under test. The introduction of secrets (under secrets collections) for a project has simplified managing access to separate environments. If a member of a project does not have access to a secret, for example, a server credential then the member cannot accidentally or maliciously run tests against that server. For example, tests that must access the database server by using the server credentials to retrieve stored data can only be run by a member if the access to the secrets is granted.

Note: Secrets and secrets collections are applicable to test assets authored in HCL DevOps Test Integrations and APIs that enable running tests in defined environments. Secrets are not applicable to tests authored in Test UI or Test Performance.

As a project member with the Owner or Tester role, you can create secrets collections in the project. You can grant or restrict access to the secrets collection that you create in the project.

Members with access to a secrets collection can access, edit, or delete the secrets collection in Test Hub and can view secrets, edit secrets, or delete secrets.

Members with access to secrets collections can grant access to or remove the following:

Other members added specifically
All members with a specific role

Members in the project with the Owner or Tester role and with access the secrets collection can use the secrets in the secrets collection, in tests at runtime.

If you are configuring a project to run an API Suite with tests that refer to secret values, you must configure the secrets under a secrets collection by using the SECRETS tab. You must complete the following tasks:

Create a secrets collection. See Step 1 in Managing secrets collections.
Add secrets in the secrets collection created. See Step 1 in Creating a secret in a secrets collection.
Grant access to project members or member roles, who can access the secrets collection. See Step 1 in Granting access to members or member roles.

Managing secrets collections

You can create secrets in a secrets collection for your project. Secrets are credentials required in certain tests during test runs. Secrets stored in the collection can be used by members to run tests on different environments and eliminates the need to store secrets in multiple locations. You can opt to edit or delete a secrets collection that you configured for your project any time after you create a secrets collection.

Before you begin

You must have created a project on Test Hub. See Managing DevOps Test Hub projects.
You must have completed the following tasks before you edit or delete a secrets collection:
- Configured a secrets collection in your project.
- Created secrets in the selected secrets collection. See Creating a secret in a secrets collection.
You must be a member with the Owner or Tester role to create a secrets collection.
You must be a member with access to the secrets collection to edit or delete the secrets collection. See Granting access to members or member roles.

About this task

You must configure secrets collections in your project so that the members of the project can use secrets contained in a collection during test runs. You can configure secrets so that you can use them in different test environments.

As a member with access to the secrets collection, you can opt to edit or delete a secrets collection configured in a project. For example, you might want to edit the secrets collection name or delete the secrets collection if the testing environment has changed and if secrets that are configured earlier are not required.

To create a secrets collection, go to Step 1.
To edit or delete a secrets collection, go to Step 4.

Procedure

To create a secrets collection:

To create a secrets collection while configuring a new project in the Test Hub UI, open the SECRETS tab in the Project Configuration and create a secrets collection. Use Add Collection.
Alternatively, to create a secrets collection in an existing project, complete the following steps:
1. Log in to Test Hub and from the User Interface (UI) open the project listed under My Projects for which you want to create a secrets collection.
2. Open the Project Configuration page, and then open the SECRETS tab to create a secrets collection.
Enter a name for the secrets collection as its Identifier.

Tip: You can create a secrets collection that contains secrets for a particular test environment in your project. For example, the secrets collection test_env can contain secrets that application testers can use in tests that they run while the secrets collection dev_env can contain secrets that application developers can use in tests they run.

A message is displayed for the successful creation of the secrets collection.

The secrets collection created is displayed.

You can add secrets to the secrets collection you created.

To edit or delete a secrets collection:

Log in to Test Hub and from the UI open the project listed under My Projects.
Open the secrets collection from the SECRETS tab in the Project Configuration page.
If there are multiple secrets collections in the project, select the secrets collection that you want from the list.
- To edit a secrets collection, go to Step 6.
- To delete a secrets collection, go to Step 7.
To edit a secrets collection, complete the following steps:
1. Click the Edit icon to edit the selected secrets collection.
  
  Note: The Edit icon is displayed only for the project owner.
2. Edit the name of the secrets collection, and update the secrets collection.
  
  The secrets collection is updated with the updated name.
To delete a secrets collection, click the Delete icon to delete the selected secrets collection.

The selected secrets collection is removed from the list of secrets collections configured for the project.

Results

You have completed the following tasks:

Created a secrets collection for your project.
Edited the name of a secrets collection in your project.
Removed a secrets collection from your project.

What to do next

If you have created a new secrets collection, you must add secrets to your secrets collection.
You must provide access to project members or member roles to the secrets collection by selecting members or member roles.

Creating a secret in a secrets collection

You must create secrets in the secrets collections configured in your project so that the secrets contained in a collection can be used in certain tests by members of the project with access to the secrets collections during an API suite run.

Before you begin

You must have created a project on Test Hub and configured a secrets collection in your project.

You must be a member with access to the secrets collection.

About this task

You can also configure secrets such that the secrets can be used across different test environments by members with access to the secrets collection. Secrets correspond to the environment variables or tags that you create in a Test Integrations and APIs project specific to an environment.

Procedure

To create a secret under a secrets collection while configuring a new project in the Test Hub UI, select the secrets collection listed in the SECRETS tab in the Project Configuration page and create a secret under the secrets collection.
Alternatively, to create a secret under a secrets collection in an existing project, complete the following tasks:
1. Log in to Test Hub and from the UI open the project listed under My Projects.
2. Open the secrets collection from the SECRETS tab in the Project Configuration page.
Enter a name for the secret as its Identifier and enter the password as the Value for the secret.
For example, under the secrets collection (named as test_env), enter the name of the secret to access a database as dbcred and enter the password required to access the database as its value.

A message is displayed for successful creation of the secret.

Results

You have created secrets in the selected secrets collection for your project.

What to do next

You can view, edit, or delete the secrets created under a secrets collection any time you want.
You can use the secrets in the tests that require these secrets during test runs.

Granting access to members or member roles

You can grant or revoke access to the secrets collection in your project to individual members with different roles or the all members with a specific role. Without access to the secrets collection, members cannot view, create, edit, delete, or use the secrets in the secrets collection.

Before you begin

You must have created a project on Test Hub and configured a secrets collection in your project.

You must be a member with access to the secrets collection.

Procedure

To grant access to a secrets collection while configuring a new project in Test Hub UI, select the secrets collection listed in the SECRETS tab in the Project Configuration page.
Alternatively, to grant access to a secrets collection in an existing project, complete the following tasks:
1. Log in to Test Hub and from the UI open the project listed under My Projects.
2. Open the secrets collection from the SECRETS tab in the Project Configuration page.
  If there are multiple secrets collections in the project, select the secrets collection that you want from the list.
To grant access to a secrets collection in a new project or an existing project, select from the following methods:
- To add all members with a specific role, click the role listed under Grant access to role. For example, if you select Testers, then all members in the project with a tester role are granted access to the secrets collection. You can select any role or all the roles listed.
- To select specific members to grant access to the selected secrets collection, enter the name or the email ID of the member in the field box and add them from the list that is displayed.
Note: Members added specifically are listed under Members with access to this collection but all the members granted access solely due to their roles are not listed.

Important: Irrespective of the role that the member (Owner, Tester or Viewer) was assigned in the project, the access to the secrets collections has to be specifically granted to the members from the SECRETS tab.

Removing access to a secrets collection

To remove access granted to all members with a specific role or a specific member, select from the following methods:
- To remove all members with a specific role, click the role listed under Grant access to role to clear the selection. For example, if Testers is selected and you clear it, then all members in the project with a tester role are removed from the access list to the secrets collection.
- To remove specific members with access to the secrets collection, select the member and click the Delete icon .
Notes:
- Any member with access to the secrets collection can remove access of other members specifically added or of all members with a specific role.
- Members with access to the secrets collection can remove themselves from the access list. Members can do this when there is at least one member remaining in the list. After removing themselves, members cannot add themselves back to the access list and must be added by any of the other remaining members in the list.

Results

You have added members from your project or members with specific role to the access list of people who can access secrets in the selected secrets collection, or you have removed specific members or members with specific role from the access list.

What to do next

You can create secrets under secrets collections for your project.

Managing secrets

You can view, edit, or delete the secrets configured under a secrets collection any time after you have created secrets or after you were granted access to the secrets collection. You can change the value of the secret by editing the secret. You can delete secrets that you no longer require in your test environment.

Before you begin

You must have created a project on Test Hub and configured a secrets collection in your project.

You must have created secrets in the selected secrets collection or the secrets collection must contain secrets.

You must be a member with access to the secrets collection.

Procedure

Log in to Test Hub and from the UI open the project listed under My Projects.
Complete the following steps:
1. Open the secrets collection from the SECRETS tab in the Project Configuration page.
2. Optionally, select the secrets collection that you want from the list if there are multiple secrets collections in the project.
The secrets configured in the selected secrets collection are displayed.

Complete the steps for the task you want to perform as listed in the following table:


Task	Steps
Viewing a secret value	Click the Show icon for the secret you want to view its value, which most likely is a password for the secret. The value configured for the secret is displayed.
Editing a secret value	Click the Edit icon for the secret you want to edit, and enter a `new value` for the secret as its `Value`. The value can be a password for the secret. Note: You can only change the value of the secret. The value of the selected secret is changed.
Deleting a secret	Click the Delete icon in the row of the secret you want to delete. After deleting it, the secrets list in the collection is removed from the list.

Results

You viewed the password configured of the secret under a secrets collection that you created or were granted access.
You changed the secret value of the secret under a secrets collection in your project.
You deleted and removed the secret from the selected secrets collection in your project.

What to do next

You can use secrets in the tests that require these secrets during test runs.