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.
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 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
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
Log on to the RAM console as a RAM user who has administrative rights.
In the left-side navigation pane, choose .
On the Policies page, click Create Policy.
Click the JSON tab and enter the following script:
{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "ram:ListAccessKeys", "ram:CreateAccessKey", "ram:DeleteAccessKey", "ram:UpdateAccessKey" ], "Resource": "*" } ] }
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.
Click OK.
2. Create a RAM role and attach the custom policy to the role
Log on to the RAM console as a RAM user who has administrative rights.
In the left-side navigation pane, choose .
On the Roles page, click Create Role.
On the Create Role page, select Alibaba Cloud Service in the Select Trusted Entity section and click Next.
Select Normal Service Role for the Role Type parameter.
Configure the RAM Role Name and Note parameters. In this example, set the RAM Role Name parameter to AliyunKMSManagedRAMCrendentialsRole.
Select Key Management Service as the trusted service and click OK.
In the Finish step, click Add Permissions to RAM Role. In the Add Permissions panel, the Principal parameter is automatically configured.
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.
Log on to the RAM console.
In the left-side navigation pane, choose .
On the Users page, click the username of the RAM user that you want to manage.
In the AccessKey section, click Create AccessKey.
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
Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.
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.
ImportantYour 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.
NoteA 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.
ImportantAdministrators 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.
A user can retrieve the secret value. You can select RAM users and RAM roles within the current Alibaba Cloud account.
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
.
NoteAfter 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.
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.
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:
|
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:
|
| 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 |
Priority 4: Alibaba Cloud SDK | An application is developed in Java 6 or later, PHP, Go, Python, .NET (C# only), C++, or Node.js. |
| The KMS endpoint: KMS API is called. For more information, see Endpoints. |
What to do next
Rotate a RAM secret
Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.
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.
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.
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.
Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.
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.
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.
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 |
|
Method 2: Add tags on the Secret Details page |
|
Configure tags for multiple secrets at a time
Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.
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.
Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Secrets.
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.
In the Versions section, click Check Account. After the check is complete, view the check result.