Use KMS secrets to store RDS passwords and improve RDS password security - Key Management Service

Business applications typically store database account passwords in code or configuration files, which poses a risk of leakage. By delegating RDS account password management to KMS secrets, applications can dynamically retrieve password values through the SDK and support automatic rotation, effectively reducing the risk of secret leakage.

How it works

With RDS secrets, applications do not need to hardcode database credentials in code or configuration files. After an administrator creates an RDS secret in KMS, the application calls the GetSecretValue API operation to retrieve the database account and password information to access the RDS database. Common use cases include:

Cloud application database access: Applications deployed on Alibaba Cloud services such as ECS or ACK require centralized management of database access credentials, avoiding dispersed management across multiple instances.
Regular security compliance requirements: Enterprise security policies mandate regular database password rotation. Automatic rotation through KMS secrets meets compliance audit requirements.
Multi-environment credential management: Production, testing, and development environments require isolated database access credentials. Use secret tags to manage credentials by dimension.

Important

After you store RDS credentials in KMS, do not modify or delete the credentials in ApsaraDB RDS to avoid service disruptions.

Before you begin

Supported databases: ApsaraDB RDS for MySQL, ApsaraDB RDS for MariaDB, ApsaraDB RDS for SQL Server (except for 2017 Cluster Edition), and ApsaraDB RDS for PostgreSQL.
KMS key preparation: A symmetric key must be created in the KMS instance for encryption. The key must reside in the same instance as the secret. For more information, see Manage RAM user permissions.
RAM permissions: If you use a RAM user or RAM role, the Alibaba Cloud account must attach the system policy AliyunKMSSecretAdminAccess to the RAM user or RAM role. For more information, see Grant permissions to a RAM role or Manage RAM user permissions.
Usage limitations: Do not delegate the same RDS database account to multiple RDS secrets. When secrets are rotated, the password changes, causing other secrets for the same account to hold an outdated password and resulting in logon failures.

Create an RDS secret

You can configure automatic periodic rotation when creating a credential to reduce the security risk of credential leaks.

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.

Click the Database Secrets tab, select a Instance ID, and then click Create Secret > Create Single Secret. Configure the parameters and click Confirm.

Note

RDS secrets do not support batch creation.
We recommend that you enable automatic secret rotation on a regular basis to reduce the risk of secret leakage.

Parameter	Description
Database Type	Select ApsaraDB RDS Secrets.
Secret Name	A custom credential name. Must be unique within the current region.
ApsaraDB RDS Instance	Select an RDS instance under your Alibaba Cloud account.
Account Management	Manage Dual Accounts (Recommended): Suitable for programmatic database access. KMS manages two accounts with identical permissions to avoid connection interruption during rotation. Click Create Account to configure the account name, select a database, and specify permissions. Note One-click creation and authorization does not immediately create the new account. The account is created after you review and confirm the credential information. For RDS PostgreSQL, you cannot obtain the database name during creation. You must manually set the DBName. Click Import Existing Accounts to select a username and configure the password. Note We recommend that you set the password to the one used when creating the RDS instance user account. If the imported username and password do not match, you can obtain the correct account and password after the first credential rotation. Manage Single Account: Suitable for privileged accounts or manual O&M account hosting scenarios. The current credential version may be temporarily unavailable immediately after password reset. Click Create Account to configure the account name and select the account type. Supports Standard Account and Privileged Account. When you select Standard Account, you must also select a database and specify permissions. Click the Import Existing Accounts tab to select a username and configure the password.
CMK	Select the symmetric key used to encrypt the credential value. The key and the credential must belong to the same KMS instance. Important The key and the credential must belong to the same KMS instance, and the key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications. If a RAM user or RAM role is used, it must have permissions to perform the GenerateDataKey operation using the encryption master key.
Tags	Add tags to the credential for classification. Each tag consists of a key-value pair. Note Format of a tag key and a tag value: 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 signs (=), colons (:), at signs (@), and spaces. A tag key cannot start with `aliyun` or `acs:`. Each credential supports up to 20 tag key-value pairs.
Automatic Rotation	Select whether to enable automatic rotation. When enabled, KMS periodically updates the credential value to reduce the risk of credential leaks.
Rotation Period	Set this parameter only when automatic rotation is enabled. Valid values: 6 hours to 365 days. Specifies the rotation interval. KMS periodically updates the credential value based on this setting.
Description	An optional description of the credential for identification and management.
Advanced Settings > Policy Settings	Set the access policy for the credential to control which RAM users or roles can read or modify it. You can select the default policy first and modify it later as needed.

After creation, verify that the new secret appears in the database credentials list with the status Normal.
Note
The system automatically creates the service-linked role AliyunServiceRoleForKMSSecretsManagerForRDS and attaches the AliyunServiceRolePolicyForKMSSecretsManagerForRDS policy. KMS uses this role to manage RDS secrets, including rotating RDS account passwords.

Manage RDS secrets

Rotate RDS secret

RDS secret rotation mechanism

KMS supports automatic rotation of passwords for associated ApsaraDB RDS instances. During rotation, KMS resets the password of the corresponding RDS account while keeping the account name unchanged.

Rotation modes: KMS supports single-account managed and dual-account managed modes for RDS secrets.

Comparison item	Single-account managed	Dual-account managed
Scenario	Simple scenarios where applications are tolerant to brief interruptions.	High-availability scenarios that require high business continuity for core applications.
Rotation principle	Generates a new password for the account during rotation.	Maintains two alternating accounts (User A and User B).
Availability	Has a brief unavailability window: during the password switch, the old credential becomes invalid before the new one takes full effect, which may cause temporary connection failures. We recommend that you configure a retry policy for your applications.	Fully available throughout the rotation: during rotation, one account's credentials always remain valid, making the process transparent to your applications.

Dual-account rotation flowchart: When you create a secret, the RDS account password for the first user already exists. During the first rotation, KMS calls the RDS API to create the account password for the second user. During the second rotation, KMS modifies the password of the first user. In subsequent rotations, KMS alternately modifies the passwords of the two users.

Precautions

Confirm application integration: Before rotation, ensure that all business applications are configured to dynamically retrieve credentials from KMS. If applications have hardcoded the old password, rotation will cause connection failures.
Verify resource status: We recommend that you use the feature before rotation to verify that the RDS instance and account associated with the secret exist and are in normal state.
Do not delete resources: During or after the rotation configuration takes effect, do not delete the associated RDS instance or database account. Otherwise, the rotation task will fail.

Procedure

Configuring periodic automatic credential rotation effectively reduces the risk of leakage caused by long-term lack of updates. Additionally, the console supports immediate manual rotation, enabling rapid response to security incidents and timely mitigation of potential threats.

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.
Click the Database Secrets tab, select a Instance ID, find the secret to rotate, and then click Details in the Actions column.
In the Versions section at the bottom of the secret details page, click Configure Rotation.
- Scheduled automatic rotation: Enable this feature and select a rotation period. You can set this parameter to a value from 6 hours to 365 days.
  Note
  When creating a secret, it's possible to enable automatic rotation and set the Rotation Period.
- Rotate now: Manually trigger an immediate rotation.

Verify the secret account

KMS verifies whether the RDS database account protected by the secret belongs to the configured RDS instance. If the verification succeeds, the secret can be rotated normally. Otherwise, delete the secret and create a new RDS secret.

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.
Click the Database Secrets tab, select a Instance ID, find the target secret, and then click Details in the Actions column.
In the Versions section, click Check Account. After the verification is complete, view the result.

Configure the database name (DBName)

After an RDS secret is created, if you need to change the associated RDS database name, specify the correct DBName in the Extended Configurations section. To do this:

Important

For RDS PostgreSQL, you must manually add the DBName field. Otherwise, the RDS secret cannot be used.

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.
On the Customer-managed Secrets tab, select Database Secrets, select the target KMS instance, and then click Details in the Actions column for the target secret.
On the Extended Configurations tab, click Edit in the Actions column for CustomData.
In the Edit Custom Data dialog box, click Add Key-value Pair and configure the following:
Note
If a DBName key-value pair already exists, modify the Value value.
- Key: Enter DBName.
- Value: Enter the database name of the target RDS instance. You can obtain this name by logging on to the RDS console and navigating to the instance details page.

Configure credential tags

You can assign tags to credentials to organize and manage them. Each tag consists of a key-value pair (Key : Value), including a tag key (Key) and a tag value (Value).

Tag usage notes

A tag key or tag value can contain up to 128 characters, including letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), at signs (@), and spaces.
A tag key cannot start with aliyun or acs:. This restriction does not apply to tag values.
Each credential can have up to 20 tags.

Procedures

Tag a single credential

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.
Click the tab for the corresponding credential type, select a Instance ID, and locate the target credential.
Open the tag editor using one of the following methods:
- Method 1: In the credential list, click the icon in the Tags column for the target credential.
- Method 2: Click Actions > Details to go to the credential details page, then click the icon next to Tag.
In the Edit Tag dialog box, enter the Tag Key and Tag Value, and click OK.

Tag multiple credentials in bulk

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.
Click the tab for the corresponding credential type, select a Instance ID, and select the credentials to operate on from the credential list.
- Add tags: At the bottom of the credential list, click Add Tag, enter the Tag Key and Tag Value, and click OK.
- Delete tags: At the bottom of the credential list, click Remove Tag, select the tags to unbind in the Batch Remove dialog box, click Cancel, and then click Close in the confirmation dialog box.

Delete an RDS secret

Warning

Before you delete a secret, make sure that it is no longer in use to avoid service failures.

You can schedule a deletion or immediately delete a secret that you no longer need. Deleting an RDS secret removes only the secret information from KMS and does not affect the corresponding account or its password in RDS.

Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Secrets.
Click the Database Secrets tab, select a Instance ID, 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 deletion method for the secret and click OK.
- Schedule Deletion: Specify a recovery period of 7 to 30 days. The system deletes the secret after the recovery period ends.
- Delete Immediately: The system immediately deletes the secret.
During the recovery period, you can find the secret and click Restore Secret in the Actions column to cancel the deletion.

Integrate RDS secrets into applications

KMS provides various methods to obtain RDS secret values. Select a method based on the following priorities. For detailed integration steps, refer to the dedicated documentation linked for each method.

Priority	Use case	Supported gateway type
Priority 1: Secret JDBC Client	The application is developed in Java 8 or later. The database type is MySQL, SQL Server, PostgreSQL, or MariaDB. Note The Secret JDBC Client encapsulates business logic, best practices, and design patterns. It directly handles identity authentication for database connections and provides database access through standard JDBC interfaces.	Shared gateway / Dedicated gateway
Priority 2: Secret Client	The application is developed in Java (Java 8 or later), Go, or Python.	Shared gateway / Dedicated gateway
Priority 3: Alibaba Cloud SDK	The application is developed in Java (Java 6 or later), PHP, Go, Python, .NET (C# only), C++, or Node.js.	Dedicated gateway (recommended) / Shared gateway
Priority 4: KMS Agent	Suitable for centralized deployment of applications that require large-scale access to KMS. KMS Agent provides services based on standard HTTP APIs, supporting business applications developed in any programming language.	Dedicated gateway (recommended) / Shared gateway
Priority 5: KMS instance SDK (not recommended)	The application is developed in Java (Java 8 or later), PHP, Go, Python, or .NET (C# only).	Dedicated gateway

FAQ

Secret rotation

Rotation fails with "Your secret is being rotated. Try again later."?

Secret type	Possible cause
RAM secret	The RAM secret is being rotated. RAM secret rotation takes time to complete within a rotation window. The rotation window for automatic rotation is approximately 48 hours. The rotation window for manual rotation is the duration you set. If the rotation is not completed within the rotation window, check whether the RAM user still exists in the RAM console.
RDS secret	Normally, RDS secret rotation completes instantly. If the rotation does not complete within 2 minutes, check whether the RDS instance and RDS account are in normal state.
ECS secret	Normally, ECS secret rotation completes instantly. If the rotation does not complete within 2 minutes, check whether the ECS instance and ECS account are in normal state.

Secret status shows as unavailable or API calls return "Rejected.Unavailable"?
The KMS instance has expired. Renew the KMS instance within 15 calendar days of expiration, or the instance will be released. For more information, see Billing.
If you do not plan to use the KMS instance for now but may need the keys or secrets in the instance later, we recommend that you back them up in advance. For more information, see KMS backup management.

Secret configuration

Why does a PostgreSQL RDS secret not work?
RDS PostgreSQL does not auto-fill the DBName field. You must manually add it in the extended configurations during secret creation. For more information, see Manage and use ApsaraDB RDS secrets.
Can the same RDS account be delegated to multiple secrets?
Not recommended. Each secret rotates independently, changing the password. If multiple secrets reference the same account, rotating one causes the others to hold outdated credentials and fail login attempts. Instead, have multiple applications retrieve credentials from the same secret and use RAM policies to control access.

Permissions and management

What is the difference between deleting a secret in KMS and deleting an account in RDS?
Deleting a secret in KMS only removes the encrypted credential information and does not affect the actual RDS account. Deleting an account in RDS invalidates the password stored in the KMS secret and causes rotation to fail.
What is the purpose of secret tags?
Tags enable categorized management and quick retrieval of secrets by environment, project, or other dimensions. Combined with RAM policies, tags can also implement tag-based access control. Plan your tagging strategy when creating secrets.