文档

凭据JDBC客户端

更新时间:

针对使用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角色。具体操作,请参见配置ECS实例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。更多详细内容,请参见创建应用接入点

    passwordFromFilePathpasswordFromEnvVariable

    • 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.userc3p0.driverClassc3p0.jdbcUrlc3p0.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参数值。

  • 本页导读 (1)
文档反馈