All Products
Search

This Product

    Key Management Service:Manage and use RAM secrets

    Document Center

    Key Management Service:Manage and use RAM secrets

    Last Updated:May 31, 2024

    If your application uses an AccessKey pair of Resource Access Management (RAM) as an access credential, you can store the AccessKey pair in a RAM secret of Key Management Service (KMS). This way, your application can dynamically retrieve the secret from KMS. You can configure a rotation policy for a RAM secret to reduce the risk of AccessKey pair leaks. This topic describes how to manage and use RAM secrets.

    Feature description

    If you use 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.

    Important

    If you manage AccessKey pairs in KMS, we recommend that you do not perform management operations on AccessKey pairs, such as creating or deleting AccessKey pairs in Resource Access Management (RAM). If you do so, service failures may occur.

    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 two methods. The following table describes the methods.

    Rotation method

    Rotation period

    Scenario

    Automatic rotation

    Approximately 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 that ranges 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 a 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 configure an automatic rotation policy or perform immediate rotation.

    • If you share an AccessKey pair or a signature that contains an AccessKey pair, such as a signed object URL generated by OSS, with a third party, the AccessKey pair or signature becomes invalid after you rotate the RAM secret that stores the AccessKey pair.

    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, the Name parameter is set 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, the RAM Role Name parameter is set 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 dialog box, 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 a region. In the left-side navigation pane, choose Resource > 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.

      • If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.

      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 Custom policies, 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 Alibaba Cloud SDK, KMS Instance SDK, the secret client, and the RAM secret plug-in to retrieve secret values. The RAM secret plug-in retrieves a RAM secret from KMS based on a secret name and then caches the secret in the memory of the application for which the plug-in is installed. When the application uses Alibaba Cloud SDK to access a cloud service, the application uses the AccessKey pair that is cached by the RAM secret plug-in to initiate requests.

    If a RAM secret is used in OSS SDK, Alibaba Cloud SDK V1.0, or ONS Java Client, we recommend that you use the RAM secret plug-in. For more information, see RAM secret plug-in. In other cases, we recommend that you use the secret client. For more information, see Secret client. If the preceding SDKs do not support your application programming language, you can use Alibaba Cloud SDK. For more information, see Alibaba Cloud SDK. For more information about SDKs, see SDK references.

    Note

    If you want to perform management operations, such as creating RAM secrets and modifying the tags of RAM secrets, you can use only Alibaba Cloud SDK.

    What to do next

    Rotate a RAM secret

    Important

    When the rotation of a RAM secret is about to be complete, KMS requests RAM to delete the old AccessKey pair.

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > 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.

    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 a region. In the left-side navigation pane, choose Resource > 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.

    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 a region. In the left-side navigation pane, choose Resource > 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

    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

    Solution

    Description

    Method 1: Add tags on the Secrets page

    1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > 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 desired secret, 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 click OK. In the message that appears, click Close.

      In the Edit Tag dialog box, you can modify 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 a region. In the left-side navigation pane, choose Resource > 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 desired secret, 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 click OK. In the message that appears, click Close.

      In the Edit Tag dialog box, you can modify 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 a region. In the left-side navigation pane, choose Resource > 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 desired secrets from 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 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.

    FAQ