在应用中集成凭据客户端使用凭据 - 密钥管理服务

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

SDK介绍

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

说明

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

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

支持开发者在应用中快速集成凭据能力，一行代码读取凭据信息。
封装凭据在应用中缓存和刷新的功能。
封装API错误的重试机制，智能处理服务端错误。
开放插件式设计模式，支持开发者自定义扩展缓存、错误重试等功能模块。

注意事项

支持的凭据类型：通用凭据、RAM凭据、ECS凭据、RDS凭据。
支持的开发语言：Java（Java 8及以上版本）、Python、Go。
支持的访问凭证：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角色。具体操作，请参见通过实例RAM角色控制资源访问。

STS

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

ClientKey

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

步骤二：安装客户端

Java

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

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

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>alibabacloud-secretsmanager-client</artifactId>
    <version>x.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拥有所有API的访问权限，建议您使用RAM用户进行API访问或日常运维。强烈建议不要把AccessKey ID和AccessKey Secret保存到工程代码里，否则可能导致AccessKey泄露，威胁您账号下所有资源的安全。

本示例以将AccessKey配置在环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET的方式来实现身份验证为例。更多认证信息配置方式，请参见Credentials 设置。

请将示例代码中的#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

方式一：通过系统环境变量构建客户端

系统环境变量的详细信息，请参见附录一：系统环境变量。请将示例代码中的#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配置在环境变量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拥有所有API的访问权限，建议您使用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)
	}
}
```

附录一：系统环境变量

不同的认证方式，需要设置的系统环境变量不同，具体请参见下表。

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。

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。

ECS实例RAM角色

参数	参数值
credentials_type	固定取值ecs_ram_role。
credentials_role_session_name	RAM角色名称。
cache_client_region_id	格式为[{"regionId":"<your region id>"}]，请将`<your region id>`替换为您真实的地域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。

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。

访问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>"}]

方式二：通过环境变量获取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
# AK
credentials_access_key_id=#access key id#
# SK
credentials_access_secret=#access key secret#
# 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]

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_info。cache_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>"}]

方式二：通过环境变量获取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证书。