AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 阿里云SDK 开发参考 Java （同步）SDK V2.0 Java SDK（推荐） 管理访问凭据

管理访问凭据

更新时间：
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

在使用阿里云SDK时，凭据信息（例如AccessKey、STS Token等）由Credentials工具统一管理。本文将为您介绍Credentials工具支持的凭据类型及其配置方法，帮助您快速掌握Credentials工具的使用。

前提条件

安装Credentials工具

请使用最新发布的Credentials依赖包，以确保对所有功能的支持。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>credentials-java</artifactId>
  <version>latest-version</version>
</dependency>
<!-- 若单独使用credentials-java时，需额外引入tea包 -->
<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>tea</artifactId>
  <version>latest-version</version>
</dependency>

Credentials依赖包的最新版本信息，请查阅GitHub或Maven Repository；tea依赖包的最新版本信息，请查阅GitHub或Maven Repository。

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秒。最小值为900秒，最大值为RAM角色支持的最大会话时间。

不支持

不支持

-

不支持

-

不支持

不支持

oidcProviderArn：OIDC身份提供商ARN。

不支持

不支持

不支持

不支持

支持

不支持

不支持

oidcTokenFilePath：OIDC Token文件路径。

不支持

不支持

不支持

不支持

支持

不支持

不支持

externalId：角色外部 ID，主要功能是防止混淆代理人问题。更多信息，请参见使用ExternalId防止混淆代理人问题。

不支持

不支持

-

不支持

不支持

不支持

不支持

credentialsURI：外部凭据的URI。

不支持

不支持

不支持

不支持

不支持

支持

不支持

STSEndpoint：STS的服务接入点，支持VPC服务接入点和公网服务接入点，可选的值请参见服务接入点，默认值为sts.aliyuncs.com。

不支持

不支持

-

不支持

-

不支持

不支持

timeout：请求的读超时时间，默认值为5000毫秒。

不支持

不支持

-

-

-

-

不支持

connectTimeout：请求的连接超时时间，默认值为10000毫秒。

不支持

不支持

-

-

-

-

不支持

使用Credentials工具

前文已介绍Credentials工具所支持的凭据类型及其配置参数，接下来将通过详细的代码示例进一步说明，您可以根据具体情况选择适合的使用方式。

重要

  • 在项目中使用明文AccessKey，容易因代码仓库权限管理不当造成AccessKey泄露，会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式保存AccessKey。

  • 在使用Credentials工具时，建议采用单例模式。这一做法能够启用Credentials工具内置的凭据缓存功能，有效防止因多次调用接口而导致的限流问题，以及因创建多个实例而引起的资源浪费问题。详细信息请参见Session类型凭据自动刷新机制。

方式一：默认凭据链

说明

该方式是OpenAPI门户示例代码中默认采用的方式。

在使用Credentials工具时，如果不传入任何配置参数，Credentials工具将从默认凭据链中获取凭据，并将所获得的凭据作为访问凭据。在采用此方式时，必须确保在应用程序运行环境中已配置默认凭据链所支持的任意一种凭据获取方式。

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

public class DemoTest {
    public static void main(String[] args) throws Exception {
        // 不指定配置参数，将从默认凭据链中获取凭据。
        Client credentialClient = new Client();
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();


        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式二：AK

Credentials工具将使用您提供的AccessKey作为访问凭据。

警告

阿里云账号（主账号）拥有资源的全部权限，AK一旦泄露，会给系统带来巨大风险，不建议使用。

推荐使用最小化授权的RAM用户的AK。

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

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("access_key");
        // 必填参数，此处以从环境变量中获取AccessKey ID为例
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // 必填参数，此处以从环境变量中获取AccessKey Secret为例
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        Client credentialClient = new Client(credentialConfig);
                
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();

        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式三：STS Token

Credentials工具将使用您提供的静态STS Token作为访问凭据。

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

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);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();

        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式四：AK及RamRoleArn

Credentials工具将使用您提供的AK及RAM角色ARN调用AssumeRole获取STS Token，并将该STS Token作为访问凭据。通过此方式获取的凭据支持自动刷新，详情请参见Session类型凭据自动刷新机制。

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

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ram_role_arn");
        // 必填参数，此处以从环境变量中获取AccessKey ID为例
        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        // 必填参数，此处以从环境变量中获取AccessKey Secret为例
        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // 可选参数，支持使用临时凭据继续扮演其他RAM角色。
        credentialConfig.setSecurityToken(System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN"));
        // 必填参数，要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole。支持通过环境变量ALIBABA_CLOUD_ROLE_ARN设置。
        credentialConfig.setRoleArn("<RoleArn>");
        // 可选参数，角色会话名称，默认格式为：credentials-java-当前时间的时间戳。支持通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置。
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // 可选参数，设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}。
        credentialConfig.setPolicy("<Policy>");
        // 可选参数，角色外部ID，主要功能是防止混淆代理人问题。
        credentialConfig.setExternalId("<ExternalId>");
        // 可选参数，会话过期时间，默认3600秒。
        credentialConfig.setRoleSessionExpiration(3600);
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();

        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式五：ECS实例RAM角色

若您的应用程序运行于ECS或ECI实例，并且实例已被授予RAM角色，Credentials工具支持通过实例元数据获取该RAM角色的STS Token作为访问凭据。在访问实例元数据时，程序会首先获取授予给当前实例的RAM角色名称，然后再基于该角色获取对应的STS Token。您可以通过参数roleName或环境变量 ALIBABA_CLOUD_ECS_METADATA 指定RAM角色名称，从而减少获取凭据所需的时间，提升效率。通过此方式获取的凭据支持自动刷新，详情请参见Session类型凭据自动刷新机制。

Credentials工具将默认采用加固模式（IMDSv2）访问实例元数据。若在加固模式下发生异常，您可以通过参数disableIMDSv1或环境变量 ALIBABA_CLOUD_IMDSV1_DISABLED 来控制异常处理逻辑：

  • 当值为false（默认）时，系统将尝试切换到普通模式继续获取凭据；

  • 当值为true时，表示仅允许使用加固模式获取凭据，若加固模式访问失败则会抛出异常。

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

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

说明 
import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

public class DemoTest {
    public static void main(String[] args) throws Exception {
        Config credentialConfig = new Config();
        credentialConfig.setType("ecs_ram_role");
        // 可选参数，该ECS被授予的RAM角色的角色名称，不填会自动获取，建议加上以减少请求次数。支持通过环境变量ALIBABA_CLOUD_ECS_METADATA设置。
        credentialConfig.setRoleName("<RoleName>");
        // 可选参数，true表示强制使用加固模式。默认值：false,系统将首先尝试在加固模式下获取凭据。如果失败，则会切换到普通模式进行尝试。
        credentialConfig.setDisableIMDSv1(false);
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式六：OIDCRoleArn

若您使用OIDC认证协议，并已创建OIDC身份提供商的RAM角色，您可以通过Credentials工具传入OIDC身份提供商ARN、OIDC Token及RAM角色ARN，系统将自动调用AssumeRoleWithOIDC接口获取RAM角色的STS Token，并将该STS Token作为访问凭据。通过此方式获取的凭据支持自动刷新，详情请参见Session类型凭据自动刷新机制。例如当您的应用程序运行于已启用RRSA功能的ACK集群中时，Credentials工具支持通过读取Pod环境变量中的OIDC配置信息，调用AssumeRoleWithOIDC接口获取服务角色的STS Token，从而利用该STS Token访问阿里云相关服务。

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

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设置。
        credentialConfig.setRoleArn("<RoleArn>");
        // 必填参数，OIDC身份提供商ARN，支持通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置。
        credentialConfig.setOidcProviderArn("<OidcProviderArn>");
        // 必填参数，OIDC Token文件路径，支持通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置。
        credentialConfig.setOidcTokenFilePath("<OidcTokenFilePath>");
        // 可选参数，角色会话名称，支持通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置。
        credentialConfig.setRoleSessionName("<RoleSessionName>");
        // 可选参数，设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        credentialConfig.setPolicy("<Policy>");
        // 可选参数，session过期时间，默认值3600毫秒。
        credentialConfig.setRoleSessionExpiration(3600);
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式七：URI凭据

通过封装STS服务并对外暴露服务的URI，外部服务能够通过该URI获取STS Token，从而有效降低AK等敏感信息的暴露风险。Credentials工具支持通过访问您所提供的URI来获取STS Token，并将该STS Token作为访问凭据。通过此方式获取的凭据支持自动刷新，详情请参见Session类型凭据自动刷新机制。

该URI必须满足如下条件：

  • 支持GET请求。

  • 响应状态码为2XX。

  • 响应体为如下的结构：

    {
  "Code": "Success",
  "AccessKeySecret": "yourAccessKeySecret",
  "AccessKeyId": "STS.****************",
  "Expiration": "2021-09-26T03:46:38Z",
  "SecurityToken": "yourSecurityToken"
}
import com.aliyun.credentials.Client;
import com.aliyun.credentials.models.Config;
import com.aliyun.credentials.models.CredentialModel;

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设置。
        credentialConfig.setCredentialsUri("<CredentialsUri>");
        Client credentialClient = new Client(credentialConfig);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // 若使用云产品 V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 的代码...
    }
}

方式八：Bearer Token

目前只有云呼叫中心CCC这款产品支持Bearer Token。

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

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);
        
        CredentialModel credential = credentialClient.getCredential();
        String accessKeyId = credential.getAccessKeyId();
        String accessKeySecret = credential.getAccessKeySecret();
        String securityToken = credential.getSecurityToken();
        
        // 若使用CCC V2.0 SDK 时，使用com.aliyun.teaopenapi.models.Config传递credential
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setCredential(credentialClient);
        config.setEndpoint("<Endpoint>");
        // 省略使用 config 初始化云产品 client 内容...
    }
}

默认凭据链

默认凭据链是一种兜底策略，按照内置的凭据查找顺序逐层向下查找，直至获取凭据信息。若所有情况均未成功获取到凭据信息，则会抛出CredentialException。以下为查找顺序：

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/Mac：~/.aliyun/config.json

  • Windows： C:\Users\USER_NAME\.aliyun\config.json

如果您需要通过此方式配置凭据，您可以使用阿里云CLI工具配置凭据，或手动在相应路径下创建config.json配置文件。内容格式示例如下：

{
  "current": "<PROFILE_NAME>",
  "profiles": [
    {
      "name": "<PROFILE_NAME>",
      "mode": "AK",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
    },
    {
      "name": "<PROFILE_NAME1>",
      "mode": "StsToken",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "sts_token": "<SECURITY_TOKEN>"
    },
    {
      "name":"<PROFILE_NAME2>",
      "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":"<PROFILE_NAME3>",
      "mode":"EcsRamRole",
      "ram_role_name":"<RAM_ROLE_ARN>"
    },
    {
      "name":"<PROFILE_NAME4>",
      "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":"<PROFILE_NAME5>",
      "mode":"ChainableRamRoleArn",
      "source_profile":"<PROFILE_NAME>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    }
  ]
}

参数名称

参数介绍

current

指定凭据名称以获取相应的凭据配置信息，其值为profiles中参数name的值。默认情况下，系统优先使用环境变量 ALIBABA_CLOUD_PROFILE 指定的凭据名称；若该环境变量未配置，则将使用current指定的凭据名称。

profiles

凭据信息集合。通过参数mode指定凭据的类型：

  • AK：使用用户的AccessKey作为凭据信息；

  • StsToken：使用STS Token作为凭据信息；

  • RamRoleArn：通过RAM用户扮演RAM角色获取凭证信息。

  • EcsRamRole：通过实例元数据获取凭据信息；

  • OIDC：通过OIDC身份提供商ARN、OIDC Token和RAM角色ARN获取凭据信息；

  • ChainableRamRoleArn：采用角色链的方式，通过source_profile指定profiles中其他凭据的名称，以重新获取新的凭据信息。

5. 使用实例RAM角色

如果仍未获取到凭据信息，Credentials将尝试通过实例元数据获取授予给该实例的RAM角色的STS Token，并将其作为默认凭据。在访问实例元数据时，程序会首先获取授予给当前实例的RAM角色名称，然后再基于该角色获取对应的STS Token。您也可以通过环境变量 ALIBABA_CLOUD_ECS_METADATA 指定RAM角色名称，从而减少凭据获取所需的时间，提升效率。

默认情况下，Credentials 会使用加固模式（IMDSv2）访问元数据。若在加固模式下发生异常，您可以通过环境变量 ALIBABA_CLOUD_IMDSV1_DISABLED 来控制异常处理逻辑：

  • 当值为false（默认）时，系统将尝试切换到普通模式继续获取凭据；

  • 当值为true时，表示仅允许使用加固模式获取凭据，若加固模式访问失败则会抛出异常。

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

说明

6. 使用CredentialsURI

如果仍未获取到凭据信息，Credentials工具会检查环境变量 ALIBABA_CLOUD_CREDENTIALS_URI，如果该变量存在且指向一个有效的URI地址，Credentials通过访问该URI来获取STS Token作为默认凭据。

Session类型凭据自动刷新机制

Session类型凭据包含ram_role_arn、ecs_ram_role、oidc_role_arn以及credentials_uri，该类型凭据在Credentials工具中内置了凭据自动刷新机制。当凭据客户端首次获取凭据后，Credentials工具会将获取的凭据信息保存至缓存中。在后续使用过程中，同一凭据客户端实例将自动从缓存中提取凭据；若缓存中的凭据信息已过期，则凭据客户端实例将重新获取凭据，并更新缓存中的值。

说明

对于ecs_ram_role类型凭据，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();
            }
        }
    }
}

image

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

  • 在第一次调用时，由于未缓存凭据信息，系统根据配置获取凭据信息。获取到凭据后，凭据信息被保存在缓存中。

  • 第二次调用所使用的凭据信息与第一次相同，表明第二次调用是从缓存中提取的凭据信息。

  • 第三次调用时，由于凭据的过期时间（RoleSessionExpiration）被设置为3600秒，而第三次调用发生在第一次调用之后的4200秒，此时缓存中的凭据已过期。因此，SDK依据自动刷新机制重新获取了新的凭据信息，并将新获取的凭据信息再次保存于缓存中。

  • 第四次调用所使用的凭据信息与第三次重新获取的凭据信息一致，这表明缓存中的凭据在过期后已被更新为新的凭据。

相关文档

上一篇：Endpoint配置下一篇：进阶配置