全部产品
Search

搜索本产品

    密钥管理服务：凭据JDBC客户端

    文档中心

    密钥管理服务：凭据JDBC客户端

    更新时间：Mar 21, 2024

    针对使用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角色

    1. 创建RAM角色。具体操作，请参见创建RAM角色。

    2. 获取目标RAM角色的RamRoleArn。具体操作，请参见查看RAM角色。

      说明

      RamRoleArn是RAM角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::$accountID:role/$roleName。$accountID为阿里云账号ID。$roleName为RAM角色名称。

    ECS RAM角色

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

    STS

    1. 创建RAM用户或RAM角色。具体操作，请参见创建RAM用户、创建RAM角色。

    2. 为RAM用户或RAM角色授予AliyunSTSAssumeRoleAccess权限。具体操作，请参见为RAM用户授权、为RAM角色授权。

    3. 使用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数据库

        说明

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

        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数据库

        说明

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

        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参数值。