This topic describes typical secret rotation scenarios and related operations.

If a business system uses Key Management Service (KMS) Secrets Manager, the following two types of roles are involved in secret-related activities:

  • Secret consumer: the business application that uses a secret. A secret consumer calls the GetSecretValue operation on a schedule to retrieve the latest version of the plaintext secret value, with which it accesses the target system.
  • Secret producer: the IT O&M system or security O&M administrator of an enterprise. The secret producer calls the CreateSecret operation to create a secret object, in which it stores the initial secret value. If the secret producer needs to rotate the secret on a schedule, it calls the PutSecretValue operation to store a new version in the secret object.
The following figure shows the secret rotation mechanism of Secrets Manager.1

Simulated scenarios

The following prerequisites must be met:
  • Your O&M system has stored the initial version of a secret in a secret object. The initial version is marked with ACSCurrent.
  • The application that needs to use the secret retrieves the secret value on a schedule by calling GetSecretValue. To retrieve the secret value, the application only needs to specify the secret name on the KMS client. The KMS server returns the secret value of the version marked with ACSCurrent.

Your O&M system rotates the secret and stores the new version of the secret value. After the new version is marked with ACSCurrent, the KMS client retrieves the new secret value.

Scenario 1: Call a single API operation to rotate a secret

You can call a single API operation to complete a rotation in the following situation: A newly generated secret takes effect in the target system before it is stored in Secrets Manager. For example, in most cases, App Secrets for OAuth 2.0 are generated in the system. You can use Secrets Manager to manage them. The rotation process is as follows:
  1. An administrator generates a new App Secret in OAuth 2.0.
  2. The administrator stores the new App Secret in Secrets Manager, where it is marked with ACSCurrent. The original version marked with ACSCurrent is marked with ACSPrevious.
    $ aliyun kms PutSecretValue \
      --SecretName MyOAuthAppSecret 
      --SecretData sample-app-secret \
      --VersionId v2

The GetSecretValue operation returns the App Secret of the version marked with ACSCurrent.

Scenario 2: Call multiple API operations to rotate a secret

In most cases, the target system does not automatically generate secrets. For example, an ApsaraDB for RDS database does not automatically generate an account, and an ECS instance does not automatically generate an SSH key. In this situation, you need to store a new secret value in Secrets Manager as the version marked with MyPendingLabel. Then, you need to register the new secret value with the target system, and finally change the stage label that marks the version from MyPendingLabel to ACSCurrent in Secrets Manager.

To update a user password of a database managed in Secrets Manager, you need to perform the following operations:
  1. The rotation program generates a random string as the new password.

    The password is generated by calling GetRandomPassword of Secrets Manager.

    $ aliyun kms GetRandomPassword --ExcludePunctuation true                       
    {
        "RequestId": "e36ca295-6e47-4dfb-9df1-48d19df4****",
        "RandomPassword": "v2GwsgcuNylyYw9JGJNE5yBViGSi****"
    }
  2. Store the new username and password of the database as a new version in the existing secret object.

    You can run the following commands to store the new username and password and mark them with MyPendingLabel. The existing versions marked with ACSCurrent and ACSPrevious are not changed.

    $ aliyun kms PutSecretValue \
        --SecretName db_cred 
        --SecretData "{\"uname\": \"alice\", \"pwd\": \"v2GwsgcuNylyYw9JGJNE5yBViGSiZ****"}" \
        --VersionId v2 \
        --VersionStages "[\"MyPendingLabel\"]"
  3. Register the new username and password with the target database.

    Only the secret value of the v2 version in the secret object db_cred can be used to access the target database.

  4. After the new username and password are registered, you can run the following CLI command to mark the new version stored in the secret object with ACSCurrent:
    $ aliyun kms UpdateSecretVersionStage \
        --SecretName db_cred \
        --VersionStage ACSCurrent \
        --MoveToVersion v2

The GetSecretValue operation returns the username and password of the version marked with ACSCurrent.