通过配置Credentials实现OpenAPI安全调用（JAVA SDK） - 阿里云SDK

在使用阿里云SDK调用OpenAPI进行资源操作时，正确配置凭证信息至关重要。阿里云Credentials工具提供了一整套便捷功能，支持多种凭证类型，包括默认凭证、AccessKey（AK）以及STS令牌等，以帮助您高效获取和管理访问凭证。本文将详细介绍各种类型凭证的配置方法以及如何根据优先级使用默认凭证。通过本文，您将深入理解如何在阿里云SDK中配置和维护凭证，从而确保对云资源的操作既高效又具有高度安全性。

背景信息

凭据是指用户证明其身份的一组信息。用户在系统中进行登录时，需要提供正确的凭据才能验证身份。常见的凭据类型有：

阿里云主账号和RAM用户的永久凭据 AccessKey（简称AK）是由AccessKey ID和AccessKey Secret组成的密钥对。
阿里云RAM角色的STS临时访问Token，简称STS Token。它是可以自定义时效和访问权限的临时身份凭据，详情请参见什么是STS。
Bearer Token。它是一种身份验证和授权的令牌类型。

前提条件

使用Credentials工具需要Java 8或更高版本。
使用V2.0代系的阿里云SDK，请参见通过IDE使用阿里云Java SDK。

安装Credentials工具

Maven安装方式如下：

<dependency>
   <groupId>com.aliyun</groupId>
   <artifactId>credentials-java</artifactId>
   <version>last-version</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>last-version</version>
</dependency>
```
说明
tea包的版本信息请参见tea-java。

Credentials工具配置参数介绍

Credentials工具的配置参数定义在com.aliyun.credentials.models.Config中，凭据类型由必填参数type指定。确定凭据类型后，需根据该凭据类型选择相应的参数。下表将详细介绍type的取值范围及各类凭据类型所支持的参数。其中，√表示必填参数，-表示可选参数，×表示不支持参数。

说明

未在下表中列出的凭据类型及参数表示不建议继续使用。

type	access_key	sts	ram_role_arn	ecs_ram_role	oidc_role_arn	credentials_uri	bearer
accessKeyId：访问凭据ID。	√	√	√	×	×	×	×
accessKeySecret：访问凭据密钥。	√	√	√	×	×	×	×
securityToken：STS Token。	×	√	-	×	×	×	×
roleArn：RAM角色的ARN。	×	×	√	×	√	×	×
roleSessionName：自定义会话名称，默认格式为`credentials-java-当前时间的时间戳`。	×	×	-	×	-	×	×
roleName：RAM角色名称。	×	×	×	-	×	×	×
disableIMDSv1：是否强制使用加固模式，默认值为`false`。	×	×	×	-	×	×	×
bearerToken：bearer token。	×	×	×	×	×	×	√
policy：自定义权限策略。	×	×	-	×	-	×	×
roleSessionExpiration：会话过期时间，默认3600秒。	×	×	-	×	-	×	×
oidcProviderArn：OIDC提供商ARN。	×	×	×	×	√	×	×
oidcTokenFilePath：OIDC Token文件路径。	×	×	×	×	√	×	×
externalId：角色外部 ID，主要功能是防止混淆代理人问题。更多信息，请参见使用ExternalId防止混淆代理人问题。	×	×	-	×	×	×	×
credentialsURI：凭证的URI。	×	×	×	×	×	√	×
STSEndpoint：STS的服务接入点，支持VPC服务接入点和公网服务接入点，可选的值请参见服务接入点，默认值为`sts.aliyuncs.com`。	×	×	-	×	-	×	×
timeout：HTTP请求的读超时时间，默认值为5000毫秒。	×	×	-	-	-	-	×
connectTimeout：HTTP请求的连接超时时间，默认值为10000毫秒。	×	×	-	-	-	-	×

初始化凭据客户端

Credentials工具支持多种方式初始化凭据客户端，您可根据实际情况选择合适的方式进行凭据客户端初始化。

重要

在项目中使用明文AccessKey，容易因代码仓库权限管理不当造成AccessKey泄露，会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式获取AccessKey。
在初始化凭据客户端时建议采用单例模式，这不仅可启用SDK的凭证缓存功能，还能有效防止因多次调用接口导致的流量控制问题和性能资源的浪费，详细信息请参见Session类型凭据自动刷新机制。

方式一：使用默认凭据链

当您在初始化凭据客户端不传入任何参数时，Credentials工具会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。

import com.aliyun.credentials.Client;

public class DemoTest {
    public static void main(String[] args) throws Exception{
        // 不指定参数
        Client credentialClient = new Client();
        // 省略使用凭据客户端初始化云产品客户端内容...
    }
}

接口调用示例

本示例以调用云服务器ECS的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();

        // 使用Credential Client初始化ECS客户端。
        Config ecsConfig = new Config();
        ecsConfig.setCredential(credentialClient);
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        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

该方式通过设置AK初始化凭据客户端，如何获取AK，请参见创建AccessKey。

警告

阿里云主账号拥有资源的全部权限，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);
        // 省略使用凭据客户端初始化云产品客户端内容...
    }
}

接口调用示例

本示例以调用云服务器ECS的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);

        // 使用Credential Client初始化ECS客户端。
        Config ecsConfig = new Config();
        ecsConfig.setCredential(credentialClient);
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        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

该方式是通过设置静态STS Token的方式初始化凭据。如何获取STS Token，请参见什么是STS。以下示例演示如何使用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"));
        // 从环境变量中获取AccessKey Secret的值
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // 从环境变量中获取临时SecurityToken的值
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        Client credentialClient = new Client(credentialConfig);
        // 省略使用凭据客户端初始化云产品客户端内容...
    }
}

接口调用示例

本示例以调用云服务器ECS的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);

        // // 使用Credential Client初始化ECS客户端。
        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工具可以调用AssumeRole接口获取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("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>");
    // 角色外部 ID，非必填。主要功能是防止混淆代理人问题
    credentialConfig.setExternalId("<ExternalId>");
    credentialConfig.setRoleSessionExpiration(3600);
    Client credentialClient = new Client(credentialConfig);
    // 省略使用凭据客户端初始化云产品客户端内容...
  }
}

接口调用示例

本示例以调用云服务器ECS的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 Client初始化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工具自动获取该角色的STS Token，从而完成凭据客户端的初始化。

Credentials工具将默认采用加固模式（IMDSv2）访问ECS的元数据服务（Meta Data Server），在使用加固模式时若发生异常，将使用普通模式兜底来获取访问凭据。您也可以通过设置参数disableIMDSv1或环境变量ALIBABA_CLOUD_IMDSV1_DISABLED，执行不同的异常处理逻辑：

当值为false（默认）时，会使用普通模式继续获取访问凭据。
当值为true时，表示只能使用加固模式获取访问凭据，会抛出异常。

服务端是否支持IMDSv2，取决于您在服务器的配置。

另外，您可以通过配置环境变量ALIBABA_CLOUD_ECS_METADATA_DISABLED=true来关闭ECS元数据的凭证访问。

说明

关于ECS实例元数据的介绍，请参见实例元数据。
如何为ECS和ECI实例授予RAM角色，具体操作请参见创建RAM角色并授予给ECS实例和为ECI实例授予实例RAM角色。

说明

使用加固模式获取临时身份凭证时，credentials-java的版本不低于0.3.10。

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(false);
        Client credentialClient = new Client(credentialConfig);
        // 省略使用凭据客户端初始化云产品客户端内容...
    }
}

接口调用示例

本示例以调用云服务器ECS的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);

        // 使用Credential Client初始化ECS客户端。
        Config ecsConfig = new Config();
        ecsConfig.setCredential(credentialClient);
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        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

为了避免影响云上资源的安全，同时又能让不可信的应用安全地获取所需的 STS Token，实现应用级别的权限最小化，您可以使用RRSA（RAM Roles for Service Account）功能。阿里云容器集群会为不同的应用Pod创建和挂载相应的服务账户OIDC Token文件，并将相关配置信息注入到环境变量中，Credentials工具通过获取环境变量的配置信息，调用STS服务的AssumeRoleWithOIDC接口换取绑定角色的STS Token。

注入的环境变量如下：

ALIBABA_CLOUD_ROLE_ARN：RAM角色名称ARN；

ALIBABA_CLOUD_OIDC_PROVIDER_ARN：OIDC提供商ARN；

ALIBABA_CLOUD_OIDC_TOKEN_FILE：OIDC Token文件路径；

说明

该功能要求credentials-java的版本不低于0.2.10。

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);
    // 省略使用凭据客户端初始化云产品客户端内容...
  }
}

接口调用示例

本示例以调用云服务器ECS的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
        credentialsConfig.setRoleArn("<RoleArn>");
        // OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OidcProviderArn
        credentialsConfig.setOidcProviderArn("<OidcProviderArn>");
        // OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OidcTokenFilePath
        credentialsConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
        // 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
        credentialsConfig.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);

        // 使用Credential Client初始化ECS客户端。
        Config ecsConfig = new Config();
        ecsConfig.setCredential(credentialClient);
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        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服务并对外提供自定义URI，其他服务仅能通过该URI获取STS Token，这样能够有效降低AK等信息的暴露风险。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);
        // 省略使用凭据客户端初始化云产品客户端内容...
    }
}

该地址必须满足如下条件：

支持GET请求。
响应状态码为2XX。

响应体为如下的结构：

{
  "Code": "Success",
  "AccessKeySecret": "AccessKeySecret",
  "AccessKeyId": "AccessKeyId",
  "Expiration": "2021-09-26T03:46:38Z",
  "SecurityToken": "SecurityToken"
}

接口调用示例

本示例以调用云服务器ECS的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);

        // 使用Credential Client初始化ECS客户端。
        Config ecsConfig = new Config();
        ecsConfig.setCredential(credentialClient);
        ecsConfig.setEndpoint("ecs.aliyuncs.com");
        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

目前只有云呼叫中心CCC这款产品支持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);

        // 使用Credential Client初始化ECS客户端。
        Config cccConfig = new Config();
        cccConfig.setCredential(credentialClient);
        cccConfig.setEndpoint("ccc.aliyuncs.com");
        Client cccClient = new Client(cccConfig);
        // 调用API
        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、alibabacloud.accessKeySecret时，使用AK作为访问凭据。
当在系统属性中定义了alibabacloud.accessKeyId、alibabacloud.accessKeySecret及alibabacloud.sessionToken时，使用STS Token作为访问凭据。

您可以通过运行Java程序时添加如下JVM参数指定这些值：

-Dalibabacloud.accessKeyId=your-access-key-id -Dalibabacloud.accessKeySecret=your-access-key-secret

2. 使用环境变量

如果未找到系统属性中的凭据信息，Credentials工具会继续检查环境变量。

如果ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET均存在且非空，则使用它们作为默认凭据。
如果同时设置了ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET和ALIBABA_CLOUD_SECURITY_TOKEN，则使用STS Token作为默认凭据。

3. 使用OIDC RAM角色

如果未找到更高优先级的凭据信息，Credentials工具会检查以下与OIDC RAM角色相关的环境变量：

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-java的版本不低于0.3.8。

如果未找到更高优先级的凭据信息，Credentials工具会尝试加载config.json配置文件。该文件的默认完整路径如下：

Linux系统：~/.aliyun/config.json
Windows系统： C:\Users\USER_NAME\.aliyun\config.json

请注意，这些默认路径不可更改为其他路径。如果您需要通过此方式配置访问凭据，您可以手动在相应路径下创建config.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": "client",
			"mode": "StsToken",
			"access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
			"access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
			"sts_token": "<SECURITY_TOKEN>"
		},
		{
			"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
		}
	]
}

在config.json配置文件中可以通过mode指定不同的凭据：

AK：使用用户的Access Key作为凭据信息；
StsToken：使用STS Token作为凭据信息；
RamRoleArn：使用RAM角色的ARN来获取凭据信息；
EcsRamRole：利用ECS绑定的RAM角色来获取凭据信息；
OIDC：通过OIDC ARN和OIDC Token来获取凭据信息；
ChainableRamRoleArn：采用角色链的方式，通过指定JSON文件中的其他凭据，以重新获取新的凭据信息。

说明

其中name为凭据名称，其他参数请根据实际情况修改。

配置完成后，Credentials将根据配置文件中current所指定的凭据名称，选择对应的凭据初始化凭据客户端。此外，还可以通过环境变量ALIBABA_CLOUD_PROFILE指定具体的凭据名称，例如将ALIBABA_CLOUD_PROFILE的值设置为client1。

5. 使用ECS实例RAM角色

如果未找到更高优先级的凭据信息，Credentials会尝试通过ECS实例绑定的RAM角色获取凭据。默认情况下，Credentials会使用加固模式（IMDSv2）访问ECS的元数据服务（Meta Data Server），以获取ECS实例RAM角色的STS Token作为默认凭据信息。程序会自动访问ECS的元数据服务拿到RoleName信息，再去获取凭证，也就是两次请求。若想减少一次请求，可以直接在环境变量中配置ALIBABA_CLOUD_ECS_METADATA来指定实例RAM角色名称。在使用加固模式时若发生异常，将使用普通模式兜底来获取访问凭据。您也可以通过设置环境变量ALIBABA_CLOUD_IMDSV1_DISABLE，执行不同的异常处理逻辑：

当值为false时，会使用普通模式继续获取访问凭据。
当值为true时，表示只能使用加固模式获取访问凭据，会抛出异常。

服务端是否支持IMDSv2，取决于您在服务器的配置。

另外，您可以通过配置环境变量ALIBABA_CLOUD_ECS_METADATA_DISABLED=true来关闭ECS元数据的凭证访问。

说明

关于ECS实例元数据的介绍，请参见实例元数据。
如何为ECS和ECI实例授予RAM角色，具体操作请参见创建RAM角色并授予给ECS实例和为ECI实例授予实例RAM角色。

说明

使用加固模式获取访问凭据要求credentials-java的版本不低于0.3.10。

6. 使用CredentialsURI

如果上述方式均未找到有效的凭据信息，Credentials工具会检查环境变量ALIBABA_CLOUD_CREDENTIALS_URI，如果该变量存在且指向一个有效的URI地址，Credentials会向该URI发起HTTP请求，获取临时安全凭证作为默认凭据。

Session类型凭据自动刷新机制

Session类型凭据包含RamRoleArn、ECS实例RAM角色、OIDCRoleArn以及URI凭据。该类型凭据Credentials工具中内置了自动刷新机制，在第一次调用服务获取访问凭据之后，Credentials工具会将获取的访问凭据保存到缓存中。当后续使用访问凭据时，若当前系统时间仍在缓存过期时间之前，将自动从缓存中提取凭据；否则，将重新调用相应服务获取访问凭据，并更新缓存中的值。

说明

针对ECS实例RAM角色凭据，Credentials工具会提前15分钟刷新缓存中的值。

下面将采用单例模式创建凭据客户端，并利用该凭据客户端初始化云产品客户端。随后，将通过多个时间段调用OpenAPI，以验证是否使用了内部缓存，并在缓存过期后检验凭据是否会刷新。

import com.aliyun.credentials.models.CredentialModel;
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;

import java.util.Date;
import java.util.concurrent.*;

public class Sample {

    /**
     * Credential类用于管理阿里云凭证实例，采用单例模式。
     */
    private static class Credential {
        private static volatile com.aliyun.credentials.Client instance;

        private Credential() {
        }

        public static com.aliyun.credentials.Client getInstance() {
            if (instance == null) {
                synchronized (Credential.class) {
                    if (instance == null) {
                        try {
                            com.aliyun.credentials.models.Config config = new com.aliyun.credentials.models.Config();
                            config.setType("ram_role_arn");
                            config.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
                            config.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
                            config.setRoleArn(System.getenv("ALIBABA_CLOUD_ROLE_ARN"));
                            config.setRoleSessionName("RamRoleArnTest");
                            config.setRoleSessionExpiration(3600);
                            instance = new com.aliyun.credentials.Client(config);
                        } catch (Exception e) {
                            throw new RuntimeException("Credential initialization failed: " + e.getMessage(), e);
                        }
                    }
                }
            }
            return instance;
        }
    }

    /**
     * EcsClient类用于管理ECS客户端，采用单例模式。
     */
    private static class EcsClient {
        private static volatile Client instance;

        private EcsClient() {
        }

        public static Client getInstance(com.aliyun.credentials.Client credentialClient) {
            if (instance == null) {
                synchronized (EcsClient.class) {
                    if (instance == null) {
                        try {
                            Config ecsConfig = new Config();
                            ecsConfig.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
                            ecsConfig.setCredential(credentialClient);
                            instance = new Client(ecsConfig);
                        } catch (Exception e) {
                            throw new RuntimeException("ECS client initialization failed: " + e.getMessage(), e);
                        }
                    }
                }
            }
            return instance;
        }
    }

    public static void main(String[] args) {
        // 使用ThreadPoolExecutor创建定时线程池
        ScheduledThreadPoolExecutor scheduler = new ScheduledThreadPoolExecutor(
                1,
                Executors.defaultThreadFactory(),
                new ThreadPoolExecutor.AbortPolicy()
        );
        scheduler.setKeepAliveTime(0L, TimeUnit.SECONDS);
        scheduler.allowCoreThreadTimeOut(false); // 不允许核心线程超时

        // 定义一个 Runnable 任务来执行调用逻辑
        Runnable task = () -> {
            try {
                com.aliyun.credentials.Client credentialClient = Credential.getInstance();
                CredentialModel credential = credentialClient.getCredential();
                System.out.println(new Date());
                System.out.printf("AK ID:%s, AK Secret:%s, STS Token:%s%n", credential.accessKeyId, credential.accessKeySecret, credential.securityToken);

                // 这里以调用ECS接口为例验证凭据是否可用，您可根据实际情况修改
                Client ecsClient = EcsClient.getInstance(credentialClient);
                DescribeRegionsRequest request = new DescribeRegionsRequest();
                RuntimeOptions runtime = new RuntimeOptions();
                DescribeRegionsResponse response = ecsClient.describeRegionsWithOptions(request, runtime);
                System.out.printf("Invoke result:%s%n", response.statusCode);
            } catch (Exception e) {
                throw new RuntimeException("ECS client execution failed: " + e.getMessage(), e);
            }
        };

        try {
            // 第一次执行任务（立即执行）
            scheduler.execute(task);
            // 第二次执行任务，延迟600秒后执行
            scheduler.schedule(task, 600, TimeUnit.SECONDS);
            // 第三次执行任务，在第二次基础上再延迟3600秒后执行
            scheduler.schedule(task, 4200, TimeUnit.SECONDS);
            // 第四次执行任务，在第三次基础上再延迟100秒后执行
            scheduler.schedule(task, 4300, TimeUnit.SECONDS);
        } finally {
            // 关闭线程池，确保所有任务完成后关闭
            scheduler.shutdown();
            try {
                if (!scheduler.awaitTermination(4500, TimeUnit.SECONDS)) {
                    scheduler.shutdownNow();
                }
            } catch (InterruptedException e) {
                scheduler.shutdownNow();
                Thread.currentThread().interrupt();
            }
        }
    }
}

根据日志显示结果进行分析：

在第一次调用时，由于未缓存凭据信息，系统根据配置获取凭据信息。获取到凭据后，凭据信息被保存在缓存中。
第二次调用所使用的凭据信息与第一次相同，表明第二次调用是从缓存中提取的凭据信息。
第三次调用时，由于凭据的过期时间（RoleSessionExpiration）被设置为3600秒，而第三次调用发生在第一次调用之后的4200秒，此时缓存中的凭据已过期。因此，SDK依据自动刷新机制重新获取了新的凭据信息，并将新获取的凭据信息再次保存于缓存中。
第四次调用所使用的凭据信息与第三次重新获取的凭据信息一致，这表明缓存中的凭据在过期后已被更新为新的凭据。

阿里云SDK：管理访问凭据

背景信息

前提条件

安装Credentials工具

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

Session类型凭据自动刷新机制

相关文档