通过配置Credentials实现OpenAPI安全调用（JAVA SDK）_阿里云SDK(Alibaba Cloud SDK)-阿里云帮助中心

当您通过阿里云SDK调用OpenAPI进行资源操作时，必须正确配置凭证信息。阿里云的Credentials工具提供了一套强大的功能，使您能够轻松地获取和管理这些访问凭证。无论是利用默认凭证，AccessKey（AK），还是安全令牌服务（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;

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

阿里云账号、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接口的调用。

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

以一个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接口的调用。

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK和STS 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工具可以帮助开发者前往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);
    // 省略使用凭据客户端初始化云产品客户端内容...
  }
}

接口调用示例

本示例以调用云服务器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工具时，将自动获取实例绑定的RAM角色，并通过访问元数据服务获取RAM角色的STS Token，以完成凭据客户端的初始化。

实例元数据服务器支持加固模式和普通模式两种访问方式，Credentials工具默认使用加固模式（IMDSv2）获取访问凭据。若使用加固模式时发生异常，您可以通过设置DisableIMDSv1来执行不同的异常处理逻辑：

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

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

说明

关于ECS实例元数据的介绍，请参见实例元数据。
如何为ECS和ECI实例授予RAM角色，具体操作请参见创建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);
        // 省略使用凭据客户端初始化云产品客户端内容...
    }
}

接口调用示例

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

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

接口调用示例

本示例以调用云服务器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。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，完成云产品接口的调用。

调用单个云产品的接口需要云产品依赖。本示例以调用云服务器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（密钥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();
    }
}

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

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());
    }
}

管理访问凭据

背景信息

前提条件

安装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

接口调用方法

相关文档