All Products
Search
Document Center

Key Management Service:Manage and use RAM secrets

Last Updated:Feb 23, 2024

A Resource Access Management (RAM) secret is the AccessKey pair of a RAM user. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. You can configure a RAM secret to authenticate the RAM user during API operations. This prevents the need for hard-coded AccessKey pairs and minimizes the risk of disclosure. This topic describes how to 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.

image.png

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.

Rotation method

Rotation period

Scenario

Automatic rotation

About 2 days

A RAM secret is integrated into an application. The application periodically reads the RAM secret.

To minimize the risk of AccessKey pair leaks, we recommend that you specify an automatic rotation period of no more than three months.

Immediate rotation

You can specify a rotation period ranging from 10 minutes to 2 days.

If a RAM secret is leaked, we recommend that you specify a rotation period of 30 minutes. In other scenarios, a rotation period of 2 days is optimal.

  • If you find that a Resource Access Management (RAM) secret is leaked, you can immediately rotate the secret as an emergency response.

  • When an application retrieves a RAM secret, you can manually trigger rotation.

Important
  • If a RAM secret is being rotated, do not delete the RAM user that is associated with the secret. This helps prevent secret rotation failures.

  • If a RAM secret is being rotated, you cannot specify an automatic rotation policy or perform immediate rotation.

Prerequisites

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 to an Alibaba Cloud user. The user can use the AccessKey pair to access Alibaba Cloud by using a development tool such as the API, CLI, SDK, Cloud Shell, and Terraform. The AccessKey pair cannot be used for console logons.

  • The AccessKey ID is used to identify a user.

  • The AccessKey secret is used to verify the identity of the user. You must keep your AccessKey secret strictly confidential.

  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 AccessKeys 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.

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.

Note

KMS provides multiple authentication methods. For higher security, we recommend you use the client key of an application access endpoint (AAP), an instance RAM role that is attached to an ECS instance, or a RAM role.

Priority

Requirement

Supported authentication method

Endpoint

Priority 1: RAM secret plug-in

Your application is developed in Java 8 or later, Go, or Python and developed by using an Alibaba Cloud SDK supported by the RAM secret plug-in. For more information about supported Alibaba Cloud SDKs, see RAM secret plug-in.

Client key of an AAP

The API that is called varies based on the endpoint:

  • (Recommended) KMS instance endpoint: KMS Instance API is called. A KMS instance endpoint is in the {Instance ID}.cryptoservice.kms.aliyuncs.com format.

    Note

    To obtain the endpoint of a KMS instance, go to the Instances page, view the details of the instance, obtain the value of Instance VPC Endpoint, and remove https:// from the value.

  • KMS endpoint: KMS API is called. For more information, see Endpoints.

Instance RAM role attached to an ECS instance

KMS endpoint: KMS API is called. For more information, see Endpoints.

Priority 2: Secrets Manager Client

Your application is developed in Java 8 or later, Go, or Python.

Client key of an AAP

The API that is called varies based on the endpoint:

  • (Recommended) KMS instance endpoint: KMS Instance API is called. A KMS instance endpoint is in the {Instance ID}.cryptoservice.kms.aliyuncs.com format.

  • KMS endpoint: KMS API is called. For more information, see Access point description.

  • RAM role

  • Instance RAM role attached to an ECS instance

  • AccessKey

  • STS Token

The KMS endpoint: KMS API is called. For more information, see Endpoints.

Priority 3: KMS Instance SDK

Your application is developed in Java 8 or later, PHP, Go, Python, or .NET (C# only).

Client key of an AAP

KMS instance endpoint: KMS Instance API is called. A KMS instance endpoint is in the {Instance ID}.cryptoservice.kms.aliyuncs.com format.

Priority 4: Alibaba Cloud SDK

An application is developed in Java 6 or later, PHP, Go, Python, .NET (C# only), C++, or Node.js.

  • Instance RAM role attached to an ECS instance

  • AccessKey

The KMS endpoint: KMS API is called. For more information, see Endpoints.

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.

Warning

Before you delete a RAM secret, make sure that the RAM secret is no longer in use. If you delete a RAM secret that is in use, service failures may occur.

  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 for secrets

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.

Add tags for a secret

Method

Description

Method 1: Add tags on the Secrets page

  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 a tab based on the type of your secret, select the required instance ID from the Instance ID drop-down list, find the secret to which you want to add tags, and then click the image.png icon in the Tag column.

  3. Click Add. In the Edit Tag dialog box, enter multiple Tag Key and Tag Value, and then click OK. In the message that appears, click Close.

    In the Edit Tag dialog box, you can change the tag values and remove multiple tags at a time.

Method 2: Add tags on the Secret Details page

  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 a tab based on the type of your secret, select the required instance ID from the Instance ID drop-down list, find the secret to which you want to add tags, and then click Details in the Actions column.

  3. On the secret details page, click the image.png icon next to Tag.

  4. In the Edit Tag dialog box, enter multiple Tag Key and Tag Value and then click OK. In the message that appears, click Close.

    In the Edit Tag dialog box, you can change the tag values and remove multiple tags at a time.

Configure tags for multiple secrets at a time

  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 a tab based on the type of your secret, select the required instance ID from the Instance ID drop-down list, and then select the secrets that you want to manage in the secret list.

    • Add tags: In the lower part of the secret list, click Add Tag. In the Add Tag dialog box, enter multiple Tag Key and Tag Value, and then click OK. In the message that appears, click Close.

    • Remove tags: In the lower part of the secret list, click Remove Tag. In the Batch Remove dialog box, select the tags that you want to remove and click Remove. In the message that appears, click Close.

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?