Locking secrets

When you work with IBM Cloud® Secrets Manager, you can create locks on your secrets to prevent them from being deleted or modified while they're in use by your applications.

By default, an authorized user or application can modify the secrets that you manage in Secrets Manager at any time. Sometimes, for example during a security audit, you might want to prevent someone on your team from accidentally deleting a secret. Or, if you plan to rotate your secrets regularly, you might be looking for a way to safely deploy the newest version of a secret after a rotation takes place. With locks, you can build automated workflows that help you to:

Indicate that a secret is in use by one or more applications or services.
Prevent secret data from being deleted even after a secret expires.
Safely delete older versions of secrets after the newest version is fully deployed to your applications.
Avoid inadvertent downtime in your applications.

To learn about the suggested guidelines for using locks to avoid application downtime, check out Best practices for rotating and locking secrets.

Before you begin

Before you begin, be sure that you have the required level of access. To manage locks on your secrets, you need the Manager service role.

Locking secrets

Locking a secret prevents any operation that can result in modifying or deleting its secret data. To lock a secret, you attach one or more locks to its current or previous version.

When you try to modify or delete a secret while it is locked, Secrets Manager denies the request with an HTTP 412 Precondition Failed response. You see an error message similar to the following example:
```
The requested action can't be completed because the secret version is locked.
```
If you're working with dynamic secretsA unique value, such as a password or an API key, that is created dynamically and leased to an application that requires access to a protected resource. After a dynamic secret reaches the end of its lease, access to the protected resource is revoked and the secret is deleted automatically., such as IAM credentials, locking your secrets also means that by default, those secrets can't be read or accessed. For more information, see Why can't I read a locked IAM credentials secret?
If a locked secret reaches its expiration date, it stays in the Active state and its data remains accessible to your applications. Secrets Manager moves the secret to the Destroyed state and permanently deletes the expired secret data only after all locks on the secret are removed.

SSL/TLS certificates still reach their defined expiration dates and move into a Destroyed state even if they are locked. For more information, see Why did my locked certificate move to the Destroyed state?
If you try to rotate a secret while its current version is locked and the previous version is unlocked (or if an automatic rotation is scheduled), the request to rotate the secret is allowed. The current secret version becomes the new previous version, retaining its existing locks. A new current version is created without any locks.
If you try to rotate a secret while its previous version is locked (or if an automatic rotation is scheduled), your request to rotate the secret is denied. Rotation is allowed only after all locks on the previous secret version are removed.

Creating locks in the UI

You can create up to 1000 locks on a secret by using the Secrets Manager UI. Each lock can be used to represent a single application or service that uses your secret.

A secret is considered locked after you attach one or more locks to it. A lock can be applied only on a secret version that contains active payload, or secret data.

To help you to create a new lock and remove older locks in a single operation, you can also specify an optional mode at lock creation.

Table 1. Optional lock modes and their descriptions
Mode	Description
Remove previous locks	Removes any other locks that match the name that you specify. If any matching locks are found in the previous version of the secret, those locks are deleted when your new lock is created. For example, suppose that the previous version of your secret contains a lock `lock-x`. Creating a lock on the current version of your secret and enabling the Delete matching locks option results in removing `lock-x` from the previous version.
Remove previous locks and delete previous version data	Same as the previous option, but also permanently deletes the data of the previous secret version if it doesn't have any locks that are associated with it. Suppose that the previous version of your secret contains a lock `lock-z`. Creating a lock on the current version of your secret with both the Delete matching locks and Delete previous version data options results in removing `lock-z` from the previous version. Additionally, because the previous version doesn't have any other locks that are attached to it, the secret data that is associated with the previous version is also deleted.

Creating a lock on the current secret version

You can lock the current version of a secret by using the Secrets Manager UI. A successful request attaches a new lock to the current version of your selected secret, or replaces a lock of the same name if it already exists.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets Manager UI, go to the Secrets list.
In the row for the secret that you want to lock, click the Actions menu > Locks > Create lock.
Add a name and description to easily identify the lock.
From the list of versions to lock, select Current.
Optional: Attach JSON attributes to your lock.

You can include a JSON object with each lock to hold any information that you might need for an automated flow. For example, a key-value pair that identifies the resource that you want to associate with this lock.
Optional: Make the lock exclusive.

Choose this option to remove any other locks that match the name that you provided. If any matching locks are found in the previous version of the secret, those locks are deleted when your new lock is created.
Optional: Delete previous version data.

Choose this option to also permanently delete the data of the previous secret version if it doesn't have any locks that are associated with it.
Click Create.

A new lock is created for your selected secret version.

Creating a lock on the previous secret version

You can lock the previous version of a secret by using the Secrets Manager UI. A successful request attaches a new lock to the previous version of your selected secret, or replaces a lock of the same name if it already exists.

In the Secrets Manager UI, go to the Secrets list.
In the row for the secret that you want to lock, click the Actions menu > Locks > Create lock.
Add a name and description to easily identify the lock.
From the list of versions to lock, select Previous.
Optional: Attach JSON attributes to your lock.

You can include a JSON object with each lock to hold any information that you might need for an automated flow. For example, a key-value pair that identifies the resource that you want to associate with this lock.
Click Create.

A new lock is created for your selected secret version.

Creating locks from the CLI

You can create up to 1000 locks on a secret by using the Secrets Manager CLI. Each lock can be used to represent a single application or service that uses your secret.

A secret is considered locked after you attach one or more locks to it. A lock can be applied only on a secret version that contains active payload, or secret data.

To help you to create a new lock and remove older locks in a single operation, you can also specify an optional mode at lock creation.

Table 1. Optional lock modes and their descriptions
Mode	Description
Remove previous locks	Removes any other locks that match the name that you specify. If any matching locks are found in the previous version of the secret, those locks are deleted when your new lock is created. For example, suppose that the previous version of your secret contains a lock `lock-x`. Creating a lock on the current version of your secret and enabling the Delete matching locks option results in removing `lock-x` from the previous version.
Remove previous locks and delete previous version data	Same as the previous option, but also permanently deletes the data of the previous secret version if it doesn't have any locks that are associated with it. Suppose that the previous version of your secret contains a lock `lock-z`. Creating a lock on the current version of your secret with both the Delete matching locks and Delete previous version data options results in removing `lock-z` from the previous version. Additionally, because the previous version doesn't have any other locks that are attached to it, the secret data that is associated with the previous version is also deleted.

Creating a lock on the current secret version

You can lock the current version of a secret by using the Secrets Manager CLI. A successful request attaches a new lock to the current version of your selected secret, or replaces a lock of the same name if it already exists.

To create a lock on the current version of a secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-locks-bulk-create command. You can specify the type of secret, the secret ID, and the mode.

ibmcloud secrets-manager secret-locks-bulk-create \
    --id=exampleString \
    --locks='[{"name": "lock-example-1", "description": "lock for consumer 1", "attributes": {"anyKey": "anyValue"}}]' \
    --mode=remove_previous

Creating locks with the API

You can create up to 1000 locks on a secret by using the Secrets Manager API. Each lock can be used to represent a single application or consumer that uses your secret. A successful request attaches a new lock to your secret, or replaces a lock of the same name if it already exists.

A secret is considered locked after you attach one or more locks to it. A lock can be applied only on a secret version that contains active payload, or secret data.

To help you to create a new lock and remove older locks in a single operation, you can also specify an optional mode at lock creation.

Table 1. Optional lock modes and their descriptions
Mode	Query parameter	Description
Remove previous locks	`mode=remove_previous`	Removes any other locks that match the name that you specify. If any matching locks are found in the previous version of the secret, those locks are deleted when your new lock is created. For example, suppose that the previous version of your secret contains a lock `lock-x`. Creating a lock and enabling the `remove_previous` mode on the current secret version results in removing `lock-x` from the previous version.
Remove previous locks	`mode=remove_previous_and_delete`	Same as the `remove_previous` option, but also permanently deletes the data of the previous secret version if it doesn't have any locks that are associated with it. Suppose that the previous version of your secret contains a lock `lock-z`. Creating a lock and enabling the `remove_previous_and_delete` mode on the current secret version results in removing `lock-z` from the previous version. Additionally, because the previous version doesn't have any other locks that are attached to it, the secret data that is associated with the previous version is also deleted.

Creating locks on the current secret version

The following request creates two locks on the current version of a secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X POST 
-H "Authorization: Bearer {iam_token}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ 
      "locks": [ 
        { 
          "name": "lock-1", 
          "description": "Lock for consumer 1.", 
          "attributes": { 
            "key": "value" 
          } 
        }, 
        { 
          "name": "lock-2", 
          "description": "Lock for consumer 2.", 
          "attributes": { 
            "key": "value" 
            } 
          } 
        ] 
      }' \ 
    "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/locks_bulk"

If you're building an automated flow, you can use the attributes object to specify key-value data with each lock on your secret. For example, you can include a resource identifier, such as an ID or Cloud Resource Name (CRN).

A successful response returns details about the new locks, along with other metadata.

{
  "secret_id": "0cf4addb-7a90-410b-a3a7-a15bbe2b7909",
  "secret_group_id": "d8371728-95c8-4c12-b2af-1af98adb9e41",
  "versions": [
    {
      "version_id": "7bf3814d-58f8-4df8-9cbd-f6860e4ca973",
      "version_alias": "current",
      "locks": [
        "lock-3",
        "lock-4"
      ],
      "payload_available": true
    },
    {
      "version_id": "5bf89b0c-df55-c8d5-7ad6-8816951c6784",
      "version_alias": "previous",
      "locks": [
        "lock-1",
        "lock-2"
      ],
      "payload_available": true
    }
  ]
}

For more information about the required and optional request parameters, see the API reference.

Creating locks on the previous secret version

The following request creates two locks on the previous version of a secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X POST 
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
      "locks": [ 
        { 
          "name": "lock-1", 
          "description": "Lock for consumer 1.", 
          "attributes": { 
            "key": "value" 
            } 
          }, 
          { 
            "name": "lock-2", 
            "description": "Lock for consumer 2.", 
            "attributes": { 
              "key": "value" 
              } 
            } 
          ] 
        }' \ "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions/{version_id}/locks_bulk"

A successful response returns details about the new locks, along with other metadata.

{
  "secret_id": "0cf4addb-7a90-410b-a3a7-a15bbe2b7909",
  "secret_group_id": "d8371728-95c8-4c12-b2af-1af98adb9e41",
  "versions": [
    {
      "version_id": "7bf3814d-58f8-4df8-9cbd-f6860e4ca973",
      "version_alias": "current",
      "locks": [
        "lock-3",
        "lock-4"
      ],
      "payload_available": true
    },
    {
      "version_id": "5bf89b0c-df55-c8d5-7ad6-8816951c6784",
      "version_alias": "previous",
      "locks": [
        "lock-1",
        "lock-2"
      ],
      "payload_available": true
    }
  ]
}

For more information about the required and optional request parameters, see the API reference.

Unlocking secrets

A secret is considered unlocked and able to be modified or deleted only after all of its associated locks are removed. You can use the Secrets Manager UI or APIs to delete locks that are associated with a secret.

Deleting locks in the UI

You can delete a lock that is attached to an existing secret by using the Secrets Manager UI.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets Manager UI, go to the Secrets list.
In the row for the secret that you want to update, click the Actions menu > Locks.
In the row for the lock that you want to delete, click the Actions menu > Delete.
To confirm the deletion, type the name of the secret. Click Delete.

Your lock is now deleted. To completely unlock the secret, you can remove all existing locks.

Deleting locks with the API

You can use the Secrets Manager API to delete one or more locks that are associated with the specific secret version.

A successful request deletes the locks that you specify. To remove all locks, you can pass {"locks": ["*"]} in the request body. Otherwise, specify the names of the locks that you want to delete. For example, {"locks": ["lock-1", "lock-2"]}.

To understand whether a secret contains locks, check the locks_total field that is returned as part of the metadata of your secret.

curl -X DELETE  
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{secret_id}/versions/{id}/locks_bulk?name=[ "lock-example-1" ]"

For more information about the required and optional request parameters, see the API reference.