文档

凭据客户端

更新时间:

凭据客户端是基于KMS OpenAPI和KMS实例API的自定义封装,封装了在应用中缓存和刷新凭据的功能,业务稳定性更高且更易于开发者在业务应用中集成。凭据客户端支持获取所有凭据类型的凭据值。本文介绍如何安装及使用凭据客户端。

SDK介绍

凭据客户端基于KMS实例API,封装了凭据缓存、最佳实践和设计模式,更易于开发者在业务系统中集成。此外KMS还提供了KMS实例SDK和阿里云SDK,也可以用于获取凭据值。详细信息,请参见SDK参考

说明

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

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

  • 支持开发者在应用中快速集成凭据能力,一行代码读取凭据信息。

  • 封装凭据在应用中缓存和刷新的功能。

  • 封装API错误的重试机制,智能处理服务端错误。

  • 开放插件式设计模式,支持开发者自定义扩展缓存、错误重试等功能模块。

注意事项

  • 支持的凭据类型:通用凭据、RAM凭据、ECS凭据、RDS凭据。

  • 支持的开发语言:Java(Java 8及以上版本)、Python、Go。

  • 支持的访问凭证:RAM角色、ECS RAM角色、STS、ClientKey(推荐)、AccessKey(不推荐)。

步骤一:创建访问凭证

    重要
    • 如果使用AccessKey、RAM角色、ECS RAM角色或STS,仅支持通过KMS服务Endpoint获取凭据值;如果使用ClientKey,既支持通过KMS服务Endpoint,也支持通过KMS实例Endpoint获取凭据值。关于Endpoint的详细介绍,请参见Endpoint说明

    • KMS实例Endpoint支持更高的性能,因此推荐您使用ClientKey通过KMS实例Endpoint获取凭据值。

ECS实例RAM角色

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

RAM角色

  1. 创建RAM角色。创建时可信实体需要选择阿里云账号或则渠道供应商,其余操作,请参见创建RAM角色

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

    说明

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

STS

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

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

  3. 使用RAM用户或RAM角色调用STS服务的AssumeRole接口获取STS临时访问凭证。具体操作,请参见AssumeRole - 获取扮演角色的临时身份凭证

ClientKey

您需要先创建应用接入点AAP,然后在AAP中创建ClientKey。根据调用的API类型不同AAP的配置也不同,具体配置如下:

  • 访问KMS服务Endpoint-OpenAPI

    网络规则-网络类型选择PublicVPC,权限规则-作用域选择KMS共享网关

  • 访问KMS实例Endpoint-实例API

    网络规则-网络类型选择Private,作用域选择实例ID

具体操作,请参见创建应用接入点

AccessKey(不推荐)

具体操作,请参见创建AccessKey

步骤二:安装客户端

Java

访问alibabacloud-secretsmanager-client-java了解更多安装信息和源代码。

通过Maven的方式在项目中安装凭据客户端。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-secretsmanager-client</artifactId>
    <version>1.x.x</version>
</dependency>
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>aliyun-java-sdk-core</artifactId>
  <version>4.x.x</version>
</dependency>
说明

建议您使用最新版本。

Python

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

执行pip命令安装凭据客户端。

pip install aliyun-secret-manager-client

Go

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

使用go get命令,在项目中使用凭据客户端。

go get -u github.com/aliyun/aliyun-secretsmanager-client-go

步骤三:构建凭据客户端

Java

  • 方式一:通过系统环境变量或配置文件(secretsmanager.properties)构建客户端

    系统环境变量的详细信息,请参见附录一:系统环境变量。配置文件的详细信息,请参见附录二:配置文件。需要注意配置文件名称固定为secretsmanager.properties

    请将示例代码中的#secretName#替换为您的凭据名称。

    import com.aliyuncs.kms.secretsmanager.client.SecretCacheClient;
    import com.aliyuncs.kms.secretsmanager.client.SecretCacheClientBuilder;
    import com.aliyuncs.kms.secretsmanager.client.exception.CacheSecretException;
    import com.aliyuncs.kms.secretsmanager.client.model.SecretInfo;
    
    public class CacheClientEnvironmentSample {
    
        public static void main(String[] args) {
            try {
                //构建凭据客户端
                SecretCacheClient client = SecretCacheClientBuilder.newClient();
                //使用构建好的客户端获取凭据信息
                SecretInfo secretInfo = client.getSecretInfo("#secretName#");
                System.out.println(secretInfo);
            } catch (CacheSecretException e) {
                e.printStackTrace();
            }
        }
    }
  • 方式二:通过自定义配置文件构建客户端

    配置文件的详细信息,请参见附录二:配置文件。需要注意配置文件名称和文件路径由您自行定义。

    请将示例代码中的#customConfigFileName#替换为您自定义的配置文件名称,#secretName#替换为您的凭据名称。

    import com.aliyuncs.kms.secretsmanager.client.SecretCacheClient;
    import com.aliyuncs.kms.secretsmanager.client.SecretCacheClientBuilder;
    import com.aliyuncs.kms.secretsmanager.client.exception.CacheSecretException;
    import com.aliyuncs.kms.secretsmanager.client.model.SecretInfo;
    import com.aliyuncs.kms.secretsmanager.client.service.BaseSecretManagerClientBuilder;
    
    public class CacheClientCustomConfigFileSample {
    
        public static void main(String[] args) {
            try {
                SecretCacheClient client = SecretCacheClientBuilder.newCacheClientBuilder(
                        BaseSecretManagerClientBuilder.standard().withCustomConfigFile("#customConfigFileName#").build()).build();
                SecretInfo secretInfo = client.getSecretInfo("#secretName#");
                System.out.println(secretInfo);
            } catch (CacheSecretException e) {
                System.out.println("CacheSecretException:" + e.getMessage());
            }
        }
    }
  • 方式三:通过指定参数(accessKey、accessSecret、regionId)构建客户端

    说明

    阿里云账号AccessKey拥有所有OpenAPI的访问权限,建议您使用RAM用户进行API访问或日常运维。强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

    本示例以将AccessKey配置在环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET的方式来实现身份验证为例。

    请将示例代码中的#regionId#替换为实际地域ID,#secretName#替换为您的凭据名称。

    import com.aliyuncs.kms.secretsmanager.client.SecretCacheClient;
    import com.aliyuncs.kms.secretsmanager.client.SecretCacheClientBuilder;
    import com.aliyuncs.kms.secretsmanager.client.exception.CacheSecretException;
    import com.aliyuncs.kms.secretsmanager.client.model.SecretInfo;
    import com.aliyuncs.kms.secretsmanager.client.service.BaseSecretManagerClientBuilder;
    import com.aliyuncs.kms.secretsmanager.client.utils.CredentialsProviderUtils;
    
    public class CacheClientSimpleParametersSample {
    
        public static void main(String[] args) {
            try {
                SecretCacheClient client = SecretCacheClientBuilder.newCacheClientBuilder(
                        BaseSecretManagerClientBuilder.standard().withCredentialsProvider(CredentialsProviderUtils
                                .withAccessKey(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))).withRegion("#regionId#").build()).build();
                SecretInfo secretInfo = client.getSecretInfo("#secretName#");
                System.out.println(secretInfo);
            } catch (CacheSecretException e) {
                e.printStackTrace();
            }
        }
    }

Python

  • 方式一:通过系统环境变量或配置文件(secretsmanager.properties)构建客户端

    系统环境变量的详细信息,请参见附录一:系统环境变量。配置文件的详细信息,请参见附录二:配置文件。需要注意配置文件名称固定为secretsmanager.properties

    请将示例代码中的#secretName#替换为您的凭据名称。

    from alibaba_cloud_secretsmanager_client.secret_manager_cache_client_builder import SecretManagerCacheClientBuilder
    
    if __name__ == '__main__':
        #构建凭据客户端
        secret_cache_client = SecretManagerCacheClientBuilder.new_client()
        #使用构建好的客户端获取凭据信息
        secret_info = secret_cache_client.get_secret_info("#secretName#")
        print(secret_info.__dict__)
  • 方式二:通过指定参数(accessKey、accessSecret、regionId)构建客户端

    说明

    阿里云账号AccessKey拥有所有OpenAPI的访问权限,建议您使用RAM用户进行API访问或日常运维。强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

    本示例以将AccessKey配置在环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET的方式来实现身份验证为例。

    请将示例代码中的#regionId#替换为实际地域ID,#secretName#替换为您的凭据名称。

    import os
    
    from alibaba_cloud_secretsmanager_client.secret_manager_cache_client_builder import SecretManagerCacheClientBuilder
    from alibaba_cloud_secretsmanager_client.service.default_secret_manager_client_builder import DefaultSecretManagerClientBuilder
    
    if __name__ == '__main__':
        secret_cache_client = SecretManagerCacheClientBuilder.new_cache_client_builder(DefaultSecretManagerClientBuilder.standard() \
            .with_access_key(os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")) \
            .with_region("#regionId#").build()) \
        .build();
        secret_info = secret_cache_client.get_secret_info("#secretName#")
        print(secret_info.__dict__)

Go

  • 方式一:通过系统环境变量或配置文件(secretsmanager.properties)构建客户端

    系统环境变量的详细信息,请参见附录一:系统环境变量。配置文件的详细信息,请参见附录二:配置文件。需要注意配置文件名称固定为secretsmanager.properties。

    请将示例代码中的#secretName#替换为您的凭据名称。

    package main
    
    import (
        "fmt"
        "github.com/aliyun/aliyun-secretsmanager-client-go/sdk"
    )
    func main() { 
       //构建凭据客户端
        client, err := sdk.NewClient()
        if err != nil {
            // Handle exceptions
            panic(err)
        }
       //使用构建好的客户端获取凭据信息
        secretInfo, err := client.GetSecretInfo("#secretName#")
        if err != nil {
            // Handle exceptions
            panic(err)
        }
        fmt.Printf("SecretValue:%s\n",secretInfo.SecretValue)
    }
  • 通过指定参数(accessKey、accessSecret、regionId)构建客户端

    说明

    阿里云账号AccessKey拥有所有OpenAPI的访问权限,建议您使用RAM用户进行API访问或日常运维。强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里,否则可能导致AccessKey泄露,威胁您账号下所有资源的安全。

    本示例以将AccessKey配置在环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET的方式来实现身份验证为例。

    请将示例代码中的#regionId#替换为实际地域ID,#secretName#替换为您的凭据名称。

    package main
    
    import (
    	"github.com/aliyun/aliyun-secretsmanager-client-go/sdk/service"
    	"github.com/aliyun/aliyun-secretsmanager-client-go/sdk"
    	"os"
    )
    
    func main() {
    	client, err := sdk.NewSecretCacheClientBuilder(service.NewDefaultSecretManagerClientBuilder().Standard().WithAccessKey(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).WithRegion("#regionId#").Build()).Build()
    	if err != nil {
    		// Handle exceptions
    		panic(err)
    	}
    	secretInfo, err := client.GetSecretInfo("#secretName#")
    	if err != nil {
    		// Handle exceptions
    		panic(err)
    	}
    }

附录一:系统环境变量

不同的认证方式,需要设置的系统环境变量不同,具体请参见下表。不同操作系统的环境变量配置方法不同,具体操作,请参见在Linux、macOS和Windows系统配置环境变量

RAM角色

参数

参数值

credentials_type

固定取值ram_role。

credentials_role_session_name

RAM角色的名称。

credentials_role_arn

RAM角色的资源ARN。

credentials_access_key_id

AccessKey ID。

credentials_access_secret

AccessKey Secret。

cache_client_region_id

格式为[{"regionId":"<your region id>"}],请将<your region id>替换为您真实的地域ID。

重要

Linux系统下,使用export命令设置环境变量时,请添加转义字符,即[{\"regionId\":\"<your region id>\"}]

ECS实例RAM角色

参数

参数值

credentials_type

固定取值ecs_ram_role。

credentials_role_name

RAM角色名称。

cache_client_region_id

格式为[{"regionId":"<your region id>"}],请将<your region id>替换为您真实的地域ID。

重要

Linux系统下,使用export命令设置环境变量时,请添加转义字符,即[{\"regionId\":\"<your region id>\"}]

STS

参数

参数值

credentials_type

固定取值sts。

credentials_role_session_name

RAM角色名称。

credentials_role_arn

RAM角色的资源ARN。

credentials_access_key_id

AccessKey ID。

credentials_access_secret

AccessKey Secret。

cache_client_region_id

格式为[{"regionId":"<your region id>"}],请将<your region id>替换为您真实的地域ID。

重要

Linux系统下,使用export命令设置环境变量时,请添加转义字符,即[{\"regionId\":\"<your region id>\"}]

ClientKey

  • 访问KMS服务Endpoint

    参数

    参数值

    credentials_type

    固定取值client_key。

    client_key_password_from_env_variable

    表示从系统环境变量获取ClientKey的凭证口令(password)。取值为password的系统环境变量名称。

    配置本参数时,您需要将password配置到系统环境变量中,变量名称由您自定义。

    client_key_password_from_file_path

    表示从文件中获取ClientKey的凭证口令(password)。取值为password的文件绝对路径或相对路径。

    配置本参数时,您需要将password配置到文件中,文件名称由您自定义。

    说明

    client_key_password_from_env_variable与client_key_password_from_file_path为二选一。

    client_key_private_key_path

    ClientKey文件的绝对路径或相对路径。

    配置本参数时,您需要将ClientKey文件保存到合适位置,文件名称由您自定义。

    cache_client_region_id

    格式为[{"regionId":"<your region id>"}],请将<your region id>替换为您真实的地域ID。

    重要

    Linux系统下,使用export命令设置环境变量时,请添加转义字符,即[{\"regionId\":\"<your region id>\"}]

  • 访问KMS实例Endpoint

    参数

    参数值

    cache_client_dkms_config_info

    • 方式一:通过文件获取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>"}]

      配置示例

      cache_client_dkms_config_info=[{"regionId":ch-hangzhou","endpoint":"kst-hzz634e67d126u9p9****.cryptoservice.kms.aliyuncs.com","passwordFromFilePath":"C:\RamSecretPlugin\src\main\resources\clientKeyPassword.txt","clientKeyFile":"C:\RamSecretPlugin\src\main\resources\clientKey_KAAP.json","ignoreSslCerts":false,"caFilePath":"C:\RamSecretPlugin\src\main\resources\PrivateKmsCA_kst-hzz634e67d126u9p9****.pem"}]
    • 方式二:通过环境变量获取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>"}]
    说明

    cache_client_dkms_config_info中的各项取值,请参见附录二:配置文件中的配置项说明表格。

AccessKey(不推荐)

参数

参数值

credentials_type

固定取值ak。

credentials_access_key_id

AccessKey ID。

credentials_access_secret

AccessKey Secret。

cache_client_region_id

格式为[{"regionId":"<your region id>"}],请将<your region id>替换为您真实的地域ID。

重要

Linux系统下,使用export命令设置环境变量时,请添加转义字符,即[{\"regionId\":\"<your region id>\"}]

附录二:配置文件

不同的认证方式,需要设置的配置文件不同。

RAM角色

# 访问凭据类型
credentials_type=ram_role
# 角色名称
credentials_role_session_name=#role name#
# 资源短名称
credentials_role_arn=#role arn#
# AK
credentials_access_key_id=#access key id#
# SK
credentials_access_secret=#access key secret#
# 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]

ECS实例RAM角色

# 访问凭据类型
credentials_type=ecs_ram_role
# ECS RAM Role名称
credentials_role_name=#credentials_role_name#
# 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]

STS

# 访问凭据类型
credentials_type=sts
# 角色名称
credentials_role_session_name=#role name#
# 资源短名称
credentials_role_arn=#role arn#
# AK
credentials_access_key_id=#access key id#
# SK
credentials_access_secret=#access key secret#
# 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]

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#
    
    # Client Key私钥文件路径
    client_key_private_key_path=#your client key private key file path#
    
    # 关联的KMS服务地域
    cache_client_region_id=[{"regionId":"#regionId#"}]
  • 访问KMS实例Endpoint

    参数配置项为cache_client_dkms_config_infocache_client_dkms_config_info采用JSON数组格式,您可配置多个KMS实例,以支持业务获得更高标准的服务可用性保障和容灾能力。

    • 方式一:通过文件获取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>"}]

      配置示例

      cache_client_dkms_config_info=[{"regionId":ch-hangzhou","endpoint":"kst-hzz634e67d126u9p9****.cryptoservice.kms.aliyuncs.com","passwordFromFilePath":"C:\RamSecretPlugin\src\main\resources\clientKeyPassword.txt","clientKeyFile":"C:\RamSecretPlugin\src\main\resources\clientKey_KAAP.json","ignoreSslCerts":false,"caFilePath":"C:\RamSecretPlugin\src\main\resources\PrivateKmsCA_kst-hzz634e67d126u9p9****.pem"}]
    • 方式二:通过环境变量获取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证书。

AccessKey(不推荐)

# 访问凭据类型
credentials_type=ak
# AK
credentials_access_key_id=#access key id#
# SK
credentials_access_secret=#access key secret#
# 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]