全部产品
Search
文档中心

密钥管理服务:RAM凭据插件

更新时间:Jun 21, 2024

您在KMS托管RAM用户的AccessKey后,可以安装RAM凭据插件,在使用阿里云SDK时通过引用RAM凭据的名称,获取AccessKey完成API鉴权,无需关注AccessKey的具体信息或者是否被轮转。本文介绍RAM凭据插件的工作原理、安装和使用。

工作原理

RAM凭据插件根据凭据名称,从KMS获取RAM凭据值并缓存在应用程序的内存中。应用程序使用阿里云SDK时,通过RAM凭据插件本地缓存的AccessKey向云产品发起请求。

当由于凭据轮转等原因导致RAM凭据插件本地缓存的AccessKey失效时,RAM凭据插件将立即向KMS重新获取凭据并刷新本地缓存,并根据您设置的错误重试行为,通过最新获取的RAM凭据重试云产品调用请求。RAM凭据插件默认依据云产品调用响应错误码InvalidAccessKeyIdInvalidAccessKeyId.NotFound来判断AccessKey无效。

支持的阿里云SDK

KMS为下表中的阿里云SDK提供了RAM凭据插件。

重要

RAM凭据插件需要针对各阿里云SDK分别开发,如果下表不能满足您的要求,请使用凭据客户端KMS实例SDK阿里云SDK。关于各SDK的介绍,请参见SDK参考。您也可以联系技术支持人员反馈需求。

Java SDK(仅支持Java 8及以上版本)

阿里云SDK名称

RAM凭据插件模块名称

说明

阿里云Java SDK(V1.0)

aliyun-java-sdk-managed-credentials-provider

仅支持V1.0版本, 不支持V2.0版本。V2.0版本请使用凭据客户端KMS实例SDK阿里云SDK

OSS Java SDK

aliyun-oss-java-sdk-managed-credentials-provider

无。

消息队列商业版 TCP协议Java SDK

ons-client-managed-credentials-provider

无。

Python SDK

阿里云SDK名称

RAM凭据插件模块名称

说明

阿里云 Python SDK(V1.0)

aliyun-openapi-python-sdk-managed-credentials-provider

仅支持V1.0版本, 不支持V2.0版本。V2.0版本请使用凭据客户端KMS实例SDK阿里云SDK

OSS Python SDK

aliyun-oss-python-sdk-managed-credentials-provider

无。

Go SDK

阿里云SDK名称

RAM凭据插件模块名称

说明

阿里云 Go SDK(V1.0)

alibaba-cloud-sdk-go-managed-credentials-provider

仅支持V1.0版本, 不支持V2.0版本。V2.0版本请使用凭据客户端KMS实例SDK阿里云SDK

OSS Go SDK

aliyun-oss-go-sdk-managed-credentials-provider

无。

身份认证方式

使用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>"}]

      配置示例

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

    • 方式二:通过环境变量获取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>"}]

    查看各配置项的详细说明

    配置项

    配置项含义

    说明

    regionId

    KMS实例所在地域ID。

    具体的地域ID,请参见地域和接入地址

    endpoint

    KMS实例的域名地址,格式为{实例ID}.kms.aliyuncs.com

    在控制台实例管理页面,单击目标KMS实例,在实例详情页面查看实例VPC地址,将https://去掉后即为KMS实例的域名地址。

    clientKeyFile

    Client Key文件(JSON格式)的绝对路径或相对路径。

    • Client Key文件:在应用接入点AAP中创建Client Key时下载的应用身份凭证内容(ClientKeyContent),下载后文件名默认为ClientKey_******.json。

    • 凭证口令:在应用接入点AAP中创建Client Key时保存的凭证口令(ClientKeyPassword)

    重要

    Client Key文件和凭证口令是一一对应的,仅支持您在创建Client Key时获取。如果您在创建时未保存,则需要在应用接入点AAP中重新创建Client Key。更多详细内容,请参见创建应用接入点

    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证书。更多详细内容,请参见获取实例CA证书

  • 使用应用接入点(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)

  1. 通过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>
    说明

    建议您安装最新版本的插件,更多信息,请参见原始代码

  2. 获得阿里云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中使用

  1. 通过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>
    说明

    建议您安装最新版本的插件,更多信息,请参见原始代码

  2. 获得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)

  1. 执行pip命令以在项目中使用RAM凭据插件。

    pip install aliyun-openapi-python-sdk-managed-credentials-provider
    说明

    请确保插件版本为0.1.0及以上版本,更多信息,请参见原始代码

  2. 获得阿里云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

  1. 执行pip命令以在项目中使用RAM凭据插件。

    pip install aliyun-oss-python-sdk-managed-credentials-provider
    说明

    请确保插件版本为0.1.0及以上版本,更多信息,请参见原始代码

  2. 获得阿里云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)

  1. 安装阿里云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
  2. 获得阿里云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

  1. 安装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
  2. 获得阿里云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()
    }