AI 助理
备案控制台
文档
输入文档关键字查找
首页 阿里云SDK 开发参考 Go SDK V1.0 Go SDK 管理访问凭据

管理访问凭据

更新时间：
我的收藏

在使用阿里云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，执行不同的异常处理逻辑：

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

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

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

说明 
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，执行不同的异常处理逻辑：

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

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

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

5. 使用Credentials工具URI

若不存在优先级更高的凭据信息，Credentials工具会在环境变量中获取ALIBABA_CLOUD_CREDENTIALS_URI，若存在，程序将请求该URI地址，获取临时安全凭证作为默认凭据信息。

相关文档

上一篇：Endpoint下一篇：进阶配置
文档推荐