工作原理

應(yīng)用程序使用托管憑據(jù)插件后，只需要引用托管RAM憑據(jù)（RAM用戶的AccessKey）的憑據(jù)名稱。插件將根據(jù)憑據(jù)名稱從憑據(jù)管家獲取憑據(jù)的值（AccessKey）并緩存在應(yīng)用程序的內(nèi)存中。插件也會以指定的間隔（可配置）從憑據(jù)管家重新獲取憑據(jù)的值并刷新本地的緩存。

應(yīng)用程序使用阿里云SDK時，將通過插件緩存的AccessKey對云產(chǎn)品發(fā)起請求。

在某些情況下，緩存的RAM憑據(jù)不再有效，這通常發(fā)生在管理員在憑據(jù)管家中人工輪轉(zhuǎn)憑據(jù)，以響應(yīng)安全事件時。使用無效RAM憑據(jù)調(diào)用阿里云服務(wù)通常會導(dǎo)致應(yīng)用程序產(chǎn)生異常。如果異常中包含的錯誤代碼為InvalidAccessKeyId.NotFound或InvalidAccessKeyId，則托管憑據(jù)插件將立即刷新緩存的RAM憑據(jù)并重試失敗的請求。

如果使用過期AccessKey調(diào)用某些云服務(wù)API返回的錯誤代碼和上述所列錯誤碼不同，應(yīng)用開發(fā)人員可以修改默認的錯誤重試行為。更多信息，請參見示例二：修改默認過期處理程序。

支持插件的阿里云SDK

阿里云提供了多種不同的SDK，針對不同SDK的托管憑據(jù)插件需要分別開發(fā)。下表列出了可以使用托管憑據(jù)插件的阿里云SDK。

如您有其他云產(chǎn)品SDK托管憑據(jù)插件需求，可以通過智能在線聯(lián)系技術(shù)支持人員。

安裝托管憑據(jù)插件

針對阿里云的各類Java SDK的托管憑據(jù)插件，您可以訪問多種阿里云SDK的托管憑據(jù)插件開源代碼倉庫了解更多安裝信息。更多信息，請參見多種阿里云SDK的托管憑據(jù)插件開源代碼倉庫。

您可以通過Maven的方式在項目中按需引入阿里云SDK托管憑據(jù)Java插件。以下以O(shè)SS插件導(dǎo)入為例，為您介紹需要添加的依賴信息。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-sdk-oss-managed-credentials-provider</artifactId>
    <version>x.x.x</version>
</dependency>

示例一：在阿里云SDK中使用托管RAM憑據(jù)

1. 為云服務(wù)的SDK配置托管憑據(jù)插件。

   您可以通過配置文件（managed_credentials_providers.properties）指定從憑據(jù)管家獲取托管憑據(jù)的方式，以配置應(yīng)用接入點的Client Key為例進行介紹。關(guān)于如何創(chuàng)建Client Key，請參見為AAP綁定Client Key。

   ## 配置訪問方式。
   credentials_type=client_key
   
   ## 讀取Client Key的解密密碼：支持從環(huán)境變量或者文件讀取。
   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#
   
   ## 配置關(guān)聯(lián)的KMS地域。
   cache_client_region_id=[{"regionId":"#regionId#"}]

2. 使用托管RAM憑據(jù)訪問云服務(wù)。
   • 方法一：編碼方式（以托管RAM憑據(jù)訪問OSS為例）

     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 OssPluginSample {
     
         public static void main(String[] args) throws Exception {
             String secretName = "******";
             String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
     
             // 獲取OSS客戶端。
             OSS ossClient = new ProxyOSSClientBuilder().build(endpoint, secretName);
     
             List<Bucket> buckets = ossClient.listBuckets();
             for (Bucket bucket : buckets) {
                 if (bucket != null) {
                     // do something with bucket
                 }
             }
     
             // 通過以下方法關(guān)閉客戶端來釋放插件關(guān)聯(lián)的資源。
              ossClient.shutdown();
         }
     }

   • 方法二：Spring Bean方式（以快速集成OSS SDK為例）

     <?xml version="1.0" encoding="UTF-8"?>
     <beans xmlns="http://www.springframework.org/schema/beans"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.springframework.org/schema/beans
                   http://www.springframework.org/schema/beans/spring-beans.xsd">
         <bean name="proxyOSSClientBuilder" class="com.aliyun.kms.secretsmanager.plugin.oss.ProxyOSSClientBuilder" scope="singleton" />
     </beans>

示例二：修改默認過期處理程序

托管憑據(jù)插件默認實現(xiàn)AKExpireHandler的接口調(diào)用，用來判斷對云服務(wù)的調(diào)用是否使用了無效的憑據(jù)。使用無效憑據(jù)時，插件將重新從憑據(jù)管家獲取最新的憑據(jù)，然后重試SDK對云服務(wù)的調(diào)用過程。

AKExpireHandler的接口定義如下：

package com.aliyun.kms.secretsmanager.plugin.common;

public interface AKExpireHandler<TException> {

  /**
   * 判斷異常是否由AccessKey過期引起。
   *
   * @param e
   * @return
   */
  boolean judgeAKExpire(TException e);
}

您可以重新實現(xiàn)AKExpireHandler的接口調(diào)用，判斷云服務(wù)返回的錯誤碼是否由使用無效AccessKey引起，示例如下：

import com.aliyun.kms.secretsmanager.plugin.sdkcore.ProxyAcsClient;
import com.aliyun.kms.secretsmanager.plugin.common.AKExpireHandler;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;

import java.util.HashSet;
import java.util.Set;

public class SdkRetrySample {

  public static void main(String[]args) throws Exception{
    String region="cn-hangzhou";
    String secretName="******";

    // 獲取阿里云SDK客戶端，并對特定的錯誤碼進行重新獲取憑據(jù)。
    IAcsClient client = new ProxyAcsClient(
        region, secretName, new CustomHandler());

    // 業(yè)務(wù)代碼。
    invoke(client,region);

    // 通過以下方法關(guān)閉客戶端來釋放插件關(guān)聯(lián)的資源。 
    client.shutdown();
  }
}

class CustomHandler implements AKExpireHandler<ClientException> {
  private Set<String> errorCodeSet;

  public CustomerHandler() {
      errorCodeSet = new HashSet<String>();
      // 自行添加錯誤碼，觸發(fā)客戶端重新從憑據(jù)管家獲取托管的RAM憑據(jù)。
      errorCodeSet.add("InvalidAccessKeyId.NotFound");
      errorCodeSet.add("InvalidAccessKeyId");
  }

  @Override
  public boolean judgeAKExpire(ClientException e) {
      return errorCodeSet.contains(e.getErrCode());
  }

}