当您通过阿里云SDK调用OpenAPI进行资源操作时,必须正确配置凭证信息。阿里云的Credentials工具提供了一套强大的功能,使您能够轻松地获取和管理这些访问凭证。无论是利用默认凭证,AccessKey(AK),还是安全令牌服务(STS)令牌等,Credentials工具都能为您提供相应支持。此外,本文档将详细阐述如何根据优先级使用默认凭证。您将深入理解如何在阿里云SDK中配置和维护凭证,从而确保您对云资源的操作既有效率又具有高度安全性。
背景信息
凭据是指用户证明其身份的一组信息。用户在系统中进行登录时,需要提供正确的凭据才能验证身份。常见的凭据类型有:
阿里云主账号和RAM用户的永久凭据 AccessKey(简称AK)是由AccessKey ID和AccessKey Secret组成的密钥对。
阿里云RAM角色的STS临时访问Token,简称STS Token。它是可以自定义时效和访问权限的临时身份凭据,详情请参见什么是STS。
Bearer Token。它是一种身份验证和授权的令牌类型。
前提条件
使用Credentials工具要求Go版本 >= 1.10.x。
使用V2.0代系的阿里云SDK,详情请参见通过IDE使用阿里云Go SDK。
安装Credentials工具
使用
go get
下载安装。
$ go get -u github.com/aliyun/credentials-go
如果您使用
dep
来管理的依赖包,您可以使用以下命令。
$ dep ensure -add github.com/aliyun/credentials-go
使用最新发布Credentials依赖包,确保所有凭证支持。
初始化凭据客户端
Credentials工具支持多种方式初始化凭据客户端,您可根据实际情况选择合适的方式进行凭据客户端初始化。
在项目中使用明文AccessKey,容易因代码仓库权限管理不当造成AccessKey泄露,会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式获取AccessKey。
方式一:使用默认凭据链
当您在初始化凭据客户端不传入任何参数时,Credentials会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。
package main
import (
"fmt"
"github.com/aliyun/credentials-go/credentials"
)
func main() {
// 不指定参数
config := new(credentials.Config)
credential, err := credentials.NewCredential(config)
}
接口调用方法
方式二:使用AK
阿里云账号、RAM用户可生成调用OpenAPI的密钥对AK。如何获取AK请参见文档创建AccessKey。您可使用AK初始化凭据客户端。
阿里云主账号拥有资源的全部权限,AK一旦泄露,会给系统带来巨大风险,不建议使用。
推荐使用最小化授权的RAM用户的AK。
import (
"fmt"
"os"
"github.com/aliyun/credentials-go/credentials"
)
func main() {
config := new(credentials.Config).
SetType("access_key").
SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
akCredential, err := credentials.NewCredential(config)
if err != nil {
return
}
accessKeyId, err := akCredential.GetAccessKeyId()
accessSecret, err := akCredential.GetAccessKeySecret()
credentialType := akCredential.GetType()
fmt.Println(accessKeyId, accessSecret, credentialType)
}
接口调用方法
方式三:使用STS Token
以一个RAM用户的身份调用STS服务的AssumeRole接口,设置Token的最大过期时间,即可换取到临时凭据STS Token。以下示例演示如何使用STS Token初始化凭据客户端(不包含如何获取到STS Token的过程)。
package main
import (
"fmt"
"github.com/aliyun/credentials-go/credentials"
"os"
)
func main() {
config := new(credentials.Config).
SetType("sts").
// 从环境变量中获取AccessKey Id。
SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
// 从环境变量中获取AccessKey Secret
SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
// 从环境变量中获取STS临时凭证。
SetSecurityToken(os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN"))
stsCredential, err := credentials.NewCredential(config)
if err != nil {
return
}
credential, err := stsCredential.GetCredential()
accessKeyId := credential.AccessKeyId
accessKeySecret := credential.AccessKeySecret
securityToken := credential.SecurityToken
credentialType := credential.Type
fmt.Println(accessKeyId, accessKeySecret, securityToken, credentialType)
}
接口调用方法
方式四:使用AK及RamRoleArn
该方式底层实现是STS Token。通过指定RAM角色的ARN(Alibabacloud Resource Name),Credentials工具可以帮助开发者前往STS换取STS Token。您也可以通过为SetPolicy
赋值来限制RAM角色到一个更小的权限集合。
package main
import (
"fmt"
"os"
"github.com/aliyun/credentials-go/credentials"
)
func main() {
config := new(credentials.Config).
SetType("ram_role_arn").
SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
// 要扮演的RAM角色ARN,示例值:acs:ram::123456789012****:role/adminrole,可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
SetRoleArn("<RoleArn>").
// 角色会话名称,可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
SetRoleSessionName("<RoleSessionName>").
// 设置更小的权限策略,非必填。示例值:{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
SetPolicy("<Policy>").
// 非必填,设置session过期时间。
SetRoleSessionExpiration(3600).
// 非必填,角色外部 ID,该参数为外部提供的用于表示角色的参数信息,主要功能是防止混淆代理人问题。
SetExternalId("ExternalId").
// 非必填,默认为sts.aliyuncs.com,建议使用Region化的STS域名,选择地理位置更接近的Region可以保证网络连通性.
SetSTSEndpoint("sts.cn-hangzhou.aliyuncs.com")
arnCredential, err := credentials.NewCredential(config)
if err != nil {
return
}
credential, err := arnCredential.GetCredential()
accessKeyId := credential.AccessKeyId
accessKeySecret := credential.AccessKeySecret
securityToken := credential.SecurityToken
credentialType := credential.Type
fmt.Println(accessKeyId, accessKeySecret, securityToken, credentialType)
}
ExternalId的更多介绍,请参见使用ExternalId防止混淆代理人问题。
接口调用方法
方式五:使用ECS实例RAM角色
ECS和ECI实例均支持绑定实例RAM角色,当在实例中使用Credentials工具时,将自动获取实例绑定的RAM角色,并通过访问元数据服务获取RAM角色的STS Token,以完成凭据客户端的初始化。
实例元数据服务器支持加固模式和普通模式两种访问方式,Credentials工具默认使用加固模式(IMDSv2)获取访问凭据。若使用加固模式时发生异常,您可以通过设置DisableIMDSv1
来执行不同的异常处理逻辑:
当值为
false
(默认值)时,会使用普通模式继续获取访问凭据。当值为
true
时,表示只能使用加固模式获取访问凭据,会抛出异常。
服务端是否支持IMDSv2,取决于您在服务器的配置。
关于ECS实例元数据的介绍,请参见实例元数据。
如何为ECS和ECI实例授予RAM角色,具体操作请参见创建RAM角色并授予给ECS实例和为ECI实例授予实例RAM角色。
package main
import (
"fmt"
"github.com/aliyun/credentials-go/credentials"
)
func _main(args []*string) {
// 使用EcsRamRole初始化Credentials Client。
credentialsConfig := new(credentials.Config).
// 凭证类型。
SetType("ecs_ram_role").
// 选填,该ECS角色的角色名称,不填会自动获取,但是建议加上以减少请求次数,可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName
SetRoleName("<RoleName>")
// true表示强制使用加固模式。默认值:false,系统将首先尝试在加固模式下获取凭据。如果失败,则会切换到普通模式进行尝试(IMDSv1)。
// credentialsConfig.SetDisableIMDSv1(true)
credentialClient, err := credentials.NewCredential(credentialsConfig)
if err != nil {
return
}
credential, err := credentialClient.GetCredential()
accessKeyId := credential.AccessKeyId
accessKeySecret := credential.AccessKeySecret
securityToken := credential.SecurityToken
credentialType := credential.Type
fmt.Println(accessKeyId, accessKeySecret, securityToken, credentialType)
}
接口调用方法
方式六:使用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文件路径;
package main
import (
"fmt"
"github.com/aliyun/credentials-go/credentials"
"os"
)
func main() {
config := new(credentials.Config).
SetType("oidc_role_arn").
// OIDC提供商ARN,可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OidcProviderArn
SetOIDCProviderArn(os.Getenv("ALIBABA_CLOUD_OIDC_PROVIDER_ARN")).
// OIDC Token文件路径,可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OidcTokenFilePath
SetOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
// RAM角色名称ARN,可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
SetRoleArn(os.Getenv("ALIBABA_CLOUD_ROLE_ARN")).
// 角色会话名称,可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
SetRoleSessionName(os.Getenv("ALIBABA_CLOUD_ROLE_SESSION_NAME")).
// 设置更小的权限策略,非必填。示例值:{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
SetPolicy("<Policy>").
// 非必填,设置session过期时间
SetRoleSessionExpiration(3600).
// 非必填,默认为sts.aliyuncs.com,建议使用Region化的STS域名,选择地理位置更接近的Region可以保证网络连通性
SetSTSEndpoint("sts.cn-hangzhou.aliyuncs.com")
oidcCredential, err := credentials.NewCredential(config)
if err != nil {
return
}
credential, err := oidcCredential.GetCredential()
accessKeyId := credential.AccessKeyId
accessKeySecret := credential.AccessKeySecret
securityToken := credential.SecurityToken
credentialType := credential.Type
fmt.Println(accessKeyId, accessKeySecret, securityToken, credentialType)
}
接口调用方法
方式七:使用URI凭据
该方案底层实现是STS Token。Credentials工具通过您提供的URI获取STS Token,完成凭据客户端初始化。
package main
import (
"github.com/aliyun/credentials-go/credentials"
)
func main() {
config := new(credentials.Config).
SetType("credentials_uri").
// 凭证的 URI,格式为http://local_or_remote_uri/,可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置CredentialsUri
SetCredentialsUri("<CredentialsUri>")
uriCredential, err := credentials.NewCredential(config)
}
接口调用方法
方式八:使用Bearer Token
目前只有云呼叫中心CCC这款产品支持Bearer Token的凭据初始化方式。
package main
import (
"fmt"
"github.com/aliyun/credentials-go/credentials"
)
func main() {
config := new(credentials.Config).
SetType("bearer").
// 填入您的Bearer Token
SetBearerToken("<BearerToken>")
bearerCredential, err := credentials.NewCredential(config)
if err != nil {
return
}
bearerToken := bearerCredential.GetBearerToken()
credentialType := bearerCredential.GetType()
fmt.Println(bearerToken, credentialType)
}
接口调用方法
默认凭据链
当开发环境与生产环境使用的凭据类型不一致时,常见做法是在代码中获取当前环境信息,编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链,您可以用同一套代码,通过程序之外的配置来控制不同环境下的凭据获取方式。当您使用NewCredential()
初始化凭据客户端,且不传入任何参数时,阿里云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地址,获取临时安全凭证作为默认凭据信息。
如何切换凭据
当您想要在程序中使用不同的访问凭据调用不同OpenAPI时,可以通过如下方式。
使用多个凭据客户端
通过初始化多个凭据客户端,传入到不同的接口请求客户端。
package main
import (
credentials "github.com/aliyun/credentials-go/credentials"
"os"
)
func main() {
config1 := new(credentials.Config).
SetType("access_key").
SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
akCredential, err1 := credentials.NewCredential(config1)
config2 := new(credentials.Config).
SetType("sts").
SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
SetSecurityToken(os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN"))
akCredential, err2 := credentials.NewCredential(config2)
}