Key Management Service:Manage and use RAM secrets

Feature description

If you use Key Management Service (KMS) to manage a RAM secret, you do not need to configure an AccessKey pair in your application. You need to only configure a secret name, which can be used to retrieve a valid AccessKey pair for calling operations. You can also rotate RAM secrets to reduce the risk of AccessKey pair leaks.

Limits

Only the AccessKey pair of a RAM user can be managed. The AccessKey pair of an Alibaba Cloud account cannot be managed.

RAM secret rotation

During rotation, RAM creates an AccessKey pair and then deletes the old AccessKey pair. KMS writes the new AccessKey as a secret value and deletes the secret value that is associated with the old AccessKey pair. Secret rotation supports the following two methods.

Prerequisites

• A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.

• A symmetric key that is used to encrypt secrets is created in the KMS instance. For more information, see Getting started with keys.

• If you use a RAM user or a RAM role to manage RAM secrets, the AliyunKMSSecretAdminAccess and AliyunRAMFullAccess system policies are attached to the RAM user or the RAM role. For more information, see Grant permissions to a RAM user or Grant permissions to a RAM role.

Step 1: Grant KMS the permissions to manage the AccessKey pair of a RAM user

1. Create a custom policy

1. Log on to the RAM console as a RAM user who has administrative rights.

2. In the left-side navigation pane, choose Permissions > Policies.

3. On the Policies page, click Create Policy.

4. Click the JSON tab and enter the following script:

   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ram:ListAccessKeys",
           "ram:CreateAccessKey",
           "ram:DeleteAccessKey",
           "ram:UpdateAccessKey"
         ],
         "Resource": "*"
       }
     ]
   }

5. Click Next to edit policy information. On the page that appears, configure the Name and Description parameters. In this example, set the Name parameter to AliyunKMSManagedRAMCrendentialsRolePolicy.

6. Click OK.

2. Create a RAM role and attach the custom policy to the role

1. Log on to the RAM console as a RAM user who has administrative rights.

2. In the left-side navigation pane, choose Identities > Roles.

3. On the Roles page, click Create Role.

4. On the Create Role page, select Alibaba Cloud Service in the Select Trusted Entity section and click Next.

5. Select Normal Service Role for the Role Type parameter.

6. Configure the RAM Role Name and Note parameters. In this example, set the RAM Role Name parameter to AliyunKMSManagedRAMCrendentialsRole.

7. Select Key Management Service as the trusted service and click OK.

8. In the Finish step, click Add Permissions to RAM Role. In the Add Permissions panel, the Principal parameter is automatically configured.

9. In the Grant Permission panel, click Custom Policy, select the AliyunKMSManagedRAMCrendentialsRolePolicy policy, and then click OK. Then, click Complete.

Step 2: Create an AccessKey pair of a RAM user

An AccessKey pair is a permanent access credential that is provided by Alibaba Cloud to a user. An AccessKey pair consists of an AccessKey ID and an AccessKey secret.

• The AccessKey ID is used to identify a user.

• The AccessKey secret is used to verify the identity of the user.

1. Log on to the RAM console.

2. In the left-side navigation pane, choose Identities > Users.

3. On the Users page, click the username of the RAM user that you want to manage.

4. In the AccessKey section, click Create AccessKey.

5. In the Create AccessKey message, view the AccessKey ID and AccessKey secret.

   You can click Download CSV File to download the AccessKey pair or click Copy to copy the AccessKey pair.

Step 3: Create a RAM secret

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.

2. Click the RAM Secrets tab, select the required instance ID from the Instance ID drop-down list, and then click Create Secret. Then, configure the parameters and click OK.

   Parameter	Description
   Select RAM User	The RAM user for which you want to create the secret. The selected RAM user must have at least one AccessKey pair.
   Secret Value	The AccessKey secret of the RAM user. The value cannot exceed 30,720 bytes in length, which is equivalent to 30 KB in size.
   CMK	The key that is used to encrypt the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications.
   Tag	The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair. Note A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), and at signs (@). A tag key cannot start with aliyun or acs:. You can configure up to 20 key-value pairs for each secret.
   Automatic Rotation	Specifies whether to enable automatic secret rotation.
   Days (7 Days to 365 Days):	The interval of automatic secret rotation. This setting is required only when you select Enable Automatic Rotation. KMS periodically updates the secret based on the value of this parameter.
   Description	The description of the secret.
   Advanced Settings	The policy settings of the secret. Default Policy: If the secret is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy. If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the secret. If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1. Secrets created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the secrets. Secrets created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the secrets. Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the secret, select Custom Policy. Important Administrators and users do not consume Access Management Quota. Cross-account users consume Access Management Quota of the KMS instance. The consumed quota is calculated based on the number of Alibaba Cloud accounts. If you revoke the permissions, wait approximately 5 minutes and then query the quota. The consumed quota is restored. When you use a secret, you must have the permission to use the required key to decrypt the secret. An administrator can manage the secret but cannot retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by administrators { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:PutSecretValue", "kms:Update*", "kms:DeleteSecret", "kms:RestoreSecret", "kms:RotateSecret", "kms:TagResource", "kms:UntagResource" ] } ] } A user can retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account. Permissions supported by users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] } A cross-account user can retrieve the secret value. You can select RAM users and RAM roles within other Alibaba Cloud accounts. RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: aacs:ram::119285303511****:user/testpolicyuser. RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole. Note After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the secret in RAM. Then, the RAM user or RAM role can use the secret. For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role. Permissions supported by cross-account users { "Statement": [ { "Action": [ "kms:List*", "kms:Describe*", "kms:GetSecretValue", ] } ] }

Step 4: Integrate the RAM secret into an application

KMS provides various SDKs. We recommend that you select SDKs in the following order of priority.

What to do next

Rotate a RAM secret

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.

2. Click the RAM Secrets tab, select the required instance ID from the Instance ID drop-down list, find the secret that you want to rotate, and then click Details in the Actions column.

3. Configure a secret rotation policy.

   • Automatic rotation: In the upper-right corner of the page, click Configure Rotation Policy, enable or disable Automatic Rotation, and then click OK.

   • Immediate rotation: In the upper-right corner of the page, click Rotate Now. In the Configure Rotation Policy dialog box, set the Rotation Window parameter to a value that ranges from 10 minutes to 2 days, and then click OK.

Delete a RAM secret

You can immediately delete a secret or create a scheduled task to delete a secret. If you delete a RAM secret, the RAM secret is deleted only from Secrets Manager. The AccessKey pair of the RAM user that is associated with the RAM secret is not deleted from RAM.

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.

2. Click the RAM Secrets tab, select the required instance ID from the Instance ID drop-down list, find the secret that you want to delete, and then click Schedule Deletion in the Actions column.

3. In the Schedule Deletion dialog box, select a method to delete the secret and click OK.

   • If you select Schedule Deletion, configure Retention Period (7 to 30 Days). When the scheduled deletion period ends, KMS deletes the secret.

   • If you select Delete Immediately, the system immediately deletes the secret.

   During the scheduled deletion period, you can click Restore Secret in the Actions column to cancel the deletion.

Add tags to secrets

Check accounts

The account check feature allows you to check whether a RAM user indicated by a RAM secret exists and whether the AccessKey ID of the RAM user is the same as that stored in the secret.

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.

2. Click the RAM Secrets tab, select the required instance ID from the Instance ID drop-down list, find the secret that you want to manage, and then click Details in the Actions column.

3. In the Versions section, click Check Account. After the check is complete, view the check result.

FAQ

When I configure a secret rotation policy or immediately rotate a secret, the system prompts the error message "Your secret is being rotated. Try again later." What is the reason?