Automatically rotating secrets

You can schedule automatic rotation for secrets by using IBM Cloud® Secrets Manager.

When you rotate a secret in your service instance, you create a new version of its value. By scheduling automatic rotation of your secrets at regular intervals, you can reduce the likelihood of compromise and ensure that your credentials never expire.

Automatic rotation is available only for secrets that are generated by Secrets Manager. If the secret was imported initially, you must provide new secret data to rotate it. For more information, see Manually rotating secrets.

Before you begin

Before you get started, be sure that you have the required level of access. To rotate secrets, you need the Writer service role or higher.

Supported secret types

Automatic rotation is supported for private certificates, public certificates, user credentials, and IAM credentials. Depending on the type of secret, automatic rotation takes place immediately on the date and time that you set, or it might need to complete a few extra steps before a new version of the secret can be created.

Table 1. Describes how Secrets Manager evaluates manual rotation by secret type
Type	Rotation description
Private certificates	The existing `certificate` value is replaced with new certificate content. The time-to-live (TTL) of the renewed certificate is set according to the certificate template that was selected when the certificate was first created. After the time-to-live (TTL) or validity period of a private certificate exceeds the validity period of its issuing certificate authority, the certificate can no longer be rotated automatically.
Public certificates	Public certificates move to the Active, Rotation pending status to indicate that the request to renew the certificate is being processed. Secrets Manager uses DNS validation to verify that you own the domains that are listed as part of the certificate. This process can take a few minutes to complete. If the validation completes successfully, a new certificate is issued and its status changes back to Active. If the validation doesn't complete successfully, the status of the certificate changes to Active, Rotation failed.
User credentials	The existing `password` value is replaced with a randomly generated 32-character password that contains uppercase letters, lowercase letters, digits, and symbols. The `username` value does not change.
IAM credentials	The Service ID's API key value is replaced with a new API key. The previous API key remains available for the remaining time in the defined TTL.
Service credentials	The Service credential is replaced with a new one. The previous credential remains available for the remaining time in the defined TTL.

Note that in the case of service credentials created for Databases, if in addition to the credential you are also altering the database permissions for the created credential, these will not be synced once the service credential was rotated. When rotating a Databases service credential, this is considered an identity rotation.

Scheduling automatic rotation in the UI

You can schedule the automatic rotation of secrets by using the Secrets Manager UI.

Setting an automatic rotation policy for user credentials

If you prefer to schedule your passwords to be automatically rotated at regular intervals, you can enable automatic rotation for your user credentials at their creation. You can also enable auto rotation by editing the details of an existing secret.

If you need more control over the rotation frequency of a secret, you can use the Secrets Manager API to set a custom interval by using day or month units of time. For more information, see the API reference.

If you're adding a secret, enable the rotation option.
If you're editing an existing secret, enable automatic rotation by updating its details.
1. In the Secrets table, view a list of your existing secrets.
2. In the row for the secret that you want to edit, click the Actions menu > Edit details.
3. Use the Automatic rotation option to enable or disable automatic rotation for the secret.

When you update a secret's rotation settings, you trigger an immediate rotation.

Setting an automatic rotation policy for public certificates

If you prefer to schedule your public SSL/TLS certificates to be automatically renewed, you can enable automatic rotation for certificates when you order them. You can also enable auto rotation by editing the details of an existing certificate. In the certificate's next rotation cycle, Secrets Manager begins attempting to reorder the certificate 31 days before its expiry date. The service continues to attempt to renew the certificate daily until it is successful.

If you're ordering a public certificate, enable the rotation options.
1. To rotate the certificate automatically, switch the rotation toggle to On. Your certificate is automatically reordered 31 days before its expiration date.
2. To request a new private key for the certificate on each rotation, switch the rekey toggle to On.
If you're editing an existing public certificate, schedule automatic rotation by updating its details.
1. In the Secrets table, view a list of your existing Public certificates.
2. In the row for the certificate that you want to edit, click the Actions menu > Edit details.
3. Use the Automatic rotation option to add or remove a rotation policy for the secret.

Setting an automatic rotation policy for private certificates

If you prefer to schedule your private SSL or TLS certificates to be automatically renewed, you can enable automatic rotation for certificates when you create them, or by editing the details of an existing certificate. The certificate must

If you're creating private certificates, enable the rotation options.
1. To rotate the certificate automatically, switch the rotation toggle to On.
2. Select an interval and unit that specifies the number of days between scheduled rotations.
  
  Depending on the certificate template that is associated with your private certificate, some restrictions on the rotation interval for the certificate might apply. For example, the rotation interval can't exceed the time-to-live (TTL) that is defined in the template. For more information, see Certificate templates.
If you're editing an existing private certificate, schedule automatic rotation by updating its details.
1. In the Secrets table, view a list of your existing Private certificates.
2. In the row for the certificate that you want to edit, click the Actions menu > Edit details.
3. Use the Automatic rotation option to add or remove a rotation policy for the secret.

Setting an automatic rotation policy for IAM credentials

If you prefer to schedule your API key to be automatically rotated at regular intervals, you can enable automatic rotation for your IAM credentials at their creation. You can also enable auto rotation by editing the details of an existing secret. Choose between a 30, 60, or 90-day rotation interval.

If you're adding a secret, enable the rotation option by selecting a 30, 60, or 90-day rotation interval.
If you're editing an existing secret, enable automatic rotation by updating its details.
1. In the Secrets table, view a list of your existing secrets.
2. In the row for the secret that you want to edit, click the Actions menu > Edit details.
3. Use the Automatic rotation option to enable or disable automatic rotation for the secret.

Rotation is available only for IAM credentials where the reuse key is set to true. The defined rotation interval cannot be higher than the defined time-to-live (TTL). You can set the TTL for secrets by using minute units of time but rotation is not available for those secrets.

Setting an automatic rotation policy for Service credentials

If you prefer to schedule your service credential to be automatically rotated at regular intervals, you can enable automatic rotation for your Service credentials at their creation. You can also enable auto rotation by editing the details of an existing secret. Choose between a 30, 60, or 90-day rotation interval.

If you're adding a secret, enable the rotation option by selecting a 30, 60, or 90-day rotation interval.
If you're editing an existing secret, enable automatic rotation by updating its details.
1. In the Secrets table, view a list of your existing secrets.
2. In the row for the secret that you want to edit, click the Actions menu > Edit details.
3. Use the Automatic rotation option to enable or disable automatic rotation for the secret.

Scheduling automatic rotation from the CLI

You can schedule the automatic rotation of secrets by using the Secrets Manager CLI plug-in.

Setting an automatic rotation policy for user credentials

Schedule the automatic rotation for user credentials by using the ibmcloud secrets-manager secret-metadata-update.

ibmcloud secrets-manager secret-metadata-update \
    --id=SECRET_ID \
    --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'

To remove a policy, keep the resources block empty.

Setting an automatic rotation policy for public certificates

Schedule the automatic rotation for public certificates by using the ibmcloud secrets-manager secret-metadata-update.

ibmcloud secrets-manager secret-metadata-update \
    --id=SECRET_ID \
    --rotation='{"auto_rotate": true, "rotate_keys": true}'

Setting an automatic rotation policy for private certificates

Schedule the automatic rotation for private certificates by using the ibmcloud secrets-manager secret-metadata-update.

ibmcloud secrets-manager secret-metadata-update \
    --id=SECRET_ID \
    --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'

Setting an automatic rotation policy for IAM credentials

Schedule the automatic rotation for IAM credentials by using the ibmcloud secrets-manager secret-metadata-update.

ibmcloud secrets-manager secret-metadata-update \
    --id=SECRET_ID \
    --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'

To remove a policy, keep the resources block empty.

Setting an automatic rotation policy for Service credentials

Schedule the automatic rotation for service credentials by using the ibmcloud secrets-manager secret-metadata-update.

ibmcloud secrets-manager secret-metadata-update \
    --id=SECRET_ID \
    --rotation='{"auto_rotate": true,"interval": 30,"unit": "day"}'

To remove a policy, keep the resources block empty.

Scheduling automatic rotation with the API

You can schedule the automatic rotation of secrets by using the Secrets Manager API.

Setting an automatic rotation policy for user credentials

The following example request creates an automatic rotation policy for a user credentials (username_password) 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 PATCH 
   -H "Authorization: Bearer {iam_token}" \
   -H "Accept: application/json" \
   -H 'Content-Type: application/merge-patch+json' \
   -d '{
            "rotation": {
               "auto_rotate": true,
               "interval": 1, 
               "unit": "month"
            } 
         }' \ 
      "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/metadata"

A successful response returns the ID value for the secret, along with other metadata. For more information about the required and optional request parameters, see the API reference.

To remove a policy, keep the resources block empty.

Setting an automatic rotation policy for public certificates

If you prefer to schedule your certificates to be automatically renewed, you can enable automatic rotation for certificates when you order them, or by editing the details of an existing certificate. In the certificate's next rotation cycle, Secrets Manager reorders the certificate 31 days before its expiry date.

Ordering a public certificate that renews automatically

The following example request orders a certificate with automatic rotation enabled. When you call the API, set the auto_rotate property to true. Optionally, you can set rotate_keys to true to request a new private key for the certificate on each rotation.

curl -X POST 
   -H "Authorization: Bearer {iam_token}" \
   -H "Accept: application/json" \
   -H "Content-Type: application/json" \
   -d '{
         "custom_metadata": {
            "metadata_custom_key": "metadata_custom_value"
         },
         "rotation": {
            "auto_rotate": true,
            "rotate_keys": true
         },
         "version_custom_metadata": {
            "custom_version_key": "custom_version_value"
         }
      }' \ 
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful response returns the ID value for the certificate, along with other metadata. For more information about the required and optional request parameters, check out the API reference.

Setting an automatic rotation policy for IAM credentials

The following example request creates an automatic rotation policy for a IAM credentials (iam_credentials) 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 PATCH 
   -H "Authorization: Bearer {iam_token}" \
   -H "Accept: application/json" \
   -H 'Content-Type: application/merge-patch+json' \
   -d '{
          "rotation": {
            "auto_rotate": true,
            "interval": 30,
            "unit": "day"
          } 
         }' \ 
      "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/metadata"

To remove a policy, keep the resources block empty.

A successful response returns the ID value for the secret, along with other metadata. For more information about the required and optional request parameters, see the API reference.

The defined rotation interval cannot be higher than the defined time-to-live. Rotation is available only for IAM credentials where the Re-use key is set to true. You can set the TTL for secrets by using minute units of time but rotation is not available for those secrets.

Setting an automatic rotation policy for Service credentials

The following example request creates an automatic rotation policy for a Service credential (service_credentials) 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 PATCH 
   -H "Authorization: Bearer {iam_token}" \
   -H "Accept: application/json" \
   -H 'Content-Type: application/merge-patch+json' \
   -d '{
          "rotation": {
            "auto_rotate": true,
            "interval": 30,
            "unit": "day"
          } 
         }' \ 
      "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/metadata"

To remove a policy, keep the resources block empty.

A successful response returns the ID value for the secret, along with other metadata. For more information about the required and optional request parameters, see the API reference.

The defined rotation interval cannot be higher than the defined time-to-live.