To enhance the security of ApsaraDB RDS database access, store the ApsaraDB RDS account's username and password in a Key Management Service (KMS) secret. Applications can dynamically retrieve these secrets from KMS using Alibaba Cloud SDK, Secret SDK, KMS Agent or KMS instance SDK. Secret rotation can also be configured to minimize the risk of account exposure. This topic describes how to manage and use ApsaraDB RDS secrets.
How it works
ApsaraDB RDS secrets eliminate the need for static database account configurations in applications. When you create an ApsaraDB RDS secret for a database account in KMS, applications can call the GetSecretValue operation to access the database using the retrieved secret.
After storing the username and password of an ApsaraDB RDS account in KMS, avoid modifying or deleting them in ApsaraDB RDS to prevent service disruptions.
ApsaraDB RDS secret rotation method
KMS changes the password of the ApsaraDB RDS account when rotating its secret, while the username remains the same. Secret rotation is typically instant. If it takes longer than 2 minutes, verify that the associated ApsaraDB RDS instance and account are functioning properly.
To avoid rotation failures, do not delete the ApsaraDB RDS instance or account associated with the secret during rotation.
KMS supports both single-account and dual-account hosting for ApsaraDB RDS secrets, each with distinct rotation policies:
Single-account
Password rotation creates a new password for the account. During this process, the current version of the secret might be temporarily inaccessible when the password is being switched. So we recommend that you set up a retry policy.
Multi-account
When creating the secret, if you have the username and password of an ApsaraDB RDS account, KMS creates a second account during the first rotation. During subsequent rotations, KMS alternates password changes between the two accounts. The following figure illustrates the process:
Limits
Supported ApsaraDB RDS databases include ApsaraDB RDS for MySQL, ApsaraDB RDS for MariaDB, ApsaraDB RDS for SQL Server (except SQL Server 2017 Cluster Edition), and ApsaraDB RDS for PostgreSQL.
Do not store the username and password of an ApsaraDB RDS account in multiple secrets. Rotating one secret updates the password, rendering the secret values in other secrets unusable for logging on to the ApsaraDB RDS database.
Prerequisites
A symmetric key for encrypting secrets is created in a KMS instance.
If managing ApsaraDB RDS secrets with a RAM user or RAM role, ensure the Alibaba Cloud account has granted the system policy AliyunKMSSecretAdminAccess to the RAM user or RAM role. For more information, see Grant permissions to a RAM user or Grant permissions to a RAM role.
Step 1: Create an ApsaraDB RDS secret
When you create a secret, you can configure automatic rotation for the secret. This helps reduce the risk of secret leaks.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select an Instance ID, and then click . After completing the configurations, click Confirm.
NoteYou cannot create multiple ApsaraDB RDS secrets at once.
When creating an ApsaraDB RDS secret, the system automatically creates the service-linked role AliyunServiceRoleForKMSSecretsManagerForRDS and grants it the permission policy AliyunServiceRolePolicyForKMSSecretsManagerForRDS. KMS assumes this role to manage ApsaraDB RDS secrets, such as rotating passwords for ApsaraDB RDS accounts.
You can log on to the RAM console to view the details of service-linked roles and policies. For more information, see View the information about a RAM role and View the basic information about a policy.
Parameter
Description
Database Type
The type of database secret that you want to create. Select ApsaraDB RDS Secrets.
Secret Name
The name of the secret. The secret name is unique within the current region.
ApsaraDB RDS Instance
The existing ApsaraDB RDS instance that you want to manage within your Alibaba Cloud account.
Account Management
Manage Dual Accounts (recommended): This mode is suitable for the scenarios in which the secret is used by applications to access the ApsaraDB RDS instance. In this mode, KMS manages two accounts that have identical permissions. This mode ensures that the connections between applications and the ApsaraDB RDS instance are not interrupted when the secret is rotated.
Click the Create Account tab, specify a username prefix, select a database, and then specify permissions.
NoteKMS does not immediately create accounts. KMS creates accounts after you double-check and confirm the secret information.
Click the Import Existing Accounts tab, select usernames, and then specify passwords for the usernames.
NoteWe recommend that you specify the same passwords as the passwords that you specified for the accounts when you created the ApsaraDB RDS instance. If a username and the specified password do not match, you can retrieve the valid username and password the first time the secret is rotated.
Manage Single Account: This mode is suitable for the scenarios in which a privileged account or a manual O&M account is managed. In this mode, the current version of the secret may be temporarily unavailable when the secret is rotated.
Click the Create Account tab, specify a username prefix, and then select an account type.
You can select Standard Account or Privileged Account for the Account Type parameter. If you select Standard Account, you must select a database and specify the permissions of the account.
Click the Import Existing Accounts tab, select a username, and then specify a password for the username.
CMK
The key that is used to encrypt the current value of 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.
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.
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 (:), at signs (@), and spaces.
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.
Rotation Period
The interval of automatic secret rotation. This setting is required only when you enable automatic rotation. The value ranges from 6 hours to 365 days.
KMS periodically updates the secret based on the value of this parameter.
Description
The description of the secret.
Policy Settings
The policy settings of the secret. For more information, see Overview.
You can use the default policy and then modify the policy based on your business requirements after you create the secret.
Step 2: Integrate an ApsaraDB RDS secret into an application
KMS offers Secret JDBC Client, Secret Client, Alibaba Cloud SDK, KMS Agent, and KMS instance SDK to call the GetSecretValue (OpenAPI) or GetSecretValue (KMS Instance API) (not recommended) operation to retrieve an ApsaraDB RDS secret's value.
To enhance service reliability, we recommend that you implement a robust error retry mechanism in your application.
KMS provides multiple authentication methods. For enhanced security, we recommend prioritizing the use of either an ECS instance RAM role or a standard RAM role.
Endpoints:
Shared gateway endpoint: see Endpoint.
Dedicated gateway endpoint:
{INSTANCE_ID}.cryptoservice.kms.aliyuncs.com.
Method | Applicable scenario | Supported gateways |
Note The Secret JDBC Client encapsulates business logic, best practices, and design patterns. It can directly complete database connection authentication and access the database through the JDBC interface after the database connection is established. |
| |
The application is developed in Java 8 or later, Go, or Python. |
| |
The application supports Java 8 or later (Java 6 or later with Alibaba Cloud SDK V1.0), PHP, Go, Python, .NET (C# only), C++, TypeScript, and Swift. |
| |
|
| |
KMS Instance SDK (not recommended) | The application is developed in Java 8 or later, PHP, Go, Python, or .NET (C# only). | Dedicated gateway |
What to do next
Rotate the ApsaraDB RDS secret
During rotation, KMS requests ApsaraDB RDS to change the associated account's password. Ensure all applications retrieve the ApsaraDB RDS secret from KMS before rotating to avoid application downtime.
If the instance or account in ApsaraDB RDS associated with a secret is deleted, KMS cannot rotate the secret. Conduct an account check before rotation and proceed only after KMS confirms the check is successful.
You can configure automatic rotation for a secret to reduce the risk of secret leaks. If a secret is leaked, you can immediately rotate the secret in the KMS console to eliminate intrusion risks.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select an Instance ID, locate the secret you want to rotate immediately, and click Actions in the Details column.
In the Versions section at the bottom of the secret details page, click Configure Rotation.
Automatic Rotation: If you enable Automatic Rotation, select a rotation period ranging from 6 hours to 365 days.
Rotation Now: Select this option to rotate the secret immediately.
Check the value of a secret
KMS verifies whether an account protected by a secret belongs to the associated ApsaraDB RDS instance. If it does, the secret can be rotated; if not, delete the secret and create a new one.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select an Instance ID, locate the target secret, and click Actions in the Details column.
In the Versions section, click Check Account. After the check is complete, view the result.
Delete an ApsaraDB RDS secret
Ensure the ApsaraDB RDS secret is not in use before deletion to prevent service failures.
You can either instantly delete an ApsaraDB RDS secret or schedule a task for its deletion. When you delete an ApsaraDB RDS secret, it is removed solely from KMS; the associated username and password remain intact in ApsaraDB RDS.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select an Instance ID, locate the secret you want to delete, and click Actions in the Schedule Deletion 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 OK in the Actions column to cancel the deletion.
Configure tags for a secret
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 (:), at signs (@), and spaces.
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 |
|
Method 2: Add tags on the Secret Details page |
|
icon in the Tag column. 
icon next to Tag. Configure tags for multiple secrets at a time
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
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.