years
2015, 2026

lastupdated

2026-04-09

keywords

tool integrations, IBM Cloud Public, Key Protect

subcollection

ContinuousDelivery

Configuring {{site.data.keyword.keymanagementserviceshort}}

{: #keyprotect}

{{site.data.keyword.contdelivery_short}} will be discontinued in the following regions on 10 April 2026: eu-es and jp-osa. This discontinuation also applies to any features provided within the service, including Code Risk Analyzer and {{site.data.keyword.DRA_short}}. Learn more {: important}

{{site.data.keyword.contdelivery_short}} will be discontinued in the following regions on 12 February 2027: au-syd, ca-mon, ca-tor, us-east. Code Risk Analyzer and {{site.data.keyword.DRA_short}} will also be deprecated in all regions on that date. However, if a region has no active usage of these features, the features in that region may be discontinued earlier and stop accepting new instances. Learn more {: important}

{{site.data.keyword.keymanagementservicefull}} helps you to securely store and apply secrets for apps across {{site.data.keyword.cloud_notm}} services. {: shortdesc}

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

Before you configure a {{site.data.keyword.keymanagementserviceshort}} tool integration, make sure that you have an instance of the {{site.data.keyword.keymanagementserviceshort}} service provisioned in the region and resource group that you want to create the tool integration in. In certain scenarios, a {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} service instance. For instructions to provision an instance of the {{site.data.keyword.keymanagementserviceshort}} service, see Provisioning the service. {: important}

Configure {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}}. If {{site.data.keyword.keymanagementserviceshort}} is defined as an optional tool integration, it is located under More Tools. To create an authorization between the toolchain and the {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} service instance.
If you have a toolchain and are adding this tool integration to it, from the {{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.contdelivery_short}} card, click View toolchain. Then, click Overview.

a. Click Add tool.

b. In the Tool Integrations section, click {{site.data.keyword.keymanagementserviceshort}}.
Specify a name for this instance of the {{site.data.keyword.keymanagementserviceshort}} tool integration to use in your toolchain. The name that you specify is used in the UI tools that select {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} service that you want to use.
To create an authorization between the toolchain and the {{site.data.keyword.keymanagementserviceshort}} service instance click the Create Authorization button. This grants the toolchain access to the secret material stored in the {{site.data.keyword.keymanagementserviceshort}} service instance.
Click Create Integration.
On the Toolchain's Overview page, on the Third-Party tools card, click {{site.data.keyword.keymanagementserviceshort}}.

Applying secrets

{: #apply_secrets}

After your {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} to an {{site.data.keyword.cloud_notm}} API key that is required by the Pipeline tool integration. You can follow the same steps to apply secrets to any of the {{site.data.keyword.contdelivery_short}} tool integrations that require secret values.

You must save third-party secrets, such as a Slack webhook or an Artifactory API token, in {{site.data.keyword.keymanagementserviceshort}} before you create a new toolchain. You can mint and store only IBM-managed secrets such as {{site.data.keyword.cloud_notm}} API keys in Key Protect while you work with your toolchain. {: important}

Click the key icon to retrieve secrets from secure stores such as {{site.data.keyword.keymanagementserviceshort}} for the {{site.data.keyword.cloud_notm}} API key.
In the Provider field, specify the provider and the name of the {{site.data.keyword.keymanagementserviceshort}} 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.

{: caption="Secret reference to a vault" caption-side="bottom"}

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 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:

{: caption="Secret value" caption-side="bottom"}

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 {{site.data.keyword.keymanagementserviceshort}}, 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 {{site.data.keyword.keymanagementserviceshort}}. This approach is useful when you must rotate the value of your toolchain secrets periodically.

Adding a {{site.data.keyword.keymanagementserviceshort}} tool integration to your toolchain template

{: #add_toolchain_template}

You can add a {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} 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 {{site.data.keyword.keymanagementserviceshort}} instance to use it again later. If you do not already have a {{site.data.keyword.keymanagementserviceshort}} instance, a new instance is created for you. {: tip}

Authorizing your toolchain to access secrets

{: #key_protect_authorize_secrets}

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

To view your authorizations in {{site.data.keyword.cloud_notm}}, complete the following steps:

From the {{site.data.keyword.cloud_notm}} console, click Manage > Access (IAM).
Click Authorizations.

You can also access your authorizations on the Manage authorizations{: external} page. {: tip}

{: caption="Toolchain authorizations for Key Protect" caption-side="bottom"}

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 {{site.data.keyword.keymanagementserviceshort}} service instance.