托管通用凭据或RDS凭据后，使用JDBC连接MySQL数据库_密钥管理服务(KMS)-阿里云帮助中心

针对使用JDBC方式连接数据库的业务场景，您将数据库账号密码保存在RDS凭据或通用凭据后，应用可以集成凭据JDBC客户端，通过在KMS托管的凭据完成数据库连接身份鉴别。本文介绍如何安装和使用凭据JDBC客户端。

SDK介绍

凭据JDBC客户端是针对使用JDBC方式连接数据库的业务场景，该客户端自动从KMS获取凭据用于数据库连接身份鉴别，更便于您集成。其他获取和使用凭据的业务场景推荐您优先使用凭据客户端，其次是KMS实例SDK和阿里云SDK。详细信息，请参见SDK参考。

说明

如果您需要对凭据进行管控类操作，仅支持使用阿里云SDK。

凭据JDBC客户端具有以下功能特性：

支持Java数据库连接（Java Database Connectivity，简称JDBC），包括在数据库连接池（例如c3p0和DBCP）和数据源中通过JDBC连接数据库。
支持MySQL、SQL Server、PostgreSQL和MariaDB四种数据库类型。
支持用户自定义凭据刷新频率。

注意事项

支持的凭据类型：通用凭据、RDS凭据。
- 如果是RDS凭据，建议您使用双账号托管的RDS凭据。
- 如果是通用凭据，凭据值为JSON格式且内容格式如下。
```
{
    "AccountName":"<您的数据库账号用户名>",
    "AccountPassword":"<您的数据库账号密码>"
}
```
支持的开发语言：Java（Java 8及以上版本）。
支持的访问凭证：AccessKey、RAM角色、ECS RAM角色、STS、ClientKey

步骤一：创建访问凭证

重要

AccessKey、RAM角色、ECS RAM角色、STS仅支持通过KMS服务Endpoint获取凭据值，ClientKey既支持通过KMS服务Endpoint，也支持通过KMS实例Endpoint获取凭据值。关于Endpoint的详细介绍，请参见Endpoint说明。
KMS实例Endpoint支持更高的性能，因此推荐您使用ClientKey通过KMS实例Endpoint获取凭据值。

AccessKey

具体操作，请参见创建AccessKey。

RAM角色

创建RAM角色。具体操作，请参见创建RAM角色。
获取目标RAM角色的RamRoleArn。具体操作，请参见查看RAM角色。
说明
RamRoleArn是RAM角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::$accountID:role/$roleName。$accountID为阿里云账号ID。$roleName为RAM角色名称。

ECS RAM角色

为ECS实例授予RAM角色。具体操作，请参见通过ECS实例RAM角色授权ECS访问其他云资源。

STS

创建RAM用户或RAM角色。具体操作，请参见创建RAM用户、创建RAM角色。
为RAM用户或RAM角色授予AliyunSTSAssumeRoleAccess权限。具体操作，请参见为RAM用户授权、为RAM角色授权。
使用RAM用户或RAM角色调用STS服务的AssumeRole接口获取STS临时访问凭证。具体操作，请参见AssumeRole - 获取扮演角色的临时身份凭证。

ClientKey

您需要先创建应用接入点AAP，然后在AAP中创建ClientKey。具体操作，请参见创建应用接入点。

步骤二：安装客户端

访问aliyun-secretsmanager-jdbc了解更多安装信息和源代码。

通过Maven的方式安装凭据JDBC客户端。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-secretsmanager-jdbc</artifactId>
    <version>x.x.x</version>
</dependency>

说明

建议您安装最新版本的SDK。

步骤三：通过配置文件（secretsmanager.properties）设置客户端运行参数

在项目的运行代码中新增配置文件secretsmanager.properties，不同访问凭证需要配置的参数不同。

AccessKey

## 访问凭据类型
credentials_type=ak
## Access Key Id
credentials_access_key_id=#credentials_access_key_id#
## Access Key Secret
credentials_access_secret=#credentials_access_secret#
## 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]
## 用户自定义的刷新频率, 默认为6小时，最小值为5分钟，单位为毫秒
refresh_secret_ttl=21600000

RAM角色

## 访问凭据类型
credentials_type=ram_role
## Access Key Id
credentials_access_key_id=#credentials_access_key_id#
## Access Key Secret
credentials_access_secret=#credentials_access_secret#
## 访问凭据Session名称
credentials_role_session_name=#credentials_role_session_name#
## RAM Role ARN
credentials_role_arn=#credentials_role_arn#
## 访问凭据Policy
credentials_policy=#credentials_policy#
## 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]
## 用户自定义的刷新频率, 默认为6小时，最小值为5分钟，单位为毫秒
refresh_secret_ttl=21600000

ECS实例RAM角色

## 访问凭据类型
credentials_type=ecs_ram_role
## ECS RAM Role名称
credentials_role_name=#credentials_role_name#
## 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]
## 用户自定义的刷新频率, 默认为6小时，最小值为5分钟，单位为毫秒
refresh_secret_ttl=21600000

STS

## 访问凭据类型
credentials_type=sts
## Access Key Id
credentials_access_key_id=#credentials_access_key_id#
## Access Key Secret
credentials_access_secret=#credentials_access_secret#
## 访问凭据Session名称
credentials_role_session_name=#credentials_role_session_name#
## RAM Role ARN
credentials_role_arn=#credentials_role_arn#
## 访问凭据Policy
credentials_policy=#credentials_policy#
## 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]
## 用户自定义的刷新频率, 默认为6小时，最小值为5分钟，单位为毫秒
refresh_secret_ttl=21600000

ClientKey

访问KMS服务Endpoint

## 访问凭据类型
credentials_type=client_key
## 读取client key的解密密码：支持从环境变量或者文件读取
client_key_password_from_env_variable=#your client key private key password environment variable name#
client_key_password_from_file_path=#your client key private key password file path#
## 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]
## 用户自定义的刷新频率, 默认为6小时，最小值为5分钟，单位为毫秒
## 下面的配置将凭据刷新频率设定为1小时
refresh_secret_ttl=3600000

访问KMS实例Endpoint

方式一：通过文件获取ClientKey凭证口令

您还需要将password配置到文件中，文件名称由您自定义，但需要和passwordFromFilePath的取值相同。

cache_client_dkms_config_info=[{"regionId":"<your dkms region>","endpoint":"<your dkms endpoint>","passwordFromFilePath":"< your password file path >","clientKeyFile":"<your Client Key file path>","ignoreSslCerts":false,"caFilePath":"<your CA certificate file path>"}]

方式二：通过环境变量获取ClientKey凭证口令

您还需要将password配置到系统环境变量中，变量名称由您自定义，但需要和passwordFromEnvVariable的取值相同。

cache_client_dkms_config_info=[{"regionId":"<your dkms region>","endpoint":"<your dkms endpoint>","passwordFromEnvVariable":"<your_password_env_variable>","clientKeyFile":"<your ClientKey file path>","ignoreSslCerts":false,"caFilePath":"<your CA certificate file path>"}]

各配置项说明：

配置项	配置项含义	说明
regionId	KMS实例所在地域ID。	具体的地域ID，请参见地域和接入地址。
endpoint	KMS实例的域名地址，格式为`{实例ID}.kms.aliyuncs.com`。	在控制台实例管理页面，单击目标KMS实例，在实例详情页面查看实例VPC地址，将`https://`去掉后即为KMS实例的域名地址。
clientKeyFile	ClientKey文件（JSON格式）的绝对路径或相对路径。	ClientKey文件：在应用接入点AAP中创建ClientKey时下载的应用身份凭证内容（ClientKeyContent），下载后文件名默认为ClientKey_****.json。凭证口令：在应用接入点AAP中创建ClientKey时下载的凭证口令（ClientKeyPassword）,下载后文件名默认为ClientKey_****_password.txt。重要 ClientKey文件和凭证口令是一一对应的，仅支持您在创建ClientKey时获取。如果您在创建时未保存，则需要在应用接入点AAP中重新创建ClientKey。更多详细内容，请参见创建应用接入点。
passwordFromFilePath或passwordFromEnvVariable	passwordFromFilePath：从文件中获取凭证口令，取值为文件的绝对路径或相对路径。您需要将凭证口令保存到文件中。 passwordFromEnvVariable：从环境变量获取凭证口令，取值为环境变量名称。您需要将凭证口令配置到环境变量中。
ignoreSslCerts	是否忽略KMS实例SSL证书的有效性检查。KMS实例内置SSL证书，使用SSL/TLS协议用于身份验证和加密通信。取值： true：表示忽略，不检查KMS实例SSL证书的有效性。说明取值为true时，无需配置caFilePath。 false：表示验证，检查KMS实例SSL证书的有效性。	正式生产环境中，请将该值设置为false。
caFilePath	KMS实例CA证书文件的绝对路径或相对路径。 KMS实例CA证书，用于检查KMS实例SSL证书的有效性。例如：检查KMS实例SSL证书是否由对应的CA中心签发、是否在有效期内、以及对应的域名是否为KMS实例的域名地址（endpoint）。	在实例管理页面，单击获取实例CA证书区域的下载，下载KMS实例的CA证书。

步骤四：使用凭据JDBC客户端连接数据库

重要

示例中仅介绍必须修改的属性，其他属性请您根据实际业务情况进行填写。

通过JDBC方式连接数据库

MySQL数据库

说明

请将#your-mysql-secret-name#、<your-mysql-ip>、<your-mysql-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class SecretManagerJDBCSample {
    public static void main(String[] args) throws Exception {
        // 加载阿里云凭据JDBC客户端 Load the JDBC Driver com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
        Class.forName("com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver");
        Connection connect = null;
        try {
            connect = DriverManager.getConnection("secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>", "#your-mysql-secret-name#","");
        } catch(SQLException e) {
            e.printStackTrace();
        }
    }
}

SQLServer数据库

说明

请将#your-sqlserver-secret-name#、<your-sqlserver-ip>、<your-sqlserver-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class SecretManagerJDBCSqlServerSample {

    public static void main(String[] args) throws Exception{
        // 加载阿里云凭据JDBC客户端 Load the JDBC Driver com.aliyun.kms.secretsmanager.MssqlSecretsManagerSimpleDriver
        Class.forName("com.aliyun.kms.secretsmanager.MssqlSecretsManagerSimpleDriver");
        Connection connect = null;
        try {
            connect = DriverManager.getConnection("secrets-manager:sqlserver://<your-sqlserver-ip>:<your-sqlserver-port>;databaseName=<your-database-name>", "#your-sqlserver-secret-name#", "");
        }  catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

PostgreSQL数据库

说明

请将#your-postgresql-secret-name#、<your-postgresql-ip>、<your-postgresql-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class SecretManagerJDBCPostgreSQLSample {
    public static void main(String[] args) throws Exception {
        // 加载阿里云凭据JDBC客户端 Load the JDBC Driver com.aliyun.kms.secretsmanager.PostgreSQLSecretManagerSimpleDriver
        Class.forName("com.aliyun.kms.secretsmanager.PostgreSQLSecretManagerSimpleDriver");
        Connection connect = null;
        try {
            connect = DriverManager.getConnection("secrets-manager:postgresql://<your-postgresql-ip>:<your-postgresql-port>/<your-database-name>", "#your-postgresql-secret-name#", "");
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

MariaDB数据库

说明

请将#your-mariadb-secret-name#、<your-mariadb-ip>、<your-mariadb-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class SecretManagerJDBCMarialDBSample {

	public static void main(String[] args) throws Exception{
		// 加载阿里云凭据JDBC客户端 Load the JDBC Driver com.aliyun.kms.secretsmanager.MariaDBSecretManagerSimpleDriver
		Class.forName("com.aliyun.kms.secretsmanager.MariaDBSecretManagerSimpleDriver");
		Connection connect = null;
		try {
			connect = DriverManager.getConnection("secrets-manager:mariadb://<your-mariadb-ip>:<your-mariadb-port>/<your-database-name>", "#your-mariadb-secret-name#", "");
		}  catch (SQLException e) {
			e.printStackTrace();
		}
	}
}

通过数据库连接池连接数据库

请按如下方式设置c3p0配置文件（c3p0.properties）中的c3p0.user、c3p0.driverClass和c3p0.jdbcUrl。c3p0.user为凭据名称，c3p0.driverClass为阿里云凭据JDBC Driver类名称，c3p0.jdbcUrl需要以secrets-manager开头。

MySQL数据库

说明

请将#your-mysql-secret-name#、<your-mysql-ip>、<your-mysql-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

c3p0.user=#your-mysql-secret-name#
c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
c3p0.jdbcUrl=secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>

SQLServer数据库

说明

c3p0.user=#your-sqlserver-secret-name#
c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
c3p0.jdbcUrl=secrets-manager:sqlserver://<your-sqlserver-ip>:<your-sqlserver-port>/<your-database-name>

PostgreSQL数据库

说明

c3p0.user=#your-postgresql-secret-name#
c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
c3p0.jdbcUrl=secrets-manager:postgresql://<your-postgresql-ip>:<your-postgresql-port>/<your-database-name>

MariaDB数据库

说明

请将#your-mariadb-secret-name#、<your-mariadb-ip>、<your-mariadb-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

c3p0.user=#your-mariadb-secret-name#
c3p0.driverClass=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
c3p0.jdbcUrl=secrets-manager:mariadb://<your-mariadb-ip>:<your-mariadb-port>/<your-database-name>

通过数据源（DataSource）连接数据库

以使用c3p0 ComboPooledDataSource、MySQL数据库为例，在Spring配置文件中增加如下配置。

说明

请将#your-mysql-secret-name#、<your-mysql-ip>、<your-mysql-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

<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-ip>:<your-mysql-port>/<your-database-name>" />
      <property name="maxPoolSize" value="***" />
      <property name="minPoolSize" value="***" />
      <property name="initialPoolSize" value="***" />
  </bean>
  <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate" >
      <property name="dataSource" ref="dataSource" />
  </bean>

说明

请您根据实际需求设置maxPoolSize、minPoolSize和initialPoolSize参数值。

通过Druid连接池连接数据库

以MySQL数据库为例，您需要修改配置文件中的如下属性。

说明

请将#your-mysql-secret-name#、<your-mysql-ip>、<your-mysql-port>、<your-database-name>替换为您实际使用的凭据名称、服务器IP地址、端口、数据库名称。

properties配置文件方式

username=#your-mysql-secret-name#
driverClassName=com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver
url=secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>

bean配置文件方式

<bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource" init-method="init" destroy-method="close"> 
     <property name="username" value="${your-mysql-secret-name}" />
     <property name="driverClassName" value="com.aliyun.kms.secretsmanager.MysqlSecretsManagerSimpleDriver" />
     <property name="url" value="secrets-manager:mysql://<your-mysql-ip>:<your-mysql-port>/<your-database-name>" />
</bean>