Secrets Manager JDBC is a Java library that integrates your database applications with Secrets Manager, automatically retrieving and rotating ApsaraDB RDS credentials at runtime. No hard-coded passwords are required.
Limitations
Only dynamic ApsaraDB RDS secrets are supported. Use Manage Dual Account mode when creating the secret.
Java 1.8 or later is required.
Supported database engines: MySQL, SQL Server, PostgreSQL, and MariaDB TX.
Prerequisites
Before you begin, make sure you have:
A dynamic ApsaraDB RDS secret in Secrets Manager. See Create a dynamic ApsaraDB RDS secret.
Java 1.8 or later installed.
Maven configured in your project.
Install Secrets Manager JDBC
Add the following dependency to your pom.xml:
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-secretsmanager-jdbc</artifactId>
<version>x.x.x</version>
</dependency>For the latest version, see aliyun-secretsmanager-jdbc releases.
Configure an access method
Secrets Manager JDBC reads secretsmanager.properties at startup to determine how to authenticate with Secrets Manager. Four access methods are supported.
Client key (recommended)
Use a client key bound to an application access point. This method is supported in Secrets Manager JDBC 1.0.7 and later.
To create a client key, see Bind a client key to the application access point.
# Access method
credentials_type=client_key
# Decryption password for the client key — read from an environment variable or a file
client_key_password_from_env_variable=<your-client-key-password-env-var>
client_key_password_from_file_path=<your-client-key-password-file-path>
# Path to the client key private key file
client_key_private_key_path=<your-client-key-private-key-path>
# KMS region
cache_client_region_id=[{"regionId":"<region-id>"}]AccessKey pair
To get your AccessKey pair, see Obtain an AccessKey pair.
# Access method
credentials_type=ak
# AccessKey ID and secret
credentials_access_key_id=<your-access-key-id>
credentials_access_secret=<your-access-key-secret>
# KMS region
cache_client_region_id=[{"regionId":"<region-id>"}]
# Cache refresh interval in milliseconds (default: 21600000 = 6 hours; minimum: 300000 = 5 minutes)
refresh_secret_ttl=21600000Security Token Service (STS)
To get your AccessKey pair, see Obtain an AccessKey pair.
# Access method
credentials_type=sts
# AccessKey ID and secret of the RAM user
credentials_access_key_id=<your-access-key-id>
credentials_access_secret=<your-access-key-secret>
# STS session name
credentials_role_session_name=<your-session-name>
# Alibaba Cloud Resource Name (ARN) of the RAM role
credentials_role_arn=<your-role-arn>
# Permission policy for retrieving the secret
credentials_policy=<your-policy>
# KMS region
cache_client_region_id=[{"regionId":"<region-id>"}]
# Cache refresh interval in milliseconds (default: 21600000 = 6 hours; minimum: 300000 = 5 minutes)
refresh_secret_ttl=21600000RAM role of an ECS instance
To create a RAM role and attach it to an Elastic Compute Service (ECS) instance, see Access KMS from an ECS instance in a secure manner.
# Access method
credentials_type=ecs_ram_role
# Name of the RAM role attached to the ECS instance
credentials_role_name=<your-ram-role-name>
# KMS region
cache_client_region_id=[{"regionId":"<region-id>"}]
# Cache refresh interval in milliseconds (default: 21600000 = 6 hours; minimum: 300000 = 5 minutes)
refresh_secret_ttl=21600000Connect to a database
Secrets Manager JDBC provides a driver wrapper for each supported database engine. Pass your secret name as the username and leave the password blank — the driver fetches credentials from Secrets Manager automatically.
Secrets Manager JDBC supports connections via JDBC directly, as well as through connection pools including c3p0 and Database Connection Pools (DBCP).
For the driver class name and Java Database Connectivity (JDBC) URL format for each supported database engine (MySQL, SQL Server, PostgreSQL, MariaDB TX), see the aliyun-secretsmanager-jdbc repository.
The MySQL driver class is com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver with JDBC URL format secrets-manager:mysql://<host>:<port>/<database>.
The following examples use MySQL.
JDBC direct connection
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class SecretManagerJDBCSample {
public static void main(String[] args) throws Exception {
Class.forName("com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver");
Connection connect = null;
try {
// Username is your secret name; leave the password blank
connect = DriverManager.getConnection(
"secrets-manager:mysql://<your-mysql-host>:<your-mysql-port>/<your-database>",
"<your-mysql-secret-name>",
""
);
} catch (SQLException e) {
e.printStackTrace();
}
}
}c3p0 connection pool
If you already use c3p0, only three properties need to change: the jdbcUrl prefix (add secrets-manager:), the user (replace with your secret name), and the driverClass.
c3p0.properties:
c3p0.user=<your-mysql-secret-name>
c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
c3p0.jdbcUrl=secrets-manager:mysql://<your-mysql-host>:<your-mysql-port>/<your-database>Spring with c3p0
Spring XML configuration:
<bean id="dataSource" class="com.mchange.v2.c3p0.ComboPooledDataSource">
<property name="driverClass" value="com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver" />
<property name="user" value="<your-mysql-secret-name>" />
<property name="jdbcUrl" value="secrets-manager:mysql://<your-mysql-host>:<your-mysql-port>/<your-database>" />
<property name="maxPoolSize" value="500" />
<property name="minPoolSize" value="5" />
<property name="initialPoolSize" value="20" />
</bean>
<bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate">
<property name="dataSource" ref="dataSource" />
</bean>