Key Management Service：多種阿里雲SDK的託管憑據外掛程式

工作原理

應用程式使用託管憑據外掛程式後，只需要引用託管RAM憑據（RAM使用者的AccessKey）的憑據名稱。外掛程式將根據憑據名稱從憑據管家擷取憑據的值（AccessKey）並緩衝在應用程式的記憶體中。外掛程式也會以指定的間隔（可配置）從憑據管家重新擷取憑據的值並重新整理本地的緩衝。

應用程式使用阿里雲SDK時，將通過外掛程式緩衝的AccessKey對雲產品發起請求。

在某些情況下，緩衝的RAM憑據不再有效，這通常發生在管理員在憑據管家中人工輪轉憑據，以響應安全事件時。使用無效RAM憑據調用阿里雲服務通常會導致應用程式產生異常。如果異常中包含的錯誤碼為InvalidAccessKeyId.NotFound或InvalidAccessKeyId，則託管憑據外掛程式將立即重新整理緩衝的RAM憑據並重試失敗的請求。

如果使用到期AccessKey調用某些雲端服務API返回的錯誤碼和上述所列錯誤碼不同，應用開發人員可以修改預設的錯誤重試行為。更多資訊，請參見樣本二：修改預設到期處理常式。

支援外掛程式的阿里雲SDK

阿里雲提供了多種不同的SDK，針對不同SDK的託管憑據外掛程式需要分別開發。下表列出了可以使用託管憑據外掛程式的阿里雲SDK。

如您有其他雲產品SDK託管憑據外掛程式需求，可以通過工單聯絡技術支援人員。

安裝託管憑據外掛程式

針對阿里雲的各類Java SDK的託管憑據外掛程式，您可以訪問多種阿里雲SDK的託管憑據外掛程式開原始碼倉庫瞭解更多安裝資訊。更多資訊，請參見多種阿里雲SDK的託管憑據外掛程式開原始碼倉庫。

您可以通過Maven的方式在專案中按需引入阿里雲SDK託管憑據Java外掛程式。以下以OSS外掛程式匯入為例，為您介紹需要添加的依賴資訊。

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

樣本一：在阿里雲SDK中使用託管RAM憑據

1. 為雲端服務的SDK配置託管憑據外掛程式。

   您可以通過設定檔（managed_credentials_providers.properties）指定從憑據管家擷取託管憑據的方式，以配置應用存取點的Client Key為例進行介紹。關於如何建立Client Key，請參見為AAP綁定Client Key。

   ## 配置訪問方式。
   credentials_type=client_key
   
   ## 讀取Client Key的解密密碼：支援從環境變數或者檔案讀取。
   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#
   
   ## 配置關聯的KMS地區。
   cache_client_region_id=[{"regionId":"#regionId#"}]

2. 使用託管RAM憑據訪問雲端服務。
   • 方法一：編碼方式（以託管RAM憑據訪問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
                 }
             }
     
             // 通過以下方法關閉用戶端來釋放外掛程式關聯的資源。
              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>

樣本二：修改預設到期處理常式

託管憑據外掛程式預設實現AKExpireHandler的介面調用，用來判斷對雲端服務的調用是否使用了無效的憑據。使用無效憑據時，外掛程式將重新從憑據管家擷取最新的憑據，然後重試SDK對雲端服務的調用過程。

AKExpireHandler的介面定義如下：

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

public interface AKExpireHandler<TException> {

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

您可以重新實現AKExpireHandler的介面調用，判斷雲端服務返回的錯誤碼是否由使用無效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用戶端，並對特定的錯誤碼進行重新擷取憑據。
    IAcsClient client = new ProxyAcsClient(
        region, secretName, new CustomHandler());

    // 業務代碼。
    invoke(client,region);

    // 通過以下方法關閉用戶端來釋放外掛程式關聯的資源。 
    client.shutdown();
  }
}

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

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

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

}