您在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凭据插件模块名称 | 说明 |
无。 |
身份认证方式
使用RAM凭据插件时支持如下两种身份认证方式:
应用接入点(AAP)的Client Key:可以通过KMS实例Endpoint获取凭据值,也可以通过KMS服务Endpoint获取凭据值。使用前您需要创建应用接入点(AAP)以及ClientKey。具体操作,请参见创建应用接入点。
ECS实例RAM角色:通过KMS服务Endpoint调用OpenAPI。使用前您需要创建ECS实例RAM角色。具体操作,请参见通过ECS实例RAM角色授权ECS访问其他云资源。
为了获得更高QPS、更低时延,推荐您使用应用接入点(AAP)的Client Key,并通过KMS实例Endpoint获取凭据值。
通过配置文件设置RAM凭据插件运行参数
RAM凭据插件仅支持通过配置文件方式,配置运行参数。您需要在应用程序的运行目录中新增配置文件(managed_credentials_providers.properties),根据不同认证方式在配置文件中新增内容。
如果您的应用程序无法自动读取到managed_credentials_providers.properties文件,请参考代码示例,通过在代码中设置配置文件路径的方式读取。
(推荐)使用应用接入点(AAP)的Client Key,通过KMS实例Endpoint获取凭据值。
参数名称为
cache_client_dkms_config_info
,采用JSON数组格式。您可配置多个KMS实例,以支持业务获得更高标准的服务可用性保障和容灾能力。根据Client Key凭证口令获取方式不同,配置文件示例如下。方式一:通过文件获取Client Key凭证口令
cache_client_dkms_config_info=[{"regionId":"<your kms region>","endpoint":"<your kms endpoint>","passwordFromFilePath":"<your client key password file absolute path>","clientKeyFile":"<your client key file absolute path>","ignoreSslCerts":false,"caFilePath":"<your DKMS's CA certificate file absolute path>"}]
方式二:通过环境变量获取Client Key凭证口令
该方式您需要将Client Key文件的凭证口令配置到环境变量中,环境变量名称即您在
passwordFromEnvVariable
中指定的名称。cache_client_dkms_config_info=[{"regionId":"<your kms region>","endpoint":"<your kms endpoint>","passwordFromEnvVariable":"<your_password_env_variable>","clientKeyFile":"<your client key file absolute path>","ignoreSslCerts":false,"caFilePath":"<your DKMS's CA certificate file absolute path>"}]
使用应用接入点(AAP)的Client Key,通过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#"}]
使用ECS实例RAM角色,通过KMS服务Endpoint获取凭据值。
credentials_type=ecs_ram_role ## ECS RAM Role名称 credentials_role_name=#credentials_role_name# ## 关联的KMS服务地域 cache_client_region_id=[{"regionId":"#regionId#"}]
代码示例
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() }