AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

管理访问凭据

更新时间：
复制为 MD 格式
我的收藏

在使用阿里云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支持通过实例RAM角色服务来获取ECS RAM角色的授权信息，以访问阿里云资源和服务。使用这种方式，您在ECS上部署的应用程序无需在SDK中配置授权信息即可访问阿里云API（即无需配置AccessKey）。ECS和ECI实例均支持绑定实例RAM角色，当在实例中使用Credentials工具时，将自动获取实例绑定的RAM角色，并通过访问元数据服务获取RAM角色的STS Token，以完成凭据客户端的初始化。

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

  1. 当值为false（默认值）时，会使用普通模式继续获取访问凭据。

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

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

说明
重要

确保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/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. 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地址，获取临时安全凭证作为默认凭据信息。

上一篇：客户端初始化和请求方式下一篇：进阶配置