您在KMS托管RAM用户的AccessKey后,可以安装RAM凭据插件,在使用阿里云SDK时通过引用RAM凭据的名称,获取AccessKey完成API鉴权,无需关注AccessKey的具体信息或者是否被轮转。本文介绍RAM凭据插件的工作原理、安装和使用。
工作原理
RAM凭据插件根据凭据名称,从KMS获取RAM凭据值并缓存在应用程序的内存中。应用程序使用阿里云SDK时,通过RAM凭据插件本地缓存的AccessKey向云产品发起请求。
当由于凭据轮转等原因导致RAM凭据插件本地缓存的AccessKey失效时,RAM凭据插件将立即向KMS重新获取凭据并刷新本地缓存,并根据您设置的错误重试行为,通过最新获取的RAM凭据重试云产品调用请求。RAM凭据插件默认依据云产品调用响应错误码InvalidAccessKeyId
和InvalidAccessKeyId.NotFound
来判断AccessKey无效。
支持的阿里云SDK
KMS为下表中的阿里云SDK提供了RAM凭据插件。
Java SDK(仅支持Java 8及以上版本)
阿里云SDK名称 | RAM凭据插件模块名称 | 说明 |
无。 | ||
无。 |
Python SDK
阿里云SDK名称 | RAM凭据插件模块名称 | 说明 |
无。 |
Go SDK
阿里云SDK名称 | RAM凭据插件模块名称 | 说明 |
无。 |
步骤一:创建访问凭证
场景一:通过共享网关获取凭据值
网络类型为公网或VPC网络。访问凭证支持ECS实例RAM角色、ClientKey(不推荐)。
ECS实例RAM角色
ECS RAM角色是指为ECS实例授予的RAM角色,该RAM角色是一个受信服务为云服务器的普通服务角色。使用实例RAM角色可以实现在ECS实例内部无需配置AccessKey即可获取临时访问凭证(STS Token),从而调用KMS的OpenAPI。
具体操作,请参见实例RAM角色。
登录RAM控制台,创建可信实体为阿里云服务的RAM角色。
信任主体类型:选择云服务。
信任主体名称:选择云服务器ECS。
授予RAM角色访问KMS的权限。
方式一:设置基于身份的策略
KMS内置了系统权限策略,可以直接绑定到RAM角色,详细介绍,请参见密钥管理服务系统权限策略参考。您也可以自定义权限策略。
方式二:设置基于资源的策略
KMS支持基于资源的策略,即为单个密钥和凭据设置访问权限,用于控制哪些阿里云账号、RAM用户、RAM角色有权限来管理或使用KMS密钥、凭据。详细介绍,请参见密钥策略、凭据策略。
登录ECS管理控制台,将RAM角色授予ECS实例。
ClientKey(不推荐)
请参考创建应用接入点中的标准创建方式,创建用于访问共享网关的ClientKey。
配置网络规则时,网络类型选择Public或VPC。
配置权限规则作用域时,请选择KMS共享网关。
场景二:通过专属网关获取凭据值(不推荐)
网络类型为KMS私有网络。访问凭证仅支持ClientKey。
ClientKey支持快速创建和标准创建两种方式。关于ClientKey的详细介绍,请参见应用接入点概述、创建应用接入点。
方式一:快速创建
便捷高效适合于快速测试和开发场景,该方式创建的访问凭证可以访问KMS实例的全部资源。
登录密钥管理服务控制台,在顶部菜单栏选择地域后,在左侧导航栏单击 。
在应用接入页签,单击创建应用接入点,在创建应用接入点面板完成各项配置。
配置项
说明
创建模式
选择快速创建。
作用域(KMS实例)
选择应用要访问的KMS实例。
应用接入点名称
自定义应用接入点的名称。
认证方式
默认为ClientKey,不支持修改。
默认权限策略
默认为
key/*
secret/*
,不支持修改。即应用可以访问指定KMS实例中的所有密钥和凭据。单击确定,浏览器会自动下载ClientKey。
ClientKey包含应用身份凭证内容(ClientKeyContent)和凭证口令(ClientKeyPassword)。 应用身份凭证内容(ClientKeyContent)文件名默认为
clientKey_****.json
。凭证口令(ClientKeyPassword)文件名默认为clientKey_****_Password.txt
。
方式二:标准创建
若您希望对资源设置更精细化的访问权限,建议您使用标准创建。具体操作,请参考创建应用接入点。
重要创建应用接入点时如果选择标准创建,需要注意以下两点:
配置网络规则时,网络类型选择Private。
配置权限规则作用域时,请选择对应的KMS实例ID。
步骤二:通过配置文件设置RAM凭据插件运行参数
RAM凭据插件仅支持通过配置文件方式,配置运行参数。您需要在应用程序的运行目录中新增配置文件(managed_credentials_providers.properties),根据不同认证方式在配置文件中新增内容。
如果您的应用程序无法自动读取到managed_credentials_providers.properties文件,请参考代码示例,通过在代码中设置配置文件路径的方式读取。
ECS实例RAM角色
配置文件内容如下。
credentials_type=ecs_ram_role
## ECS RAM Role名称
credentials_role_name=#credentials_role_name#
## 关联的KMS服务地域
cache_client_region_id=[{"regionId":"#regionId#"}]
ClientKey(共享网关)
通过KMS共享网关Endpoint获取凭据值,配置文件内容如下。
## 访问凭据类型。
credentials_type=client_key
## 读取client key的凭证口令:支持从环境变量或者文件读取。
## 凭证口令:在应用接入点AAP中创建Client Key时保存的凭证口令(ClientKeyPassword)。
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文件:在应用接入点AAP中创建Client Key时下载的应用身份凭证内容(ClientKeyContent)。
# 下载后文件名默认为ClientKey_******.json。
client_key_private_key_path=#your client key private key file path#
## 关联的KMS服务地域。
cache_client_region_id=[{"regionId":"#regionId#"}]
ClientKey(专属网关)
通过KMS专属网关Endpoint获取凭据值,配置文件内容如下。
参数配置项为cache_client_dkms_config_info
,cache_client_dkms_config_info
采用JSON数组格式,您可配置多个KMS实例,以支持业务获得更高标准的服务可用性保障和容灾能力。
方式一:通过环境变量获取ClientKey凭证口令
配置文件内容为:
cache_client_dkms_config_info=[{"regionId":"<your dkms regionId >","endpoint":"<your dkms endpoint>","passwordFromEnvVariable":"<YOUR_PASSWORD_ENV_VARIABLE>","clientKeyFile":"<your ClientKey file path>","ignoreSslCerts":false,"caFilePath":"<your CA certificate file path>"}]
该方式您还需要将ClientKey的凭证口令(ClientKeyPassword)的内容配置到环境变量中,变量名称由您自定义,配置完成后将
<YOUR_PASSWORD_ENV_VARIABLE>
替换为变量名称。示例如下:cache_client_dkms_config_info=[{"regionId":"cn-hangzhou","endpoint":"kst-hzz634e67d126u9p9****.cryptoservice.kms.aliyuncs.com","passwordFromEnvVariable":"passwordFromEnvVariable","clientKeyFile":"C:\RamSecretPlugin\src\main\resources\clientKey_KAAP.json","ignoreSslCerts":false,"caFilePath":"C:\RamSecretPlugin\src\main\resources\PrivateKmsCA_kst-hzz634e67d126u9p9****.pem"}]
方式二:通过文件获取ClientKey凭证口令
ClientKey的凭证口令(ClientKeyPassword)下载后文件名默认为
clientKey_****_Password.txt
,您也可以修改文件名称,但需要将cache_client_dkms_config_info取值中<your Client Key file path>
替换为修改后的文件路径。配置文件内容为:
cache_client_dkms_config_info=[{"regionId":"<your dkms regionId >","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":"cn-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"}]
各配置项说明:
配置项 | 配置项含义 | 说明 |
regionId | KMS实例所在地域ID。 | 具体的地域ID,请参见地域和接入地址。 |
endpoint | KMS实例的域名地址,格式为 | 访问实例管理页面,在实例详情页面查看实例VPC地址,即endpoint。 |
clientKeyFile | ClientKey文件(JSON格式)的绝对路径或相对路径。 |
重要 ClientKey文件和凭证口令是一一对应的,仅支持您在创建ClientKey时获取。如果您在创建时未保存,则需要在应用接入点AAP中重新创建ClientKey。更多详细内容,请参见创建应用接入点。 |
passwordFromFilePath或passwordFromEnvVariable |
| |
ignoreSslCerts | 是否忽略KMS实例SSL证书的有效性检查。KMS实例内置SSL证书,使用SSL/TLS协议用于身份验证和加密通信。取值:
| 正式生产环境中,请将该值设置为false。 |
caFilePath | KMS实例CA证书文件的绝对路径或相对路径。 KMS实例CA证书,用于检查KMS实例SSL证书的有效性。例如:检查KMS实例SSL证书是否由对应的CA中心签发、是否在有效期内、以及对应的域名是否为KMS实例的域名地址(endpoint)。 | 访问实例管理页面,在实例详情页面,单击实例CA证书区域的下载。 |
步骤三:在云产品SDK中使用RAM凭据插件
Java
阿里云Java SDK(V1.0)
通过Maven的方式在项目中引入RAM凭据插件。
<dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core</artifactId> <version>[4.3.2,5.0.0)</version> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core-managed-credentials-provider</artifactId> <version>[1.3.1,)</version> </dependency>
说明建议您安装最新版本的插件,更多信息,请参见原始代码。
获得阿里云Java SDK客户端并调用云服务。
以调用ECS DescribeInstanceStatus为例:
运行以下示例代码时,请自行在pom.xml中添加云服务器aliyun-java-sdk-ecs依赖。
import com.aliyuncs.IAcsClient; import com.aliyuncs.ecs.model.v20140526.DescribeInstanceStatusRequest; import com.aliyuncs.ecs.model.v20140526.DescribeInstanceStatusResponse; import com.aliyun.kms.secretsmanager.plugin.sdkcore.ProxyAcsClient; import com.aliyuncs.exceptions.ClientException; import com.aliyuncs.exceptions.ServerException; public class AliyunSdkProviderSample { public static void main(String[]args) { String secretName="******"; /* 如果应用无法设置从classpath和可执行jar包中读取默认配置文件(managed_credentials_providers.properties), 或需自定义配置文件名称时,可调用以下代码设置自定义配置文件,并按以下顺序读取: 1."your-config-name"配置绝对路径+文件名称,即读取绝对路径下的文件 2."your-config-name"仅配置文件名称,默认先读取classpath下的配置文件,再读取可执行jar包中的配置文件 */ //ConfigLoader.setConfigName("your-config-name"); // 1. 获取ACSClient by aliyun-java-sdk-managed-credentials-provider IAcsClient client = null; try { client = new ProxyAcsClient("<the regionId of ECS>", secretName); } catch (ClientException e) { e.printStackTrace(); } // 2. 调用ECS的OpenAPI实现业务功能 DescribeInstanceStatusRequest request = new DescribeInstanceStatusRequest(); DescribeInstanceStatusResponse response; try { response = client.getAcsResponse(request); } catch (ServerException e) { e.printStackTrace(); } catch (ClientException e) { e.printStackTrace(); } // 3. 通过下面方法关闭客户端来释放插件关联的资源 client.shutdown(); } }
在OSS SDK中使用
通过Maven的方式在项目中引入RAM凭据插件。
<dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-core</artifactId> <version>4.5.17</version> </dependency> <dependency> <groupId>com.aliyun.oss</groupId> <artifactId>aliyun-sdk-oss</artifactId> <version>[2.1.0,3.10.2]</version> <exclusions> <exclusion> <groupId>com.aliyun</groupId> <artifactId>aliyun-java-sdk-kms</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>aliyun-sdk-oss-managed-credentials-provider</artifactId> <version>[1.3.1,]</version> </dependency>
说明建议您安装最新版本的插件,更多信息,请参见原始代码。
获得OSS Java SDK客户端并调用云服务。
以调用OSS listBuckets 为例:
import com.aliyun.kms.secretsmanager.plugin.oss.ProxyOSSClientBuilder; import com.aliyun.oss.OSS; import com.aliyun.oss.model.Bucket; import java.util.List; public class OssProviderSample { public static void main(String[] args) throws Exception { String secretName = "******"; String endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; /* 如果应用无法设置从classpath和可执行jar包中读取默认配置文件(managed_credentials_providers.properties), 或需自定义配置文件名称时,可调用以下代码设置自定义配置文件,并按以下顺序读取: 1."your-config-name"配置绝对路径+文件名称,即读取绝对路径下的文件 2."your-config-name"仅配置文件名称,默认先读取classpath下的配置文件,再读取可执行jar包中的配置文件 */ //ConfigLoader.setConfigName("your-config-name"); // 获取Oss Client OSS ossClient = new ProxyOSSClientBuilder().build(endpoint, secretName); // 以下为业务方业务代码:调用阿里云OSS服务实现业务功能 List<Bucket> buckets = ossClient.listBuckets(); for (Bucket bucket : buckets) { if (bucket != null) { // ... } } // 通过下面方法关闭客户端来释放插件关联的资源 ossClient.shutdown(); } }
Python
阿里云Python SDK(V1.0)
执行pip命令以在项目中使用RAM凭据插件。
pip install aliyun-openapi-python-sdk-managed-credentials-provider
说明请确保插件版本为0.1.0及以上版本,更多信息,请参见原始代码。
获得阿里云Python SDK客户端并调用云服务。
from aliyun_sdk_secretsmanager_sdk_core_plugin.proxy_acs_client import ProxyAcsClient region="cn-hangzhou" secretName="******" # 1. 获取ACSClient client = ProxyAcsClient(region_id=region, secret_name=secretName ) # 2. 业务方业务代码:使用client调用阿里云服务,无需代码改动。 ... # 3. 通过下面方法关闭客户端来释放插件关联的资源 client.shutdown()
OSS Python SDK
执行pip命令以在项目中使用RAM凭据插件。
pip install aliyun-oss-python-sdk-managed-credentials-provider
说明请确保插件版本为0.1.0及以上版本,更多信息,请参见原始代码。
获得阿里云OSS Python SDK客户端并调用云服务。
from aliyun_sdk_secretsmanager_oss_plugin.proxy_bucket import ProxyBucket from itertools import islice endpoint = "******" secret_name ="******" bucket_name = "******" bucket = ProxyBucket(secret_name=secret_name, endpoint=endpoint, bucket_name=bucket_name) objects = bucket.list_objects() for b in islice(objects.object_list, 10): print(b.key) bucket.shutdown()
Go
阿里云Go SDK(V1.0)
安装阿里云Go SDK的RAM凭据插件。
说明建议您安装最新版本的插件,更多信息,请参见原始代码。
方式一:使用
go.mod
管理您的依赖。在
go.mod
文件中添加以下内容安装依赖包。require ( github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider vX.X.X )
方式二:使用
go get
命令获取远程代码包。go get -u github.com/aliyun/aliyun-sdk-mxanaged-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider
获得阿里云Go SDK的客户端并调用云服务。
以调用ECS DescribeInstances 为例:
package sample import ( "fmt" "github.com/aliyun/alibaba-cloud-sdk-go/services/ecs" sdkcoreprovider "github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/alibaba-cloud-sdk-go-managed-credentials-provider/sdk" ) func main() { secretName := "********" regionId := "cn-hangzhou" client, err := sdkcoreprovider.GetClient(&ecs.Client{}, regionId, secretName) if err != nil { fmt.Println(err) return } ecsClient := client.(*ecs.Client) request := ecs.CreateDescribeInstancesRequest() instancesResponse, err := ecsClient.DescribeInstances(request) if err != nil { fmt.Println(err) return } for _, instance := range instancesResponse.Instances.Instance { // do something with instance } }
OSS Go SDK
安装OSS Go SDK的RAM凭据插件。
说明建议您安装最新版本的插件,更多信息,请参见原始代码。
方式一:使用
go.mod
管理您的依赖。在
go.mod
文件中添加以下内容安装依赖包。require ( github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/aliyun-oss-go-sdk-managed-credentials-provider vX.X.X )
方式二:使用
go get
命令获取远程代码包。go get -u github.com/aliyun/aliyun-sdk-managed-credentials-providers-go/aliyun-sdk-managed-credentials-providers/aliyun-oss-go-sdk-managed-credentials-provider
获得阿里云OSS Go SDK客户端并调用云服务。
package sample import ( "fmt" ossprovider "aliyun-oss-go-sdk-managed-credentials-provider/sdk" ) func main() { secretName := "********" endpoint := "https://oss-cn-hangzhou.aliyuncs.com" // 获取Proxy Oss Client client, err := ossprovider.New(endpoint, secretName) if err != nil { fmt.Println(err) return } result, err := client.ListBuckets() if err != nil { fmt.Println(err) return } for _, bucket := range result.Buckets { //业务代码 } // 关闭客户端来释放插件关联的资源 client.Shutdown() }