Configuring Secrets Manager

Identifying secrets by name

When you configure the Secrets Manager tool integration to identify secrets by name, your toolchain can access the following secret types:

• Identity and Access Management (IAM) credentials secrets.
• Arbitrary secrets that are stored in the Secrets Manager.
• Key-value secrets.

References to secrets by name are currently not able to resolve a secret that includes the period character in the secret name because this character is used to delimit each section of the canonical path.

For more information about IAM credentials secrets, Arbitrary secrets and Key-value secrets in Secrets Manager, see Working with secrets of different types.

Configure Secrets Manager to securely manage secrets that are part of your toolchain:

1. If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click Secrets Manager. If Secrets Manager is defined as an optional tool integration, it is located under More Tools. Choose to identify this instance by the service instance name. To create an authorization between the toolchain and the Secrets Manager service instance select the Create an authorization for this toolchain option from the Authorization type dropdown. This grants the toolchain access to the secret material stored in the Secrets Manager service instance.

2. If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to open its Overview page. Alternatively, on your app's Overview page, on the Continuous Delivery card, click View toolchain. Then, click Overview.

   a. Click Add tool.

   b. In the Tool Integrations section, click Secrets Manager.

3. Specify a name for this instance of the Secrets Manager tool integration to use in your toolchain. The name that you specify is used in the UI tools that select Secrets Manager secrets. It is also used as part of the reference that resolves the secret values when the toolchain runs. This instance name is also displayed on the Secrets Manager tool integration tile within the toolchain workspace.

4. Choose to identify this instance by the service instance name.

5. Review the default values for Region and Resource-Group and update, if required.

6. Select the instance of the Secrets Manager service that you want to use.

7. To create an authorization between the toolchain and the Secrets Manager service instance click the Create Authorization button. This grants the toolchain access to the secret material stored in the Secrets Manager service instance.

8. Click Create Integration.

Applying secrets

After your Secrets Manager tool integration is configured, you can use it to apply secrets anywhere that they are needed by the toolchain. This tool integration and the Secrets dialog box support both the Arbitrary and the IAM credentials secret types.

You can use Arbitrary secrets to store any predefined secret value, or to store dynamically minted IBM Cloud API keys by using the Secrets dialog box. You must create IAM credentials secrets directly within your Secrets Manager service instance. After you create these secrets, you can select IAM credentials secrets to use them within your toolchain by using the Secrets dialog box on any secure field. The Secrets dialog box displays both the Arbitrary and the IAM credentials secret types, with the secret type appended to the secret name in brackets.

Using arbitrary secrets that are stored in Secrets Manager

You must save third-party secrets, such as a Slack webhook or an Artifactory API token, in Secrets Manager before you create a new toolchain. You can mint and store IBM-managed secrets, such as IBM Cloud API keys in Secrets Manager, as Arbitrary secret types while you work with your toolchain by using the Secrets dialog. However, you must mint IAM credentials secrets directly in Secrets Manager before you can select these types of secrets within your toolchain by using the Secrets dialog box.

The following example applies an Arbitrary secret type that is stored in Secrets Manager to an IBM Cloud API key that is required by the Delivery Pipeline tool integration. You can follow the same steps to apply secrets to any of the Continuous Delivery tool integrations that require secret values.

1. Click the key icon to retrieve secrets from secure stores such as Secrets Manager for the IBM Cloud API key.

2. In the Provider field, specify the provider and the name of the Secrets Manager tool integration that you use to manage your toolchain secrets. For example, to use the Secrets Manager tool integration, select Secrets Manager: ibm-secrets-manager-1. You can use other providers to manage your toolchain secrets, such as HashiCorp Vault and Key Protect.

3. Select a secret group and a secret name and click OK to apply the stored secret to the field that is associated with it.

   

   The name of the secret that you select appears in capsule form. You cannot edit the secret name inline, but you can click to delete the name. You can also replace the existing secret name by selecting the secret name again. If you manually type or paste a secret name into the Secrets field, it is displayed in a different format:

   

   The format that the secret is displayed in indicates whether the value references a secret that is stored in a backend vault or a secret that is stored in your toolchain. By using references to secrets that are managed by secret providers such as Secrets Manager, your secret values are centralized and stored securely in a single location. This approach resolves secrets sprawl and proliferation, and means that you can update secrets without updating your toolchain. When you use secret references, the actual secret value is resolved when the toolchain runs by dynamically retrieving it from Secrets Manager. This approach is useful when you must rotate the value of your toolchain secrets periodically.

Using IAM credentials secrets

The IAM credentials secret type is fully integrated with IAM. Secrets Manager auto-manages dynamic service IDs and API keys that are associated with an IAM credentials secret. Continuous Delivery and Secrets Manager service APIs engage to resolve authorized IAM Credentials secret references in Continuous Delivery toolchains and pipeline workloads.

When you create an IAM credentials secret in Secrets Manager, make sure that you select the Reuse IAM credentials until lease expires checkbox. Also, specify a lease duration with a minimum of 12 hours when you use public worker agents to run your pipeline. If you use private worker agents, make sure that you set a minimum lease duration to the forced cancellation duration for a pipeline. It is recommended that you confirm these settings with your account administrator. By setting the reuse option and an appropriate lease duration, you can make sure that the dynamically managed IAM credentials service ID API key persists during your pipeline runs.

By running the Rotate action on IAM credentials from the Secrets Manager dashboard, you can maintain the compliance posture requirements for API Key rotations that are used by your Continuous Delivery pipelines. Secrets Manager works with IAM to generate a new API Key for an IAM credentials secret and manages the versioning of the secret.

The IAM credentials secret type also helps to provide continuity of service during and after secret rotation:

• New Continuous Delivery pipeline workloads use the newly rotated API Key until its lease duration expires.
• Existing Continuous Delivery pipeline workloads that are running with the API Key that was issued before rotation can continue to run with the previous version until the lease duration of the previous version expires.

For more information about the IAM credentials secret type in Secrets Manager, see Creating IAM credentials.

Using key-value secrets

You can select the key-value secrets to use in your toolchain by selecting an individual key from the key-value secret in the Secrets dialog. Alternatively, you can select the secret in its entirety.

1. Click the key icon to retrieve secrets from secure stores such as Secrets Manager for the IBM Cloud API key.

2. In the Provider field, specify the provider and the name of the Secrets Manager tool integration that you use to manage your toolchain secrets. For example, to use the Secrets Manager tool integration, select Secrets Manager: ibm-secrets-manager-1. You can use other providers to manage your toolchain secrets, such as HashiCorp Vault and Key Protect.

3. Select a secret group and a secret name to apply the stored secret to the field that is associated with it. Optional: select a secret key. Click OK. The name of the secret that you select appears in capsule form. You cannot edit the secret name inline, but you can click to delete the name. You can also replace the existing secret name by selecting the secret name again. If you manually type or paste a secret name into the Secrets field, it is displayed in a different format.

  sm-compliance-secrets:
    service_id: secretsmanager
    parameters:
      name: sm-compliance-secrets
      instance-id-type: instance-name
      region: us-south
      resource-group: default
      instance-name: ffs-secrets
      setup-authorization-type: create

Identifying secrets by CRN

When you configure the Secrets Manager tool integration to identify secrets by CRN, your toolchain can access arbitrary, key-value, and IAM credential secrets that are stored in the Secrets Manager. For more information about the different types of secrets in Secrets Manager, see Working with secrets of different types. You can use only entire key-value secrets for CRN secrets, not individual keys.

Configure Secrets Manager to securely manage secrets that are part of your toolchain:

1. If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click Secrets Manager. If Secrets Manager is defined as an optional tool integration, it is located under More Tools. Choose to identify this instance by the service instance CRN. To create an authorization between the toolchain and the Secrets Manager service instance select the Create an authorization for this toolchain option from the Authorization type dropdown. This grants the toolchain access to the secret material stored in the Secrets Manager service instance.

2. If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains. On the Toolchains page, click the toolchain to open its Overview page. Alternatively, on your app's Overview page, on the Continuous Delivery card, click View toolchain. Then, click Overview.

   a. Click Add tool.

   b. In the Tool Integrations section, click Secrets Manager.

3. Specify a name for this instance of the Secrets Manager tool integration to use in your toolchain.

4. Choose to identify this instance by the service instance CRN.

5. Specify the CRN of the Secrets Manager service instance where your secrets are stored. This service instance can exist in a different account if your toolchain is authorized to access secrets in that account.

6. To create an authorization between the toolchain and the Secrets Manager service instance click the Create Authorization button. This grants the toolchain access to the secret material stored in the Secrets Manager service instance.

7. Click Create Integration.

Authorizing your toolchain to access secrets

References to secrets that are stored in Secrets Manager are dynamically resolved when the toolchain runs. To access the required secrets, you must authorize your toolchain to access the Secrets Manager instance. If you are creating a toolchain from a template use the Authorization type dropdown when configuring the Secrets Manager integration. If you are adding a Secrets Manager integration to an existing toolchain use the Create authorization button.

To view your authorizations in IBM Cloud, complete the following steps:

1. From the IBM Cloud console, click Manage > Access (IAM).

2. Click Authorizations.

   You can also access your authorizations on the Manage authorizations page.

   You can create the authorization manually, if required. To successfully resolve the secret references, your toolchain instance must have both Viewer and SecretsReader access to the correct Secrets Manager service instance.

   When Secrets Manager tool integrations that identify secrets by CRN are configured to access secrets in a different account, you must create the authorization in the account where the Secrets Manager service instance exists.

Configuring Secrets Manager by using the API

The Secrets Manager tool integration supports the following configuration parameters that you can use with the Toolchain HTTP API and SDKs when you create, read, and update tool integrations.

You must specify the tool_type_id property in the request body with the secretsmanager value.

Learn more about Secrets Manager

To learn more about Secrets Manager, see Getting started with Secrets Manager.