RAM凭据插件

您在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分别开发,如果下表不能满足您的要求,请使用凭据客户端阿里云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版本请使用凭据客户端阿里云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版本请使用凭据客户端阿里云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版本请使用凭据客户端阿里云SDK

OSS Go SDK

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

无。

步骤一:创建访问凭证

场景一:通过共享网关获取凭据值

网络类型为公网或VPC网络。访问凭证支持ECS实例RAM角色、ClientKey(不推荐)。

ECS实例RAM角色

ECS RAM角色是指为ECS实例授予的RAM角色,该RAM角色是一个受信服务为云服务器的普通服务角色。使用实例RAM角色可以实现在ECS实例内部无需配置AccessKey即可获取临时访问凭证(STS Token),从而调用KMSOpenAPI。

具体操作,请参见实例RAM角色

  1. 登录RAM控制台,创建可信实体为阿里云服务的RAM角色。

    • 信任主体类型:选择云服务

    • 信任主体名称:选择云服务器ECS

  2. 授予RAM角色访问KMS的权限。

    • 方式一:设置基于身份的策略

      KMS内置了系统权限策略,可以直接绑定到RAM角色,详细介绍,请参见密钥管理服务系统权限策略参考。您也可以自定义权限策略。image

    • 方式二:设置基于资源的策略

      KMS支持基于资源的策略,即为单个密钥和凭据设置访问权限,用于控制哪些阿里云账号、RAM用户、RAM角色有权限来管理或使用KMS密钥、凭据。详细介绍,请参见密钥策略凭据策略

  3. 登录ECS管理控制台,将RAM角色授予ECS实例。image

ClientKey(不推荐)

请参考创建应用接入点中的标准创建方式,创建用于访问共享网关的ClientKey。

重要
  • 配置网络规则时,网络类型选择PublicVPC

  • 配置权限规则作用域时,请选择KMS共享网关

场景二:通过专属网关获取凭据值(不推荐)

网络类型为KMS私有网络。访问凭证仅支持ClientKey。

ClientKey支持快速创建和标准创建两种方式。关于ClientKey的详细介绍,请参见应用接入点概述创建应用接入点

  • 方式一:快速创建

    便捷高效适合于快速测试和开发场景,该方式创建的访问凭证可以访问KMS实例的全部资源。

    1. 登录密钥管理服务控制台,在顶部菜单栏选择地域后,在左侧导航栏单击应用接入 > 接入点

    2. 应用接入页签,单击创建应用接入点,在创建应用接入点面板完成各项配置。

      配置项

      说明

      创建模式

      选择快速创建

      作用域(KMS实例)

      选择应用要访问的KMS实例。

      应用接入点名称

      自定义应用接入点的名称。

      认证方式

      默认为ClientKey,不支持修改。

      默认权限策略

      默认为key/*secret/*,不支持修改。即应用可以访问指定KMS实例中的所有密钥和凭据。

    3. 单击确定,浏览器会自动下载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_infocache_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实例的域名地址,格式为{实例ID}.kms.aliyuncs.com

访问实例管理页面,在实例详情页面查看实例VPC地址,即endpoint。

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证书区域的下载

步骤三:在云产品SDK中使用RAM凭据插件

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. 调用ECSOpenAPI实现业务功能
            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 SDKRAM凭据插件。

    说明

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

    • 方式一:使用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 SDKRAM凭据插件。

    说明

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

    • 方式一:使用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()
    }