通過配置Credentials實現OpenAPI安全調用（JAVA SDK） - Alibaba Cloud SDK

當您通過阿里雲SDK調用OpenAPI進行資源操作時，必須正確配置憑證資訊。阿里雲的Credentials工具提供了一套強大的功能，使您能夠輕鬆地擷取和管理這些訪問憑證。無論是利用預設憑證，AccessKey（AK），還是Security Token Service（STS）令牌等，Credentials工具都能為您提供相應支援。此外，本文檔將詳細闡述如何根據優先順序使用預設憑證。您將深入理解如何在阿里雲SDK中配置和維護憑證，從而確保您對雲資源的操作既有效率又具有高度安全性。

背景資訊

憑據是指使用者證明其身份的一組資訊。使用者在系統中進行登入時，需要提供正確的憑據才能驗證身份。常見的憑據類型有：

阿里雲主帳號和RAM使用者的永久憑據 AccessKey（簡稱AK）是由AccessKey ID和AccessKey Secret組成的金鑰組。
阿里雲RAM角色的STS臨時訪問Token，簡稱STS Token。它是可以自訂時效和存取權限的臨時身份憑據，詳情請參見什麼是STS。
Bearer Token。它是一種身分識別驗證和授權的令牌類型。

前提條件

使用Credentials工具最低要求是Java 8(JDK 1.8)。
使用V2.0代系的阿里雲SDK，請參見通過IDE使用阿里雲Java SDK。

安裝Credentials工具

Maven安裝方式。

<dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>credentials-java</artifactId>
   <version>LATEST</version>
</dependency>

使用最新發行Credentials依賴包，確保所有憑證支援。
請查看ChangeLog.txt擷取所有發行的版本列表。
建議優先選用阿里雲V2.0 SDK。如果選擇不使用阿里雲V2.0 SDK，而是單獨依賴credentials-java，則務必引入下面的依賴，否則將出現錯誤，無法找到com.aliyun.tea.TeaModel類檔案。
```
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>tea</artifactId>
  <version>LATEST</version>
</dependency>
```

初始化憑據用戶端

Credentials工具支援多種方式初始化憑據用戶端，您可根據實際情況選擇合適的方式進行憑據用戶端初始化。

重要

在專案中使用明文AccessKey，容易因代碼倉庫許可權管理不當造成AccessKey泄露，會威脅該帳號下所有資源的安全。建議通過環境變數、設定檔等方式擷取AccessKey。

方式一：使用預設憑據鏈

當您在初始化憑據用戶端不傳入任何參數時，Credentials工具會使用預設憑據鏈方式初始化用戶端。預設憑據的讀取邏輯請參見預設憑據鏈。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception{
        // 不指定參數
        Config credentialConfig = new Config();
        Client credentialClient = new Client(credentialConfig);
    }
}

介面調用方法

通過預設憑據提供鏈自動建立訪問憑證，並在不使用寫入程式碼AccessKey的情況下成功調用雲產品OpenAPI介面。

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用預設憑證初始化Credentials Client。
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();

        Config ecsConfig = new Config();
        // 配置雲產品服務接入地址（endpoint）。
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // 使用 Credentials 配置憑證。
        ecsConfig.setCredential(credentialClient);
        // 初始化 ECS Client。
        Client ecsClient = new Client(ecsConfig);
        // 初始化 DescribeRegions 請求。
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用 DescribeRegions 介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

方式二：使用AK

阿里雲帳號、RAM使用者可產生調用OpenAPI的金鑰組AK。如何擷取AK請參見文檔建立AccessKey。您可使用AK初始化憑據用戶端。

警告

阿里雲主帳號擁有資源的全部許可權，AK一旦泄露，會給系統帶來巨大風險，不建議使用。

推薦使用最小化授權的RAM使用者的AK。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception{
        Config credentialConfig = new Config();
        credentialConfig.setType("access_key");
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient = new Client(credentialConfig);
    }
}

介面調用方法

通過Credentials工具讀取AK，完成雲產品OpenAPI介面的調用。

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用AK 初始化Credentials Client。
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // 憑證類型。
        credentialsConfig.setType("access_key");
        // 設定為AccessKey ID值。
        credentialsConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // 設定為AccessKey Secret值。
        credentialsConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // 配置雲產品服務接入地址（endpoint）。
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // 使用Credentials配置憑證。
        ecsConfig.setCredential(credentialClient);
        // 初始化ECS Client。
        Client ecsClient = new Client(ecsConfig);
        // 初始化DescribeRegions請求。
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

方式三：使用STS Token

以一個RAM使用者的身份調用STS服務的AssumeRole介面，設定Token的最大到期時間，即可換取到臨時憑據STS Token。以下樣本示範如何使用STS Token初始化憑據用戶端（不包含如何擷取到STS Token的過程）。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) {
        Config credentialConfig = new Config();
        credentialConfig.setType("sts");
        // 從環境變數中擷取AccessKey ID的值
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // 從環境變數中擷取AccessKeySecret的值
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // 從環境變數中擷取臨時SecurityToken的值
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient = new Client(credentialConfig);
    }
}

介面調用方法

通過Credentials工具讀取臨時安全性權杖（STS Token），完成雲產品OpenAPI介面的調用。

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝Elastic Compute Service SDK和Security Token Service SDK。

import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.sts20150401.Client;
import com.aliyun.sts20150401.models.AssumeRoleRequest;
import com.aliyun.sts20150401.models.AssumeRoleResponse;
import com.aliyun.sts20150401.models.AssumeRoleResponseBody;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 建立StsClient對象，並調用assumeRole服務擷取STS Token
        Config config = new Config()
                // 從環境變數中擷取AccessKey ID的值
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 從環境變數中擷取AccessKey Secret的值
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")); 
        config.endpoint = "sts.cn-hangzhou.aliyuncs.com";
        Client client = new Client(config);
        AssumeRoleRequest assumeRoleRequest = new AssumeRoleRequest()
                // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
                .setRoleArn("<RoleArn>")
                // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
                .setRoleSessionName("<RoleSessionName>"); 
        RuntimeOptions runtime = new RuntimeOptions();
        AssumeRoleResponse assumeRoleResponse = client.assumeRoleWithOptions(assumeRoleRequest, runtime);
        AssumeRoleResponseBody.AssumeRoleResponseBodyCredentials assumeRoleResponseBodyCredentials = assumeRoleResponse.body.credentials;

        // 使用STS Token初始化Credentials Client。
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        credentialsConfig.setType("sts"); // 憑證類型。
        credentialsConfig.setAccessKeyId(assumeRoleResponseBodyCredentials.accessKeyId);
        credentialsConfig.setAccessKeySecret(assumeRoleResponseBodyCredentials.accessKeySecret);
        credentialsConfig.setSecurityToken(assumeRoleResponseBodyCredentials.securityToken);
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        // 使用Credentials建立ecs client。
        Config ecsConfig = new Config();
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        ecsConfig.setCredential(credentialClient);
        com.aliyun.ecs20140526.Client ecsClient = new com.aliyun.ecs20140526.Client(ecsConfig);
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        RuntimeOptions describeRegionsRuntime = new RuntimeOptions();

        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, describeRegionsRuntime);
        System.out.println(response.body.toMap());
    }
}

方式四：使用AK及RamRoleArn

該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具可以協助開發人員前往STS換取STS Token。您也可調用setPolicy函數限制RAM角色到一個更小的許可權集合。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
  public static void main(String[] args) throws Exception {
    Config credentialConfig = new Config();
    credentialConfig.setType("ram_role_arn");
    credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
    credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
    // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
    credentialConfig.setRoleArn("<RoleArn>");
    // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
    credentialConfig.setRoleSessionName("<RoleSessionName>");
    // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    credentialConfig.setPolicy("<Policy>");
    // Not required, the external ID of the RAM role
    // This parameter is provided by an external party and is used to prevent the confused deputy problem.
    credentialConfig.setExternalId("<ExternalId>");
    credentialConfig.setRoleSessionExpiration(3600);
    Client credentialClient = new Client(credentialConfig);
  }
}

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用RamRoleArn初始化Credentials Client
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // 憑證類型
        credentialsConfig.setType("ram_role_arn");
        // 從環境變數中擷取AccessKey ID的值
        credentialsConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // 從環境變數中擷取AccessKey Secret的值
        credentialsConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // 要扮演的RAM角色ARN，樣本值：acs:ram::123456789012****:role/adminrole，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
        credentialsConfig.setRoleArn("<RoleArn>");
        // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
        credentialsConfig.setRoleSessionName("<RoleSessionName>");
        // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        credentialsConfig.setPolicy("<Policy>");
        // Not required, the external ID of the RAM role
        // This parameter is provided by an external party and is used to prevent the confused deputy problem.
        credentialsConfig.setExternalId("<ExternalId>");
        // 會話有效時間
        credentialsConfig.setRoleSessionExpiration(3600);
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        // 使用Credentials初始化ECS Client。
        Config ecsConfig = new Config();
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        ecsConfig.setCredential(credentialClient);
        Client ecsClient = new Client(ecsConfig);
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

方式五：使用ECS執行個體RAM角色

ECS和ECI執行個體均支援綁定執行個體RAM角色，當在執行個體中使用Credentials工具時，將自動擷取執行個體綁定的RAM角色，並通過訪問中繼資料服務擷取RAM角色的STS Token，以完成憑據用戶端的初始化。

執行個體中繼資料服務器支援加固模式和普通模式兩種訪問方式，Credentials工具預設使用加固模式（IMDSv2）擷取訪問憑據。若使用加固模式時發生異常，您可以通過設定DisableIMDSv1來執行不同的異常處理邏輯：

當值為false（預設值）時，會使用普通模式繼續擷取訪問憑據。
當值為true時，表示只能使用加固模式擷取訪問憑據，會拋出異常。

服務端是否支援IMDSv2，取決於您在伺服器的配置。

說明

關於ECS執行個體中繼資料的介紹，請參見執行個體中繼資料。
如何為ECS和ECI執行個體授予RAM角色，具體操作請參見建立ECS執行個體RAM角色並授予給ECS和為ECI執行個體授予執行個體RAM角色。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ecs_ram_role");
        // 選填，該ECS角色的角色名稱，不填會自動擷取，但是建議加上以減少請求次數，可以通過環境變數ALIBABA_CLOUD_ECS_METADATA設定RoleName
        credentialConfig.setRoleName("<RoleName>");
        // true表示強制使用加固模式。預設值：false,系統將首先嘗試在加固模式下擷取憑據。如果失敗，則會切換到普通模式進行嘗試（IMDSv1）。
        // credentialConfig.setDisableIMDSv1(true);
        Client credentialClient = new Client(credentialConfig);
    }
}

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用 EcsRamRole 初始化Credentials Client。
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // 憑證類型。
        credentialsConfig.setType("ecs_ram_role");
        // 選填，該ECS角色的角色名稱，不填會自動擷取，但是建議加上以減少請求次數，可以通過環境變數ALIBABA_CLOUD_ECS_METADATA設定RoleName
        credentialsConfig.setRoleName("<RoleName>");

        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // 配置雲產品服務接入地址（endpoint）。
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // 使用Credentials配置憑證。
        ecsConfig.setCredential(credentialClient);
        // 初始化ECS Client。
        Client ecsClient = new Client(ecsConfig);
        // 初始化DescribeRegions請求。
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

方式六：使用OIDCRoleArn

在Container Service for Kubernetes中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署您的客戶提交的應用，代碼也沒有對您開放），您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的 STS Token，實現應用層級的許可權最小化，您可以使用RRSA（RAM Roles for Service Account）功能。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC - OIDC角色SSO時擷取扮演角色的臨時身份憑證介面換取綁定角色的STS Token。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。

注入的環境變數如下：

ALIBABA_CLOUD_ROLE_ARN：RAM角色名稱ARN；

ALIBABA_CLOUD_OIDC_PROVIDER_ARN：OIDC供應商ARN；

ALIBABA_CLOUD_OIDC_TOKEN_FILE：OIDC Token檔案路徑；

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {

  public static void main(String[] args) throws Exception {
    Config credentialConfig = new Config();
    credentialConfig.setType("oidc_role_arn");
    // RAM角色名稱ARN，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
    credentialConfig.setRoleArn("<RoleArn>");
    // OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定OidcProviderArn
    credentialConfig.setOidcProviderArn("<OidcProviderArn>");
    // OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定OidcTokenFilePath
    credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
    // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
    credentialConfig.setRoleSessionName("<RoleSessionName>");
    // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    credentialConfig.setPolicy("<Policy>");
    // 設定session到期時間
    credentialConfig.setRoleSessionExpiration(3600);
    Client credentialClient = new Client(credentialConfig);
  }
}

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用OIDCRoleArn初始化Credentials Client。
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // 憑證類型。
        credentialsConfig.setType("oidc_role_arn");
        // 角色ARN，可以通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn
        credentialConfig.setRoleArn("<RoleArn>");
        // OIDC供應商ARN，可以通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定OidcProviderArn
        credentialConfig.setOidcProviderArn("<OidcProviderArn>");
        // OIDC Token檔案路徑，可以通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定OidcTokenFilePath
        credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
        // 角色會話名稱，可以通過環境變數ALIBABA_CLOUD_ROLE_SESSION_NAME設定RoleSessionName
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // 設定更小的權限原則，非必填。樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        credentialsConfig.setPolicy("<Policy>");
        // 設定session到期時間
        credentialsConfig.setRoleSessionExpiration(3600);
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // 配置雲產品服務接入地址（endpoint）。
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // 使用Credentials配置憑證。
        ecsConfig.setCredential(credentialClient);
        // 初始化ECS Client。
        Client ecsClient = new Client(ecsConfig);
        // 初始化DescribeRegions請求。
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

方式七：使用URI憑據

該方案底層實現是STS Token。Credentials工具通過您提供的URI擷取STS Token，完成憑據用戶端初始化。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("credentials_uri");
        // 憑證的 URI，格式為http://local_or_remote_uri/，可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定CredentialsUri
        credentialConfig.setCredentialsUri("<CredentialsUri>");
        Client credentialClient = new Client(credentialConfig);
    }
}

介面調用方法

指定Credentials提供地址，實現通過本地或遠端URI來擷取並自動更新Token，完成雲產品介面的調用。

調用單個雲產品的介面需要雲產品依賴。本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝ECS SDK。

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用URI憑據初始化Credentials Client。
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // 憑證類型。
        credentialsConfig.setType("credentials_uri");
        // 從環境變數擷取Credentials URI，格式為http://local_or_remote_uri/，可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定CredentialsUri
        credentialsConfig.setCredentialsUri("<CredentialsUri>");
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config ecsConfig = new Config();
        // 配置雲產品服務接入地址（endpoint）。
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // 使用Credentials配置憑證。
        ecsConfig.setCredential(credentialClient);
        // 初始化ECS Client。
        Client ecsClient = new Client(ecsConfig);
        // 初始化DescribeRegions請求。
        DescribeRegionsRequest describeInstancesRequest = new DescribeRegionsRequest();
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeInstancesRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

方式八：使用Bearer Token

目前只有Cloud Call CenterCCC這款產品支援Bearer Token的憑據初始化方式。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("bearer");
        // 填入您的Bearer Token
        credentialConfig.setBearerToken("<BearerToken>");
        Client credentialClient = new Client(credentialConfig);
    }
}

介面調用方法

本樣本以調用話務中心CCC的GetInstance介面為例，因此需先安裝CCC SDK。

import com.aliyun.ccc20200701.Client;
import com.aliyun.ccc20200701.models.GetInstanceRequest;
import com.aliyun.ccc20200701.models.GetInstanceResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用Bearer Token初始化Credentials Client。
        com.aliyun.credentials.models.Config credentialsConfig = new com.aliyun.credentials.models.Config();
        // 憑證類型。
        credentialsConfig.setType("bearer");
        // 伺服器端自動產生的Bearer Token，帶有效期間。
        credentialsConfig.setBearerToken("<bearer_token>");
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client(credentialsConfig);

        Config cccConfig = new Config();
        // 配置雲產品服務接入地址（endpoint）。
        cccConfig.setEndpoint("ccc.aliyuncs.com");
        // 使用Credentials配置憑證。
        cccConfig.setCredential(credentialClient);
        Client cccClient = new Client(cccConfig);
        GetInstanceRequest getInstanceRequest = new GetInstanceRequest().setInstanceId("ccc-test");
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        GetInstanceResponse response = cccClient.getInstanceWithOptions(getInstanceRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

預設憑據鏈

當您的程式開發環境和生產環境採用不同的憑據類型，常見做法是在代碼中擷取當前環境資訊，編寫擷取不同憑據的分支代碼。藉助Credentials工具的預設憑據鏈，您可以用同一套代碼，通過程式之外的配置來控制不同環境下的憑據擷取方式。當您在不傳入參數的情況下，直接使用Client client = new Client()初始化憑據用戶端時，阿里雲SDK將會嘗試按照如下順序尋找相關憑據資訊。

1. 使用系統屬性

Credentials工具會優先在系統屬性中擷取憑據資訊。

當系統屬性alibabacloud.accessKeyId（密鑰key）、alibabacloud.accessKeyIdSecret（密鑰value）均已設定且不為空白時，Credentials工具會優先使用它們作為預設憑據。

您可在運行Java程式時，添加屬性-Dalibabacloud.accessKeyId=*** -Dalibabacloud.accessKeyIdSecret=***來指定。

2. 使用環境變數

若不存在優先順序更高的憑據資訊，Credentials工具會優先在環境變數中擷取憑據資訊。

如果系統內容變數ALIBABA_CLOUD_ACCESS_KEY_ID（密鑰Key）和 ALIBABA_CLOUD_ACCESS_KEY_SECRET（密鑰Value）不為空白，Credentials工具會優先使用它們作為預設憑據。
如果系統內容變數ALIBABA_CLOUD_ACCESS_KEY_ID（密鑰Key）、ALIBABA_CLOUD_ACCESS_KEY_SECRET（密鑰Value）、ALIBABA_CLOUD_SECURITY_TOKEN（Token）均不為空白，Credentials工具會優先使用STS Token作為預設憑據。

3. 使用OIDC RAM角色

若不存在優先順序更高的憑據資訊，Credentials工具會在環境變數中擷取如下內容：

ALIBABA_CLOUD_ROLE_ARN：RAM角色名稱ARN；

ALIBABA_CLOUD_OIDC_PROVIDER_ARN：OIDC供應商ARN；

ALIBABA_CLOUD_OIDC_TOKEN_FILE：OIDC Token檔案路徑；

若以上三個環境變數都已設定內容，Credentials將會使用變數內容調用STS服務的AssumeRoleWithOIDC - OIDC角色SSO時擷取扮演角色的臨時身份憑證介面換取STS Token作為預設憑據。

4. 使用config.json設定檔

若不存在優先順序更高的憑據資訊，Credentials工具會優先在如下位置尋找config.json檔案是否存在：

Linux系統：~/.aliyun/config.json

Windows系統： C:\Users\USER_NAME\.aliyun\config.json

如果檔案存在，程式將會使用設定檔中current 指定的憑據資訊初始化憑據用戶端。當然，您也可以通過環境變數 ALIBABA_CLOUD_PROFILE 來指定憑據資訊，例如設定 ALIBABA_CLOUD_PROFILE 的值為client1。

在config.json設定檔中每個mode的值代表了不同的憑據資訊擷取方式：

AK：使用使用者的Access Key作為憑據資訊；
RamRoleArn：使用RAM角色的ARN來擷取憑據資訊；
EcsRamRole：利用ECS綁定的RAM角色來擷取憑據資訊；
OIDC：通過OIDC ARN和OIDC Token來擷取憑據資訊；
ChainableRamRoleArn：採用角色鏈的方式，通過指定JSON檔案中的其他憑據，以重新擷取新的憑據資訊。

配置樣本資訊如下：

{
	"current": "default",
	"profiles": [
		{
			"name": "default",
			"mode": "AK",
			"access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
			"access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
		},
		{
			"name":"client1",
			"mode":"RamRoleArn",
			"access_key_id":"<ALIBABA_CLOUD_ACCESS_KEY_ID>",
			"access_key_secret":"<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
			"ram_role_arn":"<ROLE_ARN>",
			"ram_session_name":"<ROLE_SESSION_NAME>",
			"expired_seconds":3600
		},
		{
			"name":"client2",
			"mode":"EcsRamRole",
			"ram_role_name":"<RAM_ROLE_ARN>"
		},
		{
			"name":"client3",
			"mode":"OIDC",
			"oidc_provider_arn":"<OIDC_PROVIDER_ARN>",
			"oidc_token_file":"<OIDC_TOKEN_FILE>",
			"ram_role_arn":"<ROLE_ARN>",
			"ram_session_name":"<ROLE_SESSION_NAME>",
			"expired_seconds":3600
		},
		{
			"name":"client4",
			"mode":"ChainableRamRoleArn",
			"source_profile":"<PROFILE_NAME>",
			"ram_role_arn":"<ROLE_ARN>",
			"ram_session_name":"<ROLE_SESSION_NAME>",
			"expired_seconds":3600
		}
	]
}

5. 使用ECS執行個體RAM角色

若不存在優先順序更高的憑據資訊，Credentials工具將通過環境變數擷取ALIBABA_CLOUD_ECS_METADATA（ECS執行個體RAM角色名稱）的值。若該變數的值存在，程式將採用加固模式（IMDSv2）訪問ECS的中繼資料服務（Meta Data Server），以擷取ECS執行個體RAM角色的STS Token作為預設憑據資訊。在使用加固模式時若發生異常，將使用普通模式兜底來擷取訪問憑據。您也可以通過設定環境變數ALIBABA_CLOUD_IMDSV1_DISABLED，執行不同的異常處理邏輯：

當值為false時，會使用普通模式繼續擷取訪問憑據。
當值為true時，表示只能使用加固模式擷取訪問憑據，會拋出異常。

服務端是否支援IMDSv2，取決於您在伺服器的配置。

6. 使用CredentialsURI

若不存在優先順序更高的憑據資訊，Credentials工具會在環境變數中擷取ALIBABA_CLOUD_CREDENTIALS_URI，若存在，程式將請求該URI地址，擷取臨時安全憑證作為預設憑據資訊。

如何切換憑據

當您想要在程式中使用不同的訪問憑據調用不同OpenAPI時，可以通過如下方式。

使用多個憑據用戶端

通過初始化多個憑據用戶端，傳入到不同的介面請求用戶端。

import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;

public class DemoTest {
    public static void main(String[] args) {
        Config credentialConfig1 = new Config();
        credentialConfig1.setType("access_key");
        credentialConfig1.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        credentialConfig1.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient1 = new Client(credentialConfig1);

        Config credentialConfig2 = new Config();
        credentialConfig2.setType("sts");
        credentialConfig2.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        credentialConfig2.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        credentialConfig2.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient2 = new Client(credentialConfig2);
    }
}

使用AuthUtils

當我們初始化憑據用戶端採用設定檔記錄憑據資訊時，可以使用AuthUtils.setClientType切換到不同的憑據配置上。範例程式碼如下。

import com.aliyun.credentials.utils.AuthUtils;

public class Sample {
    public static void main(String[] args) {
        // 若不配置AuthUtils類clientType屬性，則預設使用default。
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
        // 切換到client1憑據上
        AuthUtils.setClientType("client1");
        com.aliyun.credentials.Client credentialClient1 = new com.aliyun.credentials.Client();
        // 切換到client2憑據上
        AuthUtils.setClientType("client2");
        com.aliyun.credentials.Client credentialClient2 = new com.aliyun.credentials.Client();
    }
}

介面調用方法

本樣本以調用Elastic Compute Service的DescribeRegions介面為例，因此需先安裝。

import com.aliyun.credentials.utils.AuthUtils;
import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeRegionsRequest;
import com.aliyun.ecs20140526.models.DescribeRegionsResponse;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;

public class Sample {
    public static void main(String[] args) throws Exception {
        // 使用預設憑證初始化Credentials Client。
        com.aliyun.credentials.Client defaultCredentialClient = new com.aliyun.credentials.Client();
        // 使用設定檔中client1初始化Credentials Client。
        AuthUtils.setClientType("client1");
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();

        Config ecsConfig = new Config();
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        // 使用預設憑證配置憑證。
        ecsConfig.setCredential(defaultCredentialClient);
        // 初始化ECS Client。
        Client ecsClient = new Client(ecsConfig);
        // 初始化DescribeRegions請求。
        DescribeRegionsRequest describeRegionsRequest = new DescribeRegionsRequest();
        // 初始化運行時配置。
        RuntimeOptions runtime = new RuntimeOptions();
        // 調用DescribeRegions介面並獲得響應。
        DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
        System.out.println(response.body.toMap());
    }
}

Alibaba Cloud SDK：管理訪問憑據

背景資訊

前提條件

安裝Credentials工具

初始化憑據用戶端

方式一：使用預設憑據鏈

介面調用方法

方式二：使用AK

介面調用方法

方式三：使用STS Token

介面調用方法

方式四：使用AK及RamRoleArn

介面調用方法

方式五：使用ECS執行個體RAM角色

介面調用方法

方式六：使用OIDCRoleArn

介面調用方法

方式七：使用URI憑據

介面調用方法

方式八：使用Bearer Token

介面調用方法

預設憑據鏈

1. 使用系統屬性

2. 使用環境變數

3. 使用OIDC RAM角色

4. 使用config.json設定檔

5. 使用ECS執行個體RAM角色

6. 使用CredentialsURI

如何切換憑據

使用多個憑據用戶端

使用AuthUtils

介面調用方法

相關文檔