V1.0 Java SDK的认证信息该如何配置 - 阿里云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

在容器服务Kubernetes版中配置了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地址，获取临时安全凭证作为默认凭据信息。