在使用阿里云SDK调用OpenAPI操作资源时,必须正确配置凭证信息。Go V1.0 SDK支持多种凭据配置方式,本文详细阐述了如何配置访问凭据,以确保安全有效地使用SDK进行开发。
背景信息
在使用阿里云SDK进行开发时,需要根据具体的应用场景和授权需求选择合适的访问凭据类型,并正确配置和管理这些凭据。通过合理设置环境变量或配置文件,确保SDK能够正确读取和使用凭据,从而帮助开发者构建稳定、可靠的应用程序。
前提条件
Go 环境版本必须不低于 1.10.x。
安装 SDK 核心库 Core
go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk
初始化凭据客户端
方式一:使用默认凭证链
当您在初始化凭据客户端不传入任何参数时,SDK会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。
package main
import (
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials/provider"
)
func main() {
config := sdk.NewConfig()
// 不传参数
credentialsProvider := credentials.NewDefaultCredentialsProvider()
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou。
sdk.NewClientWithOptions("<REGION_ID>", config, credentialsProvider)
// 省略调用API步骤...
}
方式二:使用AK
阿里云账号和RAM用户可以生成用于调用OpenAPI的AccessKey密钥对,您可以使用该AccessKey初始化客户端。
由于主账号AccessKey有资源完全的权限,一旦泄露风险巨大。建议您使用RAM用户的AccessKey,并设置定期轮换,创建RAM用户AccessKey的方法请参见创建AccessKey。
package main
import (
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
)
func main() {
config := sdk.NewConfig()
// 这里通过环境变量获取RAM用户的AccessKey ID和AccessKey Secret,以避免硬编码带来的安全风险
credentialsProvider := credentials.NewStaticAKCredentialsProvider(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou
sdk.NewClientWithOptions("<REGION_ID>", config, credentialsProvider)
// 省略调用API步骤...
}
方式三:使用STS Token
通过安全令牌服务(Security Token Service,简称 STS),申请临时安全凭证(Temporary Security Credentials,简称 TSC),创建临时安全客户端。
package main
import (
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
)
func main() {
config := sdk.NewConfig()
// 这里通过环境变量获取RAM用户的AccessKey ID、AccessKey Secret和STS Token,以避免硬编码带来的安全风险
credentialsProvider := credentials.NewStaticSTSCredentialsProvider(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN"))
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou。
client, err := sdk.NewClientWithOptions("<REGION_ID>", config, credentialsProvider)
// 省略调用API步骤...
}
方式四:使用AK及RamRoleArn
通过指定RAM角色的ARN(Alibabacloud Resource Name)来初始化客户端。客户端在发起请求前,需先通过调用STS服务获取STS Token。若需限制STS Token的权限,可使用自定义权限策略.
package main
import (
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
)
func main() {
config := sdk.NewConfig()
credentialsProvider := credentials.NewRamRoleArnWithPolicyAndExternalIdCredential(
// os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"):从环境变量中获取RAM用户AccessKey ID
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
// os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"):从环境变量中获取RAM用户AccessKey Secret
os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
// "<ROLE_ARN>":指定要扮演的RAM角色的ARN。示例值:acs:ram::123456789012****:role/adminrole。
"<ROLE_ARN>",
// "<ROLE_SESSION_NAME>":指定角色会话的名称,用于标识和区分不同的会话。示例值:alice。
"<ROLE_SESSION_NAME>",
// "<POLICY>":指定一个自定义的授权策略用于限制角色会话的权限。示例值:{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}。
"<POLICY>",
// "<EXTERNAL_ID>":指定一个角色外部ID,防止混淆代理人问题。示例值:abcd1234。
"<EXTERNAL_ID>",
// <ROLE_SESSION_EXPIRATION>:Token 有效期。示例值:3600。
"<ROLE_SESSION_EXPIRATION>"
)
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou
client, err := sdk.NewClientWithOptions("<REGION_ID>", config, credentialsProvider)
// 省略调用API步骤...
}
方式五:使用ECS实例RAM角色
ECS和ECI实例均支持绑定实例RAM角色,当在实例中使用Credentials工具时,将自动获取实例绑定的RAM角色,并通过访问元数据服务获取RAM角色的STS Token,以完成凭据客户端的初始化。
实例元数据服务器支持加固模式和普通模式两种访问方式,Credentials工具默认使用加固模式(IMDSv2)获取访问凭据。若使用加固模式时发生异常,您可以通过环境变量ALIBABA_CLOUD_IMDSV1_DISABLED,执行不同的异常处理逻辑:
当值为
false
(默认值)时,会使用普通模式继续获取访问凭据。当值为
true
时,表示只能使用加固模式获取访问凭据,会抛出异常。
服务端是否支持IMDSv2,取决于您在服务器的配置。
关于ECS实例元数据的介绍,请参见实例元数据。
如何为ECS和ECI实例授予RAM角色,具体操作请参见创建RAM角色并授予给ECS实例和为ECI实例授予实例RAM角色。
package main
import (
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
)
func main() {
// 通过ECS实例的RAM角色来获取访问凭证,从而创建一个阿里云客户端
// 它适用于那些需要在ECS实例上运行,并且需要访问其他阿里云资源的程序
// "<ROLE_NAME>":指定要使用的RAM角色名称,您可以在环境变量ALIBABA_CLOUD_ECS_METADATA中设置 roleName 默认值。示例值:alice。
credentialsProvider := credentials.NewECSRAMRoleCredentialsProvider("<ROLE_NAME>")
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou。
client, err := sdk.NewClientWithOptions("<REGION_ID>", config, credentialsProvider)
// 省略调用API步骤...
}
方式六:使用OIDCRoleArn
在容器服务 Kubernetes 版中,设置 Worker 节点 RAM 角色后,节点内的 Pod 可以通过元数据服务获取关联角色的 STS Token。然而,对于不可信的应用(如客户提交的未公开代码的应用),直接通过元数据服务获取 STS Token 可能会带来安全风险。为了解决这一问题并实现应用级别的权限最小化,可以使用 RRSA(RAM Roles for Service Account)功能。这有助于确保云上资源的安全性,同时允许不可信应用安全地获取所需的 STS Token。阿里云容器集群会为不同的应用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文件路径;
package main
import (
"os"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
)
func main() {
config := sdk.NewConfig()
// 使用OIDCRoleArn初始化SDK客户端
oidcProvider, _ := credentials.NewOIDCCredentialsProviderBuilder().
// OIDC提供商ARN,可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OIDCProviderARN
WithOIDCProviderARN(os.Getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN")).
// OIDC Token文件路径,可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OIDCTokenFilePath
WithOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
// RAM角色名称ARN,可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
WithRoleArn(os.Getenv("ALIBABA_CLOUD_ROLE_ARN")).
// "<ROLE_SESSION_NAME>":自定义角色会话名称。示例值:alice。
WithRoleSessionName("<ROLE_SESSION_NAME>").
// "<POLICY>":设置更小的权限策略,非必填。示例值:{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}。
WithPolicy("<POLICY>").
// <ROLE_SESSION_EXPIRATION>:设置session过期时间。示例值:3600。
WithDurationSeconds( "<ROLE_SESSION_EXPIRATION>").
Build()
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou。
client, err := sdk.NewClientWithOptions("<REGION_ID>", config, oidcProvider)
// 省略调用API步骤...
}
方式七:使用Bearer Token
目前只有云呼叫中心CCC这款产品支持Bearer Token的凭据初始化方式。
package main
import (
"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
"github.com/aliyun/alibaba-cloud-sdk-go/sdk/auth/credentials"
)
func main() {
config := sdk.NewConfig()
// <BEARER_TOKEN>是一种认证方式,用于授权访问API
credentialsProvider := credentials.NewBearerTokenCredentialsProvider("BEARER_TOKEN")
// <REGION_ID>:指定客户端要访问的阿里云区域。示例值:cn_hangzhou。
client, err := sdk.NewClientWithOptions("<REGION_ID>", config, credentialsProvider)
// 省略调用API步骤...
}
默认凭据链
当开发环境与生产环境使用的凭据类型不一致时,常见做法是在代码中获取当前环境信息,编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链,您可以用同一套代码,通过程序之外的配置来控制不同环境下的凭据获取方式。当您使用credentials.NewDefaultCredentialsProvider()
初始化凭据客户端,且不传入任何参数时,阿里云SDK将会尝试按照如下顺序查找相关凭据信息。
1. 使用环境变量
若不存在优先级更高的凭据信息,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作为默认凭据。
2. 使用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作为默认凭据。
3. 使用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
}
]
}
4. 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,取决于您在服务器的配置。
5. 使用Credentials工具URI
若不存在优先级更高的凭据信息,Credentials工具会在环境变量中获取ALIBABA_CLOUD_CREDENTIALS_URI,若存在,程序将请求该URI地址,获取临时安全凭证作为默认凭据信息。