Hardcoding AccessKey pairs in application source code is a common security risk—anyone who can inspect the code or its deployed artifacts can compromise your credentials. RAM secrets let you store and rotate a RAM user's AccessKey pair in Key Management Service (KMS), so your application retrieves valid credentials at runtime instead of embedding them at build time.
This topic walks you through authorizing KMS, creating a RAM secret, integrating it into your application, and managing the secret lifecycle.
How it works
After you store a RAM user's AccessKey pair as a RAM secret, configure your application with the secret name only. At runtime, the application calls GetSecretValue to retrieve the current AccessKey pair. When you rotate the secret, KMS creates a new AccessKey pair in RAM, writes the new credentials as the current secret value, and deletes the old AccessKey pair—your application picks up the new credentials on the next retrieval without any code change.
Limits: Only a RAM user's AccessKey pair can be managed as a RAM secret. The AccessKey pair of an Alibaba Cloud account cannot be managed.
Secret rotation
KMS supports two rotation methods:
| Rotation method | When to use | Rotation period |
|---|---|---|
| Automatic rotation | The RAM secret is integrated into an application that periodically reads it. | Approximately 2 days (recommended: no more than three months) |
| Immediate rotation | Emergency response when a secret is leaked, or to manually trigger rotation when an application retrieves the secret. | 10 minutes to 2 days (recommended: 30 minutes for leaked secrets, 2 days otherwise) |
Do not delete the RAM user associated with a secret while rotation is in progress—doing so causes rotation to fail.
While a secret is being rotated, you cannot configure an automatic rotation policy or trigger immediate rotation.
Prerequisites
Before you begin, ensure that you have:
A symmetric key created in the KMS instance to encrypt secrets. For more information, see Create keys.
(Required if using a RAM user or role) The AliyunKMSSecretAdminAccess and AliyunRAMReadOnlyAccess system policies attached to the RAM user or role used to manage secrets. For more information, see Grant permissions to a RAM user or Grant permissions to a RAM role.
If the Alibaba Cloud account already has the AliyunKMSManageRAMCredentialsRole or AliyunKMSManagedRAMCrendentialsRole service-linked role, skip Step 1. KMS already has permission to manage the RAM user's AccessKey pair.
Step 1: Grant KMS permission to manage RAM user AccessKey pairs
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click the Customer-managed Secrets tab, locate the RAM Secrets type, select the required instance ID from the Instance ID drop-down list, and then click Create Secret.
On the Create RAM Secrets panel, click Authorize KMS to access AccessKey pairs.
On the Cloud Resource Access Authorization page: When authorization is complete, KMS automatically creates the AliyunKMSManageRAMCredentialsRole service-linked role and attaches the AliyunKMSManageRAMCredentialsRolePolicy permission policy to it. KMS uses this role to manage RAM secrets and perform secret rotation. To view the service-linked role and policy details, see View the information about a RAM role and View the information about a policy.
If you are a RAM administrator without the AliyunKMSManageRAMCredentialsRole or AliyunKMSManagedRAMCrendentialsRole role, click Agree to Authorization.
Otherwise, send the Cloud Resource Access Authorization link to a RAM administrator or the Alibaba Cloud account owner to complete the authorization.
Return to the RAM secrets creation page and click the refresh button to proceed.
Step 2: Create a RAM secret
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click the Customer-managed Secrets tab, locate the RAM Secrets type, select the required instance ID from the Instance ID drop-down list, and then click Create Secret.
Configure the parameters and click OK.
| Parameter | Description |
|---|---|
| Select RAM User | The RAM user whose AccessKey pair you want to manage. The RAM user must have at least one AccessKey pair. For more information, see Create an AccessKey pair. The secret name is auto-generated from the RAM user name and is unique within the region. |
| Secret Value | The AccessKey Secret of the RAM user. Maximum size: 30,720 bytes (30 KB). |
| CMK | The customer master key (CMK) used to encrypt the secret value. The key and secret must belong to the same KMS instance, and the key must be a symmetric key. If you are a RAM user or role, you must have permission to call GenerateDataKey using this key. For supported key types, see Key specifications for symmetric and asymmetric encryption. |
| Tag | A key-value pair to classify and manage the secret. Each tag key and value can be up to 128 characters, using letters, digits, /, \, _, -, ., +, =, :, @, and spaces. Tag keys cannot start with aliyun or acs:. Up to 20 key-value pairs per secret. |
| Automatic Rotation | Whether to enable automatic secret rotation. |
| Days (7 Days to 365 Days) | The automatic rotation interval. Required only when automatic rotation is enabled. |
| Description | An optional description of the secret. |
| Advanced Settings > Policy Settings | The resource policy for the secret. For more information, see Overview of secret policies. You can use the default policy and refine it after creation. |
Step 3: Integrate the RAM secret into an application
Use one of the following methods to call GetSecretValue and retrieve the RAM secret at runtime. For enhanced security, authenticate using an ECS instance RAM role or a standard RAM role rather than hardcoded credentials.
Implement a retry mechanism in your application to handle transient errors and improve reliability.
Endpoints:
Shared gateway: see Endpoint.
Dedicated gateway: {INSTANCE_ID}.cryptoservice.kms.aliyuncs.com| Method | Best for | Supported gateways |
|---|---|---|
| RAM secret plugin | Java 8+, Go, or Python applications using a supported SDK version | Shared gateway, dedicated gateway |
| Secret Client | Java 8+, Go, or Python applications | Shared gateway, dedicated gateway |
| Alibaba Cloud SDK | Applications in Java 8+ (Java 6+ with SDK V1.0), PHP, Go, Python, .NET (C# only), C++, TypeScript, or Swift | Dedicated gateway (recommended), shared gateway |
| KMS Agent | Multi-application deployments where many applications access KMS; supports any language via standard HTTP APIs | Dedicated gateway (recommended), shared gateway |
| KMS Instance SDK (not recommended) | Java 8+, PHP, Go, Python, or .NET (C# only) applications | Dedicated gateway only |
Manage the secret lifecycle
Rotate a RAM secret
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click the Customer-managed Secrets tab, locate the RAM Secrets type, select the required instance ID from the Instance ID drop-down list, find the target secret, and then click Details in the Actions column.
Configure the rotation policy:
Automatic rotation: In the upper-right corner, click Configure Rotation, enable or disable Automatic Rotation, and then click OK.
Immediate rotation: In the upper-right corner, click Rotate Now. In the Configure Rotation dialog box, set Rotation Window to a value between 10 minutes and 2 days, and then click OK.
Delete a RAM secret
Deleting a RAM secret removes it from Secrets Manager only. The associated RAM user's AccessKey pair is not deleted from RAM.
Verify that the secret is no longer in use before deleting it. Deleting an active secret may cause service failures.
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click the Customer-managed Secrets tab, locate the RAM Secrets type, select the required instance ID from the Instance ID drop-down list, find the target secret, and then click Schedule Deletion in the Actions column.
In the Schedule Deletion dialog box, select a deletion method and click OK:
Schedule Deletion: Set the retention period (7–30 days). KMS deletes the secret when the period ends. During the retention period, click OK in the Actions column to cancel the deletion.
Delete Immediately: KMS deletes the secret immediately.
Manage tags
Tags are key-value pairs that help you classify and manage secrets. Each tag key and value can be up to 128 characters. Tag keys cannot start with aliyun or acs:. Each secret supports up to 20 key-value pairs.
Add a tag to a single secret
You can add tags from the Secrets list page or the Secret Details page:
From the Secrets list page:
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click a tab based on your secret type, select the required instance ID from the Instance ID drop-down list, find the target secret, and then click the
icon in the Tag column.Click Add. In the Edit Tag dialog box, enter one or more Tag Key and Tag Value pairs, and then click OK. Click Close to dismiss the confirmation message.
From the Secret Details page:
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click a tab based on your secret type, select the required instance ID from the Instance ID drop-down list, find the target secret, and then click Details in the Actions column.
On the Secret Details page, click the
icon next to Tag.In the Edit Tag dialog box, enter one or more Tag Key and Tag Value pairs, and then click OK. Click Close to dismiss the confirmation message.
Add or remove tags for multiple secrets at once
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click a tab based on your secret type, select the required instance ID from the Instance ID drop-down list, and then select the target secrets from the list.
At the bottom of the list:
Add tags: Click Add Tag. In the Add Tag dialog box, enter one or more Tag Key and Tag Value pairs, and then click OK. Click Close to dismiss the confirmation message.
Remove tags: Click Remove Tag. In the Batch Remove dialog box, select the tags to remove, and then click Cancel. Click Close to dismiss the confirmation message.
Check accounts
The account check feature verifies that the RAM user associated with a RAM secret still exists and that the AccessKey ID stored in the secret matches the current AccessKey ID of the RAM user.
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.
Click the Customer-managed Secrets tab, locate the RAM Secrets type, select the required instance ID from the Instance ID drop-down list, find the target secret, and then click Details in the Actions column.
In the Versions section, click Check Account and review the result.