V1.0 Java SDK的認證資訊該如何配置 - Alibaba Cloud SDK

在使用阿里雲SDK調用OpenAPI操作資源時，必須正確配置憑證資訊。Java V1.0 SDK支援多種憑據配置方式，本文詳細闡述了如何配置訪問憑據，以確保安全有效地使用SDK進行開發。

前提條件

aliyun-java-sdk-core包的版本需要大於等於4.7.3。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.7.3</version>
</dependency>

方式一：使用AccessKey

重要

阿里雲帳號的AccessKey泄露會威脅該帳號下所有資源的安全。為保證帳號安全，強烈建議您使用RAM使用者的AccessKey。具體操作，請參見建立AccessKey。
請確保代碼運行環境已設定環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。具體操作，請參見在Linux、macOS和Windows系統配置環境變數。

通過DefaultProfile配置AccessKey初始化用戶端。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile(
                "<REGION_ID>",
                // 從環境變數擷取RAM使用者的AccessKey ID
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 從環境變數擷取RAM使用者的AccessKey Secret
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        // 省略調用API步驟...
    }
}

通過BasicCredentials配置AccessKey初始化用戶端。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.auth.BasicCredentials;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        BasicCredentials basicCredentials = new BasicCredentials(
                // 從環境變數擷取RAM使用者的AccessKey ID
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 從環境變數擷取RAM使用者的AccessKey Secret
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
        );
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        IAcsClient client = new DefaultAcsClient(profile, basicCredentials);
        // 省略調用API步驟...
    }
}

方式二：使用STS Token

使用臨時訪問憑據（STS Token）初始化憑據用戶端。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.profile.DefaultProfile;

public class Test {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile(
                "<REGION_ID>",
                // 從環境變數擷取RAM使用者的AccessKey ID
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 從環境變數擷取RAM使用者的AccessKey Secret
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                // STS Token
                System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        IAcsClient client = new DefaultAcsClient(profile);
        // 省略調用API步驟...
    }
}

方式三：使用RamRoleArn

以一個RAM使用者的身份調用STS服務的AssumeRole介面擷取STS Token。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.auth.STSAssumeRoleSessionCredentialsProvider;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        // 使用RamRoleArn方式
        STSAssumeRoleSessionCredentialsProvider stsProvider = STSAssumeRoleSessionCredentialsProvider
                .builder()
                // 從環境變數擷取RAM使用者的AccessKey ID，必填
                .accessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // 從環境變數擷取RAM使用者的AccessKey Secret，必填
                .accessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                // RAM角色ARN，當通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RAM角色ARN時非必填，否則必填
                .roleArn("<ROLE_ARN>")
                // 自訂會話名稱，非必填，可通過環境ALIBABA_CLOUD_ROLE_SESSION_NAME設定
                .roleSessionName("<ROLE_SESSION_NAME>")
                // 自訂權限原則，樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}，非必填
                .policy("<POLICY>")
                // 自訂外部ID，防止混淆代理人問題，非必填
                .externalId("<<EXTERNAL_ID>>")
                // 自訂會話憑證的有效期間，單位是秒，預設3600秒，不能超過12小時，非必填
                .durationSeconds(3600)
                // 調用STS AssumeRole介面對應的Region ID，非必填
                .stsRegionId("<STS_REGION_ID>") 
                .build();
        DefaultAcsClient client = new DefaultAcsClient(profile, stsProvider);
        // 省略調用API步驟...
    }
}

方式四：使用ECSRamRole

為了在提高應用部署安全性的同時增強便利性，阿里雲SDK支援通過ECS執行個體RAM角色Token服務來擷取ECS RAM角色的授權資訊，以訪問阿里雲資源和服務。使用這種方式，您在ECS上部署的應用程式無需在SDK中配置授權資訊即可訪問阿里雲API（即無需配置AccessKey）。ECS和ECI執行個體均支援綁定執行個體RAM角色，當在執行個體中使用Credentials工具時，將自動擷取執行個體綁定的RAM角色，並通過訪問中繼資料服務擷取RAM角色的STS Token，以完成憑據用戶端的初始化。

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

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

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

說明

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

重要

確保ECS執行個體已經配置了RAM角色。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.auth.InstanceProfileCredentialsProvider;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        // 使用ECSRamRole方式
        InstanceProfileCredentialsProvider provider = InstanceProfileCredentialsProvider
                .builder()
                // 執行個體綁定的RAM角色名稱
                .roleName("<ROLE_NAME>")
                //.disableIMDSv1(false)
                .build();
        DefaultAcsClient client = new DefaultAcsClient(profile, provider);
        // 省略調用API步驟...
    }
}

方式五：使用OIDCRoleArn

在Container ServiceKubernetes版中配置了Worker節點RAM角色後，您可以基於RRSA功能在叢集內實現Pod層級的應用關聯RAM角色功能。各個應用可以獨立扮演不同的RAM角色，並利用擷取的臨時憑證訪問雲資源，從而實現應用RAM許可權的最小化，並滿足無AccessKey訪問阿里雲OpenAPI的需求，以避免AccessKey泄露。

阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，SDK底層通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC - OIDC角色SSO時擷取扮演角色的臨時身份憑證介面換取綁定角色的STS Token。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.auth.OIDCCredentialsProvider;
import com.aliyuncs.profile.DefaultProfile;

public class Sample {
    public static void main(String[] args) {
        // 使用OIDC方式
        OIDCCredentialsProvider provider = OIDCCredentialsProvider
                .builder()
                // OIDC供應商ARN，通過環境變數ALIBABA_CLOUD_OIDC_PROVIDER_ARN設定OIDCProviderARN時非必填，否則為必填
                .oidcProviderArn(System.getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN"))
                // OIDC Token檔案路徑，通過環境變數ALIBABA_CLOUD_OIDC_TOKEN_FILE設定OIDCTokenFilePath時非必填，否則為必填
                .oidcTokenFilePath(System.getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE"))
                // RAM角色名稱ARN，通過環境變數ALIBABA_CLOUD_ROLE_ARN設定RoleArn時非必填，否則為必填
                .roleArn(System.getenv("ALIBABA_CLOUD_ROLE_ARN"))
                // 自訂會話名稱，非必填
                .roleSessionName("<ROLE_SESSION_NAME>")
                // 自訂權限原則，樣本值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}，非必填
                .policy("<POLICY>")
                // 自訂會話憑證的有效期間，單位是秒，預設3600秒，不能超過12小時，非必填
                .durationSeconds(3600)
                // 指定STS服務的region id，非必填
                .stsRegionId("<REGION_ID>")
                .build();
        DefaultProfile profile = DefaultProfile.getProfile(
                // 指定client的region id
                "<REGION_ID>");
        IAcsClient client = new DefaultAcsClient(profile, provider);
        // 省略調用API步驟...
    }
}

方式六：使用Bearertoken

說明

只有CCC這個產品支援此方式。

import com.aliyuncs.auth.BearerTokenCredentials;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.DefaultAcsClient;

public class BearerToken {
    public static void main(String[] args) {
        DefaultProfile profile = DefaultProfile.getProfile("<REGION_ID>");
        // 使用BearerTokenCredentials設定訪問憑據
        BearerTokenCredentials bearerTokenCredential = new BearerTokenCredentials("<BEARER_TOKEN>");
        DefaultAcsClient client = new DefaultAcsClient(profile, bearerTokenCredential);
        // 省略調用API步驟...
    }
}

方式七：使用預設憑證提供鏈

當您在初始化憑據用戶端不傳入任何參數時，SDK會使用預設憑據鏈方式初始化用戶端。

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;

public class Test {
    public static void main(String[] args) throws ClientException {
        // 使用預設憑據鏈
        IAcsClient client = new DefaultAcsClient("<REGION_ID>");
        // 省略調用API步驟...
    }
}

預設憑證提供者鏈將按照以下順序尋找可用的憑證：

1. 系統屬性

在系統屬性裡尋找環境憑證，如果定義了 alibabacloud.accessKeyId 和 alibabacloud.accessKeyIdSecret 系統屬性且不為空白，程式將使用它們建立預設憑證。

2. 環境憑證

在環境變數裡尋找環境憑證，如果定義了 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 環境變數且不為空白，程式將使用它們建立預設憑證。

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介面換取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角色名稱），若存在，程式將會通過ECS的中繼資料服務（Meta Data Server）擷取ECS執行個體RAM角色的STS Token作為預設憑據資訊。

6. 使用Credentials工具URI

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