Manually rotating secrets

Rotating arbitrary secrets

You can use the Secrets Manager UI to manually rotate your arbitrary secrets.

1. In the console, click the Menu icon > Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu > Rotate.
5. Select a new file or enter a new secret value.
6. Optional: Add metadata to your secret or to a specific version of your secret.
   1. Upload a file or enter the metadata and the version metadata in JSON format.
7. To rotate the secret immediately, click Rotate.
8. Optional: Check the version history to view the latest updates.

Creating new versions of key-value secrets

You can use the Secrets Manager UI to manually rotate your key-value secrets.

1. In the console, click the Menu icon > Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu > Rotate.
5. Select a file or enter a new secret value in JSON format.
6. Optional: Add metadata to your secret or to a specific version of your secret.
   1. Upload a file or enter the metadata and the version metadata in JSON format.
7. To rotate the secret immediately, click Rotate.
8. Optional: Check the version history to view the latest updates.

Creating new versions of user credentials

You can use the Secrets Manager UI to manually rotate the password values that are associated with a user credentials secret.

1. In the console, click the Menu icon > Resource List.

2. From the list of services, select your instance of Secrets Manager.

3. In the Secrets Manager UI, go to the Secrets list.

4. In the row for the secret that you want to rotate, click the Actions menu > Rotate.

5. Determine whether to enter your own password or generate a new one.

   If you choose to generate a new password, Secrets Manager replaces the existing value with a randomly generated 32-character password that contains uppercase letters, lowercase letters, digits, and symbols.

6. Optional: Add metadata to your secret or to a specific version of your secret.

   1. Upload a file or enter the metadata and the version metadata in JSON format.

7. To rotate the secret immediately, click Rotate.

8. Optional: Check the version history to view the latest updates.

Creating new versions of iam credentials

You can use the Secrets Manager UI to manually rotate the password values that are associated with an IAM credentials secret.

1. In the console, click the Menu icon > Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu > Rotate.
5. Optional: Add metadata to your secret or to a specific version of your secret.
   1. Upload a file or enter the metadata and the version metadata in JSON format.
6. To rotate the secret immediately, click Rotate.
7. Optional: Check the version history to view the latest updates.

Creating new versions of service credentials

You can use the Secrets Manager UI to manually rotate the password values that are associated with a Service credentials secret.

1. In the console, click the Menu icon > Resource List.
2. From the list of services, select your instance of Secrets Manager.
3. In the Secrets Manager UI, go to the Secrets list.
4. In the row for the secret that you want to rotate, click the Actions menu > Rotate.
5. Optional: Add metadata to your secret or to a specific version of your secret.
   1. Upload a file or enter the metadata and the version metadata in JSON format.
6. To rotate the secret immediately, click Rotate.
7. Optional: Check the version history to view the latest updates.

Creating new versions of imported certificates

When it's time to renew a certificate that was initially imported to the service, you can use the Secrets Manager UI to manually reimport it. After a certificate is rotated, the previous version is retained in case you need it.

If the certificate that you are rotating was previously imported with an intermediate certificate and a private key, include an intermediate certificate and private key on rotation to avoid service disruptions.

1. In the console, click the Menu icon > Resource List.

2. From the list of services, select your instance of Secrets Manager.

3. In the Secrets Manager UI, go to the Secrets list.

4. In the row for the certificate that you want to rotate, click the Actions menu > Rotate.

5. Select or enter the new certificate data.

   Keep in mind that manually rotating a certificate replaces the content of the certificate with the new data that you provide only. Private keys and intermediate certificates from previous versions are not retained.

6. To rotate the certificate immediately, click Rotate.

7. Optional: Check the version history to view the latest updates.

8. Redeploy the latest certificate version to your TLS termination point.

   To access the current version, you can download the certificate or retrieve it programmatically by using the Get a secret API.

Creating new versions of public certificates

If your Secrets Manager service instance is enabled for public certificates, you can manually renew a certificate that was previously ordered from a third-party certificate authority.

1. In the console, click the Menu icon > Resource List.

2. From the list of services, select your instance of Secrets Manager.

3. In the Secrets Manager UI, go to the Secrets list.

4. In the row for the certificate that you want to rotate, click the Actions menu > Rotate.

5. Optional: Add metadata to your secret or to a specific version of your secret.

   1. Upload a file or enter the metadata and the version metadata in JSON format.

6. Click Rotate.

   A success message is displayed to indicate that your order is being processed. If the validation completes successfully, a new certificate is issued and the status of the certificate changes from Active, Rotation pending back to Active. If the validation doesn't complete successfully, the status of the certificate changes to Active, Rotation failed.

7. Optional: Check the issuance details of a certificate.

   You can check the issuance details of a public certificate by clicking the Actions icon > Details. If there was an issue with the request, the Status field provides information about why the rotation did not complete successfully.

8. Redeploy the latest certificate version to your TLS termination point.

   To access the current version, you can download the certificate or retrieve it programmatically by using the Get a secret API.

Creating new versions of public certificates with your own DNS provider in the UI

To rotate a public certificate that was created by using a manual DNS provider in the UI, complete the following steps.

1. In the console, click the Menu icon > Resource List.

2. From the list of services, select your instance of Secrets Manager.

3. In the row for the certificate that you want to rotate, click the Actions menu > Rotate.

4. Optional: Add a name and description to easily identify your certificate.

5. Optional: Click Update.

6. Click Challenges to access the TXT record name and value that are associated with each of your domains. You need them to complete the challenges.

7. To validate the ownership of your domains, manually add the TXT records that are provided for each of your domains to your DNS provider account. You must address only the challenges that are not validated, before the expiration date.

   If you order a certificate for subdomains, for example, sub1.sub2.domain.com, you need to add the TXT records to your registered domain domain.com.

8. Verify that the TXT records that you added to your domains are propagated. Depending on your DNS provider, it can take some time to complete.

9. After you confirm that the records are propagated, click Validate to request Let's Encrypt to validate the challenges to your domains and create a public certificate.

   If the order fails, for example, if the TXT records were not successfully propagated, you must start a new order to proceed.

10. When your certificate is issued, clean up and remove the TXT records from the domains in your DNS provider account.

Creating new versions of private certificates

If your Secrets Manager service instance is enabled for private certificates, you can manually renew a certificate that was previously issued by a certificate authority that is configured for your service instance.

1. In the console, click the Menu icon > Resource List.

2. From the list of services, select your instance of Secrets Manager.

3. In the Secrets Manager UI, go to the Secrets list.

4. In the row for the certificate that you want to rotate, click the Actions menu > Rotate.

5. Optional: Add metadata to your secret or to a specific version of your secret.

   1. Upload a file or enter the metadata and the version metadata in JSON format.

6. Click Rotate.

7. Redeploy the latest certificate version to your TLS termination point.

   To access the current version, you can download the certificate or retrieve it programmatically by using the Get a secret API.

Rotating arbitrary secrets

To rotate an arbitrary secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-version-create command. For example, the following command rotates a secret and assigns new-secret-data as its new version.

ibmcloud secrets-manager secret-version-create \    
   --secret-id=SECRET_ID \    
   --secret-version-prototype='{"payload": "updated secret credentials", "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-version-create.

Rotating user credentials

To rotate a user credential secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-version-create command. For example, the following command rotates a secret and assigns new-password as its new version.

ibmcloud secrets-manager secret-version-create \    
   --secret-id=SECRET_ID \    
   --secret-version-prototype='{"password": "new-password", "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'

To have the service generate and assign a random password to your credential, omit the password field. For example, {}. Secrets Manager replaces the existing value with a randomly generated 32-character password that contains uppercase letters, lowercase letters, digits, and symbols.

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-version-create.

Rotating IAM credentials

To rotate an IAM credential secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-version-create command. For example, the following command will create a new API key

ibmcloud secrets-manager secret-version-create \    
   --secret-id=SECRET_ID

Manually rotating an IAM credentials is possible only if Reuse IAM credentials is set to Off.

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-version-create.

Rotating imported certificates

To reimport a certificate by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-version-create command. For example, the following command rotates a secret and assigns new-secret-data as its new version.

ibmcloud secrets-manager secret-version-create \    
   --secret-id=SECRET_ID \    
   --secret-version-prototype='{"certificate": "new-secret-data", "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'

Replace new lines in the certificate, intermediate, and private key data with \n.

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-version-create.

Rotating Public certificates

To order a new public certificate secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-version-create command.

ibmcloud secrets-manager secret-version-create \
   --secret-id SECRET_ID \
   --public-cert-rotation '{"rotate_keys": true|false}'

When rotating a certificate, choose if to also rotate its private key to assigning true or false for the rotate_keys field.

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-version-create.

Rotating KV secrets

To rotate a KV secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-version-create command. For example, the following command rotates a secret and assigns new-secret-data as its new version.

ibmcloud secrets-manager secret-version-create \    
   --secret-id=SECRET_ID \    
   --secret-version-prototype='{"data": {"key":"value"}, "custom_metadata": {"anyKey": "anyValue"}, "version_custom_metadata": {"anyKey": "anyValue"}}'

The command outputs the value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-version-create.

Rotating arbitrary secrets

You can rotate arbitrary secrets by calling the Secrets Manager API.

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

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

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" 
            }, 
         "payload": "Updated arbitrary data", 
         "version_custom_metadata": { 
            "custom_version_key": "custom_version_value" 
            } 
         }' \ 
      "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

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

Rotating key-value secrets

You can rotate key-value secrets by calling the Secrets Manager API.

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

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

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" 
         }, 
      "data": {
            "key1": "val2"
         },
      "version_custom_metadata": { 
         "custom_version_key": "custom_version_value" 
         }
      }' \ 
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

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

Rotating user credentials

You can rotate secrets by calling the Secrets Manager API.

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

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

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" 
         }, 
      "password": "new-password",
      "version_custom_metadata": { 
         "custom_version_key": "custom_version_value" 
         } 
      }' \ 
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

To have the service generate and assign a random password to your credential, omit the password field. For example, {}. Secrets Manager replaces the existing value with a randomly generated 32-character password that contains uppercase letters, lowercase letters, digits, and symbols.

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

Rotating IAM credentials

You can rotate secrets by calling the Secrets Manager API.

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

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

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" 
         }, 
      "version_custom_metadata": { 
         "custom_version_key": "custom_version_value" 
         } 
      }' \ 
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

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

Rotating Service credentials

You can rotate secrets by calling the Secrets Manager API.

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

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

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" 
         }, 
      "version_custom_metadata": { 
         "custom_version_key": "custom_version_value" 
         } 
      }' \ 
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

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

Rotating imported certificates

You can rotate secrets by calling the Secrets Manager API.

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

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

curl -X POST \
   -H "Authorization: Bearer {iam_token}" \
   -H "Accept: application/json" \
   -H "Content-Type: application/json" \
   -d '{
         "certificate": "-----BEGIN CERTIFICATE-----\nMIIE3jCCBGSgAwIBAgIUZfTbf3adn87l5J2Q2Aw+6Vk/qhowCgYIKoZIzj0EAwIwx\n-----END CERTIFICATE-----", "custom_metadata": {
            "metadata_custom_key": "metadata_custom_value"
         },
         "intermediate": "-----BEGIN CERTIFICATE-----\nMIIE3DCCBGKgAwIBAgIUKncnp6BdSUKAFGBcP4YVp/gTb7gwCgYIKoZIzj0EAwIw\n-----END CERTIFICATE-----",
         "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAqcRbzV1wp0nVrPtEpMtnWMO6Js1q3rhREZluKZfu0Q8SY4H3\n-----END RSA PRIVATE KEY-----", "version_custom_metadata": {
            "custom_version_key": "custom_version_value"
         }
      }' \ 
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

Replace new lines in the certificate, intermediate, and private key data with \n.

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

Rotating arbitrary secrets

You can rotate arbitrary secrets by using Terraform for Secrets Manager.

To rotate an arbitrary secret, modify the value of the payload attribute in your ibm_sm_arbitrary_secret resource configuration, and run terraform apply to apply the change. If you're using an input variable for the payload, modify its value in the variables.tf file.

You can also modify other attributes of the arbitrary secret at the same time, including metadata attributes such as description, custom_metadata, or version_custom_metadata.

Rotating key-value secrets

To rotate a key-value secret by using Terraform for Secrets Manager, modify the value of the data attribute in your ibm_sm_kv_secret resource configuration, and run terraform apply to apply the change. If you're using an input variable for the payload, modify its value in the variables.tf file.

You can also modify other attributes of the key-value secret at the same time, including metadata attributes such as description, custom_metadata or version_custom_metadata.

Rotating imported certificates

You can rotate imported certificates by using Terraform for Secrets Manager.

To rotate an imported certificate, modify the values of the certificate, intermediate (optional) and private_key (optional) attributes in your ibm_sm_imported_certificate resource configuration, and run terraform apply to apply the change.

You can also modify other attributes of the imported certificate at the same time, including metadata attributes such as description, custom_metadata or version_custom_metadata.