管理访问凭据
本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
在使用阿里云SDK调用OpenAPI进行资源操作时,正确配置凭证信息至关重要。本文将介绍支持的凭据类型以及如何在代码中配置这些凭据。
前提条件
通常情况下,在安装云产品SDK时会自动安装aliyun-java-auth包,如果未安装或者版本过低时,可以通过Maven方式安装。
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-auth</artifactId>
<version>last-version</version>
</dependency>最新版本信息,请参见aliyun-java-auth。
本文内容要求包版本不低于0.3.1-beta。
初始化凭据提供者
凭据提供者有多种实现方式,您可根据实际情况选择以下任意一种方式实现。
在项目中使用明文AccessKey,容易因代码仓库权限管理不当造成AccessKey泄露,会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式获取AccessKey。
在初始化凭据提供者时建议采用单例模式,这不仅可启用SDK的凭证缓存功能,还能有效防止因多次调用接口导致的流量控制问题和性能资源的浪费,
默认凭据提供者
默认凭据提供者的底层机制是通过内置的凭据提供者自动获取访问凭据。有关内置凭据及其实现逻辑的详细信息,内置凭据及其实现逻辑请参见默认凭据链。
import com.aliyun.auth.credentials.ICredential;
import com.aliyun.auth.credentials.provider.DefaultCredentialProvider;
import com.aliyun.auth.credentials.provider.EnvironmentVariableCredentialProvider;
import com.aliyun.auth.credentials.provider.SystemPropertiesCredentialProvider;
public class Demo {
public static void main(String[] args) {
DefaultCredentialProvider credentialProvider = DefaultCredentialProvider.builder()
// 自定义凭证提供者集合,默认凭据会遍历该集合,获取到有效凭证后,将不再遍历。
// 默认值包含:SystemPropertiesCredentialProvider、EnvironmentVariableCredentialProvider、OIDCRoleArnCredentialProvider、
// CLIProfileCredentialsProvider、EcsRamRoleCredentialProvider和URLCredentialProvider。
.customizeProviders(SystemPropertiesCredentialProvider.create(), EnvironmentVariableCredentialProvider.create())
// 是否开启复用上一次凭证提供者功能,默认值为true。当开启时,将会使用上一次的凭据提供者获取凭据,而不会再遍历customizeProviders获取
.reuseLastProviderEnabled(true)
.build();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
系统属性凭据提供者
从系统属性中获取访问凭据。
当在系统属性中定义了
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
import com.aliyun.auth.credentials.provider.SystemPropertiesCredentialProvider;
public class Demo {
public static void main(String[] args) {
SystemPropertiesCredentialProvider credentialProvider = SystemPropertiesCredentialProvider.create();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
环境变量凭据提供者
默认从环境变量中获取访问凭据:
如果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作为默认凭据。
import com.aliyun.auth.credentials.provider.EnvironmentVariableCredentialProvider;
public class Demo {
public static void main(String[] args) {
EnvironmentVariableCredentialProvider credentialProvider = EnvironmentVariableCredentialProvider.create();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
CLI配置文件凭据提供者
通过读取config.json配置文件获取访问凭据。
import com.aliyun.auth.credentials.provider.CLIProfileCredentialsProvider;
public class Demo {
public static void main(String[] args) {
CLIProfileCredentialsProvider credentialProvider = CLIProfileCredentialsProvider.builder()
// 设置凭据名称,非必填。当未通过环境变量ALIBABA_CLOUD_PROFILE配置凭据名称时,可通过该参数指定凭据名称获取凭据。
// 若未指定该参数且未配置环境变量ALIBABA_CLOUD_PROFILE时,则根据config.json中current指定的凭据名称获取凭据。
.profileName("<PROFILE_NAME>")
.build();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}使用此凭据时,您需要手动在如下路径创建config.json配置文件:
Linux系统:
~/.aliyun/config.jsonWindows系统:
C:\Users\USER_NAME\.aliyun\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为凭据名称,其他参数请根据实际情况修改。
配置完成后,SDK将根据配置文件中current所指定的凭据名称,选择对应的凭据初始化凭据客户端。此外,还可以通过环境变量ALIBABA_CLOUD_PROFILE 或在代码中指定凭据名称,例如将ALIBABA_CLOUD_PROFILE 的值设置为client1。
静态凭据提供者
静态凭据是指固定的访问凭据,包括AK和STS Token两种形式,适用于凭据保持不变的场景。
不建议使用,由于阿里云主账号拥有资源的全部权限,AK一旦泄露,会给系统带来巨大风险。因此推荐使用具有最小化授权的RAM用户的AK。
import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
public class Demo {
private static final String ACCESS_KEY_ID = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
private static final String ACCESS_KEY_SECRET = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
private static final String SECURITY_TOKEN = System.getenv("ALIBABA_CLOUD_SECURITY_TOKEN");
public static void main(String[] args) {
// 初始化凭证提供者
StaticCredentialProvider credentialProvider = StaticCredentialProvider.create(
Credential.builder()
.accessKeyId(ACCESS_KEY_ID)
.accessKeySecret(ACCESS_KEY_SECRET)
.securityToken(SECURITY_TOKEN)
.build()
);
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
RamRoleArn凭据提供者
该凭据提供者底层是通过调用STS服务的AssumeRole接口获取STS Token。
import com.aliyun.auth.credentials.Credential;
import com.aliyun.auth.credentials.provider.RamRoleArnCredentialProvider;
import com.aliyun.auth.credentials.provider.StaticCredentialProvider;
public class Demo {
public static void main(String[] args) {
// 初始化凭证提供者
StaticCredentialProvider staticCredentialProvider = StaticCredentialProvider.create(
Credential.builder()
.accessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
.accessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
.build()
);
RamRoleArnCredentialProvider credentialProvider = RamRoleArnCredentialProvider.builder()
// 其他凭据提供者,必填。
.credentialsProvider(staticCredentialProvider)
// RAM角色的ARN,必填。示例值:acs:ram::123456789012****:role/adminrole
.roleArn("<RAM_ROLE_ARN>")
// 自定义角色会话名称,建议设置为调用该API的用户身份,非必填。
.roleSessionName("<ROLE_SESSION_NAME>")
// 临时凭证的过期时间,单位:秒,默认3600秒,非必填。
.durationSeconds(3600)
// 设置更小的权限策略,非必填。示例值:{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
.policy("<POLICY>")
// 角色外部 ID,非必填。主要功能是防止混淆代理人问题
.externalId("<EXTERNAL_ID>")
// STS服务接入点,默认值为sts.aliyuncs.com,非必填。当设置了该值时,enableVpc和stsRegionId参数将不生效。
.stsEndpoint("sts.cn-hangzhou.aliyuncs.com")
// STS是否启用VPC Endpoint,默认为false,非必填。
.enableVpc(false)
// 通过RegionId拼接STS Endpoint,非必填。
.stsRegionId("cn-hangzhou")
// 调用AssumeRole时的连接超时,默认值为5000毫秒。
.connectionTimeout(5000)
// 调用AssumeRole时的读超时,默认值为10000毫秒。
.readTimeout(10000)
.build();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
EcsRamRole凭据提供者
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角色。
import com.aliyun.auth.credentials.provider.EcsRamRoleCredentialProvider;
public class Demo {
public static void main(String[] args) {
// 方式一
EcsRamRoleCredentialProvider credentialProvider = EcsRamRoleCredentialProvider.builder()
// ECS实例被授予的RAM角色名称,选填。不填会自动获取,建议加上以减少请求次数。可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName
.roleName("<ROLE_NAME>")
// true表示强制使用加固模式。默认值:false,系统将首先尝试在加固模式下获取凭据,如果失败,则会切换到普通模式进行尝试(IMDSv1)。
.disableIMDSv1(false)
// HttpClient连接超时,单位:毫秒,选填。默认值:1000
.connectionTimeout(1000)
// HttpClient读超时,单位:毫秒,选填。默认值:1000
.readTimeout(1000)
.build();
// 方式二:
// EcsRamRoleCredentialProvider credentialProvider = EcsRamRoleCredentialProvider.create("<ROLE_NAME>");
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}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.auth.credentials.provider.OIDCRoleArnCredentialProvider;
public class Demo {
public static void main(String[] args) {
OIDCRoleArnCredentialProvider credentialProvider = OIDCRoleArnCredentialProvider.builder()
// OIDC提供商ARN,可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OidcProviderArn
.oidcProviderArn("<OIDC_PROVIDER_ARN>")
// OIDC Token文件路径,可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OidcTokenFilePath
.oidcTokenFilePath("<OIDC_TOKEN_FILE_PATH>")
// RAM角色的ARN,必填。示例值:acs:ram::123456789012****:role/adminrole
.roleArn("<RAM_ROLE_ARN>")
// 自定义角色会话名称,建议设置为调用该API的用户身份,非必填。
.roleSessionName("<ROLE_SESSION_NAME>")
// 临时凭证的过期时间,单位:秒,默认3600秒,非必填。
.durationSeconds(3600)
// 设置更小的权限策略,非必填。示例值:{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
.policy("<POLICY>")
// STS服务接入点,默认值为sts.aliyuncs.com,非必填。当设置了该值时,enableVpc和stsRegionId参数将不生效。
.stsEndpoint("sts.cn-hangzhou.aliyuncs.com")
// STS是否启用VPC Endpoint,默认为false,非必填。
.enableVpc(false)
// 通过RegionId拼接STS Endpoint,非必填。
.stsRegionId("cn-hangzhou")
// 调用AssumeRoleWithOIDC时的连接超时时间,默认值为10000毫秒。
.readTimeout(10000)
// 调用AssumeRoleWithOIDC时的读超时,默认值为5000毫秒。
.connectionTimeout(5000)
.build();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
URL凭据提供者
通过封装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.auth.credentials.provider.URLCredentialProvider;
public class Demo {
public static void main(String[] args) {
URLCredentialProvider credentialProvider = URLCredentialProvider.builder()
// 凭证的 URI,格式为http://local_or_remote_uri/,可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentials_uri
.credentialsURI("http://localhost:8080/api/ecs/send")
// HTTP请求连接超时时间,单位:毫秒,默认5000毫秒,非必填。
.connectionTimeout(5000)
// HTTP请求读超时,单位:毫秒,默认10000毫秒,非必填。
.readTimeout(1000)
.build();
// 省略使用credentialProvider初始化AsyncClient步骤...
}
}
该地址必须满足如下条件:
支持GET请求。
响应状态码为2XX。
响应体为如下的结构:
{ "AccessKeyId": "AccessKeyId", "AccessKeySecret": "AccessKeySecret", "Code": "Success", "Expiration": "2025-07-04T15:06:21Z", "SecurityToken": "SecurityToken" }
默认凭据链
默认凭据链是一种兜底策略,按照内置的凭据查找顺序逐层向下查找,直至获取凭据信息。若所有情况均未成功获取到凭据信息,则会抛出异常。以下为查找顺序:
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. 使用配置文件
如果仍未获取到凭据信息,Credentials工具会尝试从默认路径加载config.json配置文件,并获取指定的凭据作为默认凭据。该文件的默认完整路径如下:
Linux/Mac:
~/.aliyun/config.jsonWindows:
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 | 凭据信息集合。通过参数
|
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角色。
6. 使用Credentials工具URI
如果仍未获取到凭据信息,Credentials工具会检查环境变量 ALIBABA_CLOUD_CREDENTIALS_URI,如果该变量存在且指向一个有效的URI地址,Credentials通过访问该URI来获取STS Token作为默认凭据。