Configuring Key Protect

IBM® Key Protect for IBM Cloud® helps you to securely store and apply secrets for apps across IBM Cloud services.

A secret is anything that provides access to sensitive information, such as an API key. If you store secrets as standard keys in Key Protect, you can use this tool integration to access secrets wherever they are needed in the toolchain workflow. To learn more about standard keys in Key Protect, see Key types.

Before you configure a Key Protect tool integration, make sure that you have an instance of the Key Protect service provisioned in the region and resource group that you want to create the tool integration in. In certain scenarios, a Key Protect service instance can be automatically generated. For example, if you are minting a new API key and choose to store it as a secret for later use, you automatically generate the Key Protect service instance. For instructions to provision an instance of the Key Protect service, see Provisioning the service.

Configure Key Protect to securely manage secrets that are part of your toolchain:

If you are configuring this tool integration as you are creating the toolchain, in the Configurable Integrations section, click Key Protect. If Key Protect is defined as an optional tool integration, it is located under More Tools. To create an authorization between the toolchain and the Key Protect 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 Key Protect service instance.
If you have a toolchain and are adding this tool integration to it, from the IBM Cloud console, click the menu icon and select DevOps. 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 Key Protect.
Specify a name for this instance of the Key Protect tool integration to use in your toolchain. The name that you specify is used in the UI tools that select Key Protect 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 Key Protect tool integration tile within the toolchain workspace.
Review the default values for Region and Resource-Group and update, if required.
Select the instance of the Key Protect service that you want to use.
To create an authorization between the toolchain and the Key Protect service instance click the Create Authorization button. This grants the toolchain access to the secret material stored in the Key Protect service instance.
Click Create Integration.
On the Toolchain's Overview page, on the Third-Party tools card, click Key Protect.

Applying secrets

After your Key Protect tool integration is configured, you can use it to apply secrets anywhere that they are needed by the toolchain. The following example applies a secret that is stored in Key Protect to an IBM Cloud API key that is required by the Pipeline tool integration. You can follow the same steps to apply secrets to any of the Continuous Delivery tool integrations that require secret values.

You must save third-party secrets, such as a Slack webhook or an Artifactory API token, in Key Protect before you create a new toolchain. You can mint and store only IBM-managed secrets such as IBM Cloud API keys in Key Protect while you work with your toolchain.

Click the key icon to retrieve secrets from secure stores such as Key Protect for the IBM Cloud API key.
In the Provider field, specify the provider and the name of the Key Protect tool integration that you use to manage your toolchain secrets. For example, to use the Key Protect tool integration, select Key Project: ibm-keyprotect-secrets-1. You can use other providers to manage your toolchain secrets, such as HashiCorp Vault.
Select a secret name and click OK to apply the stored secret to the field that is associated with it.

Secret Reference to a Vault — Figure 1. Secret reference to a vault

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

Literal Secret Value — Figure 2. Secret value

The format that the secret is displayed in indicates whether the value references a secret that is stored in a backend vault or is a secret that is stored in your toolchain. By using references to secrets that are managed by secret providers such as Key Protect, 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 Key Protect. This approach is useful when you must rotate the value of your toolchain secrets periodically.

Adding a Key Protect tool integration to your toolchain template

You can add a Key Protect tool integration to your toolchain template by adding a service definition to the toolchain.yml file in your template repo. This file is the design blueprint for your toolchain and includes all of the tool integrations that are available when you create a toolchain instance based on that template. To customize an existing toolchain template to include a Key Protect tool integration, insert a YAML definition.

  kp-tool:
    service_id: keyprotect
    parameters:
      name: kp-compliance-secrets
      region: us-south
      resource-group: default
      instance-name: ffs-secrets
      setup-authorization-type: create

In certain scenarios, you can add a Key Protect tool integration dynamically while creating a toolchain. For example, if you click New to mint a new API key, you can select the Save this key in a secrets store for reuse checkbox to save the API key in a Key Protect instance to use it again later. If you do not already have a Key Protect instance, a new instance is created for you.

Authorizing your toolchain to access secrets

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

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

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

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

Toolchain Authorizations for Key Protect — Figure 3. Toolchain authorizations for Key Protect

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

Configuring Key Protect by using the API

The Key Protect 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 keyprotect value.

Table 1. Key Protect tool integration parameters
Parameter	Usage	Type	Terraform argument	Description
instance-name	required, updatable	String	instance_name	The name of the Key Protect service instance.
name	required, updatable	String	name	The name of this tool integration. Secret references include this name to identify the secrets store where the secrets reside. All of the secrets store tools that are integrated into a toolchain must have a unique name to allow secret resolution to function properly.
region	required, updatable	String	location	The IBM Cloud region where the Key Protect service instance is located.
resource-group	required, updatable	String	resource_group_name	The name of the resource group where the Key Protect service instance is located.

Learn more about Key Protect

To learn more about Key Protect, see Service overview.