AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 阿里云SDK 开发参考 Python SDK V2.0 Python SDK（推荐） 管理访问凭据

管理访问凭据

更新时间：
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

在使用阿里云SDK调用OpenAPI进行资源操作时，正确配置凭证信息至关重要。阿里云Credentials工具提供了一整套便捷功能，支持多种凭证类型，包括默认凭证、AccessKey（AK）以及STS令牌等，以帮助您高效获取和管理访问凭证。本文将详细介绍各种类型凭证的配置方法以及如何根据优先级使用默认凭证。通过本文，您将深入理解如何在阿里云SDK中配置和维护凭证，从而确保对云资源的操作既高效又具有高度安全性。

背景信息

凭据是指用户证明其身份的一组信息。用户在系统中进行登录时，需要提供正确的凭据才能验证身份。常见的凭据类型有：

  1. 阿里云主账号和RAM用户的永久凭据 AccessKey（简称AK）是由AccessKey ID和AccessKey Secret组成的密钥对。

  2. 阿里云RAM角色的STS临时访问Token，简称STS Token。它是可以自定义时效和访问权限的临时身份凭据，详情请参见什么是STS。

  3. Bearer Token。它是一种身份验证和授权的令牌类型。

前提条件

  • 使用Credentials工具要求Python版本 >= 3.7。

  • 使用V2.0代系的阿里云SDK。

安装Credentials工具

使用pip安装（推荐），如未安装pip，请先安装pip。更多信息，请参见pip官网pip user guide。

pip install alibabacloud_credentials

  • 使用最新发布Credentials依赖包，确保所有凭证支持。

  • 请查看ChangeLog.txt获取所有已发布的版本列表。

Credentials工具配置参数介绍

Credentials工具的配置参数定义在alibabacloud_credentials.models模块的Config类中，凭据类型由必填参数type指定。确定凭据类型后，需根据该凭据类型选择相应的参数。下表将详细介绍type的取值范围及各类凭据类型所支持的参数。其中，√表示必填参数，-表示可选参数，×表示不支持参数。

说明

未在下表中列出的凭据类型及参数表示不建议继续使用。

type

access_key

sts

ram_role_arn

ecs_ram_role

oidc_role_arn

credentials_uri

bearer

access_key_id：访问凭据ID。

√

√

√

×

×

×

×

access_key_secret：访问凭据密钥。

√

√

√

×

×

×

×

security_token：STS Token。

×

√

-

×

×

×

×

role_arn：RAM角色的ARN。

×

×

√

×

√

×

×

role_session_name：自定义会话名称，默认格式为credentials-python-当前时间的时间戳。

×

×

-

×

-

×

×

role_name：RAM角色名称。

×

×

×

-

×

×

×

disable_imds_v1：是否强制使用加固模式，默认值为false。

×

×

×

-

×

×

×

bearer_token：bearer token。

×

×

×

×

×

×

√

policy：自定义权限策略。

×

×

-

×

-

×

×

role_session_expiration：会话过期时间，默认3600秒。

×

×

-

×

-

×

×

oidc_provider_arn：OIDC提供商ARN。

×

×

×

×

√

×

×

oidc_token_file_path：OIDC Token文件路径。

×

×

×

×

√

×

×

external_id：角色外部 ID，主要功能是防止混淆代理人问题。更多信息，请参见使用ExternalId防止混淆代理人问题。

×

×

-

×

×

×

×

credentials_uri：凭证的URI。

×

×

×

×

×

√

×

sts_endpoint：STS的服务接入点，支持VPC服务接入点和公网服务接入点，可选的值请参见服务接入点，默认值为sts.aliyuncs.com。

×

×

-

×

-

×

×

timeout：HTTP请求的读超时时间，默认值为5000毫秒。

×

×

-

-

-

-

×

connect_timeout：HTTP请求的连接超时时间，默认值为10000毫秒。

×

×

-

-

-

-

×

初始化凭据客户端

Credentials工具支持多种方式初始化凭据客户端，您可根据实际情况选择合适的方式进行凭据客户端初始化。

重要

  • 在项目中使用明文AccessKey，容易因代码仓库权限管理不当造成AccessKey泄露，会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式获取AccessKey。

  • 在初始化凭据客户端时建议采用单例模式，这不仅可启用SDK的凭证缓存功能，还能有效防止因多次调用接口导致的流量控制问题和性能资源的浪费，详细信息请参见Session类型凭据自动刷新机制。

方式一：使用默认凭据链

当您在初始化凭据客户端不传入任何参数时，Credentials工具会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。

from alibabacloud_credentials.client import Client as CredClient

# 不指定参数
credentialsClient = CredClient()

credential = credentialsClient.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

通过默认凭据提供链自动创建访问凭证，并在不使用硬编码AccessKey的情况下成功调用云产品OpenAPI接口。

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

# Credentials和云产品SDK都需引入Client，此处为创建别名。
from alibabacloud_credentials.client import Client as CredClient
# 引入阿里云ECS SDK，此处以ECS产品为例。
from alibabacloud_ecs20140526.client import Client as EcsClient
# 使用ECS DescribeRegions接口发起调用请求。
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
# 引入阿里云SDK核心包。
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用默认凭证初始化Credentials Client。
credentialsClient = CredClient()
ecsConfig = Config(credential=credentialsClient)
# 配置云产品服务接入地址（endpoint）。
ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'
# 使用Credentials Client初始化ECS Client。
ecsClient = EcsClient(ecsConfig)
# 初始化DescribeRegions请求。
request = DescribeRegionsRequest()
# 初始化运行时配置。
runtime_options = RuntimeOptions()
# 调用DescribeRegions接口并获得响应。
response = ecsClient.describe_regions_with_options(request, runtime_options)
print(response.to_map())

方式二：使用AK

该方式通过设置AK初始化凭据客户端，如何获取AK，请参见创建AccessKey。

警告

阿里云主账号拥有资源的全部权限，AK一旦泄露，会给系统带来巨大风险，不建议使用。

推荐使用最小化授权的RAM用户的AK。

import os
from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config

config = Config(
	type='access_key',
	access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
	access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
)
cred = Client(config)

credential = cred.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

import os

# Credentials和云产品SDK都需引入Client，此处为创建别名。
from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CreConfig
# 引入阿里云ECS SDK，此处以ECS产品为例。
from alibabacloud_ecs20140526.client import Client as EcsClient
# 使用ECS DescribeRegions接口发起调用请求。
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用AK 初始化Credentials Client。
credentialsConfig = CreConfig(
    # 凭证类型。
    type='access_key',
    # 设置为AccessKey ID值。
    access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    # 设置为AccessKey Secret值。
    access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
)
credentialClient = CredClient(credentialsConfig)

ecsConfig = Config(credential=credentialClient)
# 配置云产品服务接入地址（endpoint）。
ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'
# 初始化ECS Client。
ecsClient = EcsClient(ecsConfig)

# 初始化DescribeRegions请求。
request = DescribeRegionsRequest()
# 初始化运行时配置。
runtime_options = RuntimeOptions()
# 调用DescribeRegions接口并获得响应。
response = ecsClient.describe_regions_with_options(request, runtime_options)
print(response.to_map())

方式三：使用STS Token

该方式是通过设置静态STS Token的方式初始化凭据。如何获取STS Token，请参见什么是STS。以下示例演示如何使用STS Token初始化凭据客户端（不包含如何获取到STS Token的过程）。

import os

from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config

config = Config(
    type='sts',
    # 从环境变量中获取AccessKey ID的值
    access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    # 从环境变量中获取AccessKeySecret的值
    access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    # 从环境变量中获取临时SecurityToken的值
    security_token=os.environ.get('ALIBABA_CLOUD_SECURITY_TOKEN')
)
credClient = Client(config)

credential = credClient.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK和STS SDK。

import os

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CreConfig
from alibabacloud_ecs20140526.client import Client as EcsClient
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
from alibabacloud_sts20150401.client import Client as Sts20150401Client
from alibabacloud_sts20150401.models import AssumeRoleRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 从环境变量中获取RAM用户ak
config = Config(
    access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
    access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
)
config.endpoint = "sts.aliyuncs.com"
stsClient = Sts20150401Client(config)

# 调AssumeRole API的参数
assume_role_request = AssumeRoleRequest(
    # 会话有效时间
    duration_seconds=3600,
    # 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
    role_arn='<role_arn>',
    # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
    role_session_name='<role_session_name>'
)
runtime = RuntimeOptions()
try:
    resp = stsClient.assume_role_with_options(assume_role_request, runtime)
    assumeRoleResponseBodyCredentials = resp.body.credentials

    # 使用STS Token初始化Credentials Client。
    credentialsConfig = CreConfig(
        # 凭证类型。
        type='sts',
        # 设置为AccessKey ID值。
        access_key_id=assumeRoleResponseBodyCredentials.access_key_id,
        # 设置为AccessKey Secret值。
        access_key_secret=assumeRoleResponseBodyCredentials.access_key_secret,
        # 设置为STS Token值。
        security_token=assumeRoleResponseBodyCredentials.security_token
    )
    credentialClient = CredClient(credentialsConfig)
    ecsConfig = Config(credential=credentialClient)
    # 配置云产品服务接入地址（endpoint）。
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'
    # 初始化ECS Client。
    ecsClient = EcsClient(ecsConfig)

    # 初始化DescribeRegions请求。
    request = DescribeRegionsRequest()
    # 初始化运行时配置。
    runtime_options = RuntimeOptions()
    # 调用DescribeRegions接口并获得响应。
    response = ecsClient.describe_regions_with_options(request, runtime_options)
    print(response.to_map())
except Exception as error:
    # 错误 message
    print(error.message)

方式四：使用AK及RamRoleArn

该方式底层实现是STS Token。通过指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具可以帮助开发者前往STS换取STS Token。您也可以通过为policy赋值来限制RAM角色到一个更小的权限集合。

import os

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig

credentialsConfig = CredConfig(
    access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    type='ram_role_arn',
    # 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
    role_arn='<role_arn>',
    # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
    role_session_name='<role_session_name>',
    # 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<policy>',
    role_session_expiration=3600
)
credentialsClient = CredClient(credentialsConfig)

credential = credentialsClient.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

import os

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig
from alibabacloud_ecs20140526.client import Client as EcsClient
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用RamRoleArn初始化Credentials Client。
credentialsConfig = CredConfig(
    type='ram_role_arn',  # 凭证类型。
    access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),  # 从环境变量中获取AccessKey ID。
    access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),  # 从环境变量中获取AccessKey Secret。
    # 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
    role_arn='<role_arn>',
    # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
    role_session_name='<role_session_name>',
    # 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<policy>',
    role_session_expiration=3600  # 会话有效时间
)
credentialsClient = CredClient(credentialsConfig)
ecsConfig = Config(credential=credentialsClient)
# 配置云产品服务接入地址（endpoint）。
ecsConfig.endpoint = 'ecs.aliyuncs.com'
# 使用Credentials Client初始化ECS Client。
ecsClient = EcsClient(ecsConfig)
# 初始化DescribeRegions请求。
request = DescribeRegionsRequest()
# 初始化运行时配置。
runtime_options = RuntimeOptions()
# 调用DescribeRegions接口并获得响应。
response = ecsClient.describe_regions_with_options(request, runtime_options)
print(response.to_map())

方式五：使用ECS实例RAM角色

ECS和ECI实例均支持绑定实例RAM角色，运行于实例中的程序可通过Credentials工具自动获取该角色的STS Token，从而完成凭据客户端的初始化。

Credentials工具将默认采用加固模式（IMDSv2）访问ECS的元数据服务（Meta Data Server），在使用加固模式时若发生异常，将使用普通模式兜底来获取访问凭据。您也可以通过设置参数enable_imds_v1或环境变量ALIBABA_CLOUD_IMDSV1_DISABLE，执行不同的异常处理逻辑：

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

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

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

另外，您可以通过配置环境变量ALIBABA_CLOUD_ECS_METADATA_DISABLED=true来关闭ECS元数据的凭证访问。

说明
说明

使用加固模式获取临时身份凭证时，alibabacloud_credentials的版本不低于0.3.6。

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig

credentialsConfig = CredConfig(
	type='ecs_ram_role',
	# 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置role_name
	role_name='<role_name>',
	# 选填，默认值：False。True：表示强制使用加固模式。False：系统将首先尝试在加固模式下获取凭据。如果失败，则会切换到普通模式（IMDSv1）进行尝试
	# enable_imds_v1=True,
)
credentialsClient = CredClient(credentialsConfig)

credential = credentialsClient.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

# Credentials和云产品SDK都需引入Client，此处为创建别名。
from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig
# 引入阿里云ECS SDK，此处以ECS产品为例。
from alibabacloud_ecs20140526.client import Client as EcsClient
# 使用ECS DescribeRegions接口发起调用请求。
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
# 引入阿里云SDK核心包。
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用EcsRamRole初始化Credentials Client。
credentialsConfig = CredConfig(
    type='ecs_ram_role',  # 凭证类型。
    # 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置role_name
    role_name='<role_name>'
)
credentialsClient = CredClient(credentialsConfig)
ecsConfig = Config(credential=credentialsClient)
# 配置云产品服务接入地址（endpoint）。
ecsConfig.endpoint = 'ecs.aliyuncs.com'
# 使用Credentials Client初始化ECS Client。
ecsClient = EcsClient(ecsConfig)

# 初始化DescribeRegions请求。
request = DescribeRegionsRequest()
# 初始化运行时配置。
runtime_options = RuntimeOptions()
# 调用DescribeRegions接口并获得响应。
response = ecsClient.describe_regions_with_options(request, runtime_options)
print(response.to_map())

方式六：使用OIDCRoleArn

说明

该功能要求alibabacloud_credentials的版本不低于0.3.1。

为了避免影响云上资源的安全，同时又能让不可信的应用安全地获取所需的 STS Token，实现应用级别的权限最小化，您可以使用RRSA（RAM Roles for Service Account）功能。阿里云容器集群会为不同的应用Pod创建和挂载相应的服务账户OIDC Token文件，并将相关配置信息注入到环境变量中，Credentials工具通过获取环境变量的配置信息，调用STS服务的AssumeRoleWithOIDC接口换取绑定角色的STS Token。

注入的环境变量如下：

ALIBABA_CLOUD_ROLE_ARN：RAM角色名称ARN；

ALIBABA_CLOUD_OIDC_PROVIDER_ARN：OIDC提供商ARN；

ALIBABA_CLOUD_OIDC_TOKEN_FILE：OIDC Token文件路径；

from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config

config = Config(
    type='oidc_role_arn',
    # RAM角色名称ARN，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
    role_arn='<role_arn>',
    # OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置oidc_provider_arn
    oidc_provider_arn='<oidc_provider_arn>',
    # OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置oidc_token_file_path
    oidc_token_file_path='<oidc_token_file_path>',
    # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
    role_session_name='<role_session_name>',
    # 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<policy>',
    # 设置session过期时间
    role_session_expiration=3600
)
cred = Client(config)

credential = cred.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig
from alibabacloud_ecs20140526.client import Client as EcsClient
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用OIDCRoleArn初始化Credentials Client。
credentialsConfig = CredConfig(
    type='oidc_role_arn',
    # RAM角色名称ARN，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置role_arn
    role_arn='<role_arn>',
    # OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置oidc_provider_arn
    oidc_provider_arn='<oidc_provider_arn>',
    # OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置oidc_token_file_path
    oidc_token_file_path='<oidc_token_file_path>',
    # 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置role_session_name
    role_session_name='<role_session_name>',
    # 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy='<policy>',
    # 设置session过期时间
    role_session_expiration=3600
)
credentialsClient = CredClient(credentialsConfig)
ecsConfig = Config(credential=credentialsClient)
# 配置云产品服务接入地址（endpoint）。
ecsConfig.endpoint = 'ecs.aliyuncs.com'
# 使用Credentials Client初始化ECS Client。
ecsClient = EcsClient(ecsConfig)

# 初始化DescribeRegions请求。
request = DescribeRegionsRequest()
# 初始化运行时配置。
runtime_options = RuntimeOptions()
# 调用DescribeRegions接口并获得响应。
response = ecsClient.describe_regions_with_options(request, runtime_options)
print(response.to_map())

方式七：使用URI凭据

通过在应用内部封装STS Token服务并对外提供自定义URI，其他服务仅能通过该URI获取STS Token，这样能够有效降低AK等信息的暴露风险。Credentials工具支持通过请求该服务的URI来获取STS Token，从而实现凭据客户端的初始化。

from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config

config = Config(
    type='credentials_uri',
    # 凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentials_uri
    credentials_uri='<credentials_uri>',
)
cred = Client(config)

credential = cred.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

该地址必须满足如下条件：

  • 支持GET请求。

  • 响应 200 状态码。

  • 响应体为如下的结构：

    {
  "Code": "Success",
  "AccessKeySecret": "AccessKeySecret",
  "AccessKeyId": "AccessKeyId",
  "Expiration": "2021-09-26T03:46:38Z",
  "SecurityToken": "SecurityToken"
}

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig
from alibabacloud_ecs20140526.client import Client as EcsClient
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用URI凭据初始化Credentials Client。
credentialsConfig = CredConfig(
    # 凭证类型。
    type='credentials_uri',
    # 凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentials_uri
    credentials_uri='<credentials_uri>',
)
credentialsClient = CredClient(credentialsConfig)
ecsConfig = Config(credential=credentialsClient)
# 配置云产品服务接入地址（endpoint）。
ecsConfig.endpoint = 'ecs.aliyuncs.com'
# 使用Credentials Client初始化ECS Client。
ecsClient = EcsClient(ecsConfig)

# 初始化DescribeRegions请求。
request = DescribeRegionsRequest()
# 初始化运行时配置。
runtime_options = RuntimeOptions()
# 调用DescribeRegions接口并获得响应。
response = ecsClient.describe_regions_with_options(request, runtime_options)
print(response.to_map())

方式八：使用Bearer Token

目前只有云呼叫中心CCC这款产品支持Bearer Token的凭据初始化方式。

from alibabacloud_credentials.client import Client
from alibabacloud_credentials.models import Config

config = Config(
	type='bearer',
	# 填入您的Bearer Token
	bearer_token='<BearerToken>',
)
cred = Client(config)

credential = cred.get_credential()
access_key_id = credential.get_access_key_id()
access_key_secret = credential.get_access_key_secret()
security_token = credential.get_security_token()
cred_type = credential.get_type()

接口调用方法

本示例以调用呼叫中心CCC的GetInstance接口为例，因此需先安装CCC SDK。

from alibabacloud_credentials.client import Client as CredClient
from alibabacloud_credentials.models import Config as CredConfig
from alibabacloud_ccc20200701.client import Client as CCC20200701Client
from alibabacloud_ccc20200701 import models as ccc20200701_models
from alibabacloud_tea_openapi.models import Config
from alibabacloud_tea_util.models import RuntimeOptions

# 使用Bearer Token初始化Credentials Client。
credentialsConfig = CredConfig(
    type='bearer',  # 凭证类型。
    bearer_token='<bearer_token>',  # 服务器端自动生成的Bearer Token，带有效期。
)
credentialsClient = CredClient(credentialsConfig)
config = Config(credential=credentialsClient)

# 配置云产品服务接入地址（endpoint）。
config.endpoint = 'ccc.cn-shanghai.aliyuncs.com'
# 使用Credentials Client初始化CCC Client。
cccClient = CCC20200701Client(config)

request = ccc20200701_models.GetInstanceRequest(
    instance_id='ccc-test'
)
# 初始化运行时配置。
runtime_options = RuntimeOptions()
response = cccClient.get_instance_with_options(request, runtime_options)
print(response.to_map())

默认凭据链

当您的程序开发环境和生产环境采用不同的凭据类型，常见做法是在代码中获取当前环境信息，编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链，您可以用同一套代码，通过程序之外的配置来控制不同环境下的凭据获取方式。当您在不传入参数的情况下，直接使用cred = CredClient()初始化凭据客户端时，阿里云SDK将会尝试按照如下顺序查找相关凭据信息。

1. 使用环境变量

如果未找到系统属性中的凭据信息，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作为默认凭据。

2. 使用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作为默认凭据。

3. 使用配置文件

说明

该功能要求alibabacloud_credentials的版本不低于1.0rc3。

如果未找到更高优先级的凭据信息，Credentials工具会尝试加载config.json配置文件。该文件的默认完整路径如下：

  • Linux/Mac系统：~/.aliyun/config.json

  • Windows系统： C:\Users\USER_NAME\.aliyun\config.json

请注意，这些默认路径不可更改为其他路径。如果您需要通过此方式配置访问凭据，您可以手动在相应路径下创建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
		}
	]
}

在config.json配置文件中可以通过mode指定不同的凭据：

  • AK：使用用户的Access Key作为凭据信息；

  • StsToken：使用STS Token作为凭据信息；

  • RamRoleArn：使用RAM角色的ARN来获取凭据信息；

  • EcsRamRole：利用ECS绑定的RAM角色来获取凭据信息；

  • OIDC：通过OIDC ARN和OIDC Token来获取凭据信息；

  • ChainableRamRoleArn：采用角色链的方式，通过source_profile指定config.json配置文件中其他凭据的名称，以重新获取新的凭据信息。

配置完成后，Credentials将根据配置文件中current所指定的凭据名称，选择对应的凭据初始化凭据客户端。此外，还可以通过环境变量 ALIBABA_CLOUD_PROFILE 指定具体的凭据名称，例如将 ALIBABA_CLOUD_PROFILE 的值设置为client1。

4. 使用ECS实例RAM角色

若不存在优先级更高的凭据信息，Credentials工具将默认采用加固模式（IMDSv2）访问ECS的元数据服务（Meta Data Server），以获取ECS实例RAM角色的STS Token作为默认凭据信息。程序会自动访问ECS的元数据服务拿到RoleName信息，再去获取凭证，也就是两次请求。若想减少一次请求，可以直接在环境变量中配置ALIBABA_CLOUD_ECS_METADATA来指定实例RAM角色名称。在使用加固模式时若发生异常，将使用普通模式兜底来获取访问凭据。您也可以通过设置环境变量ALIBABA_CLOUD_IMDSV1_DISABLED，执行不同的异常处理逻辑：

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

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

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

另外，您可以通过配置环境变量ALIBABA_CLOUD_ECS_METADATA_DISABLED=true来关闭ECS元数据的凭证访问。

5. 使用Credentials工具URI

如果上述方式均未找到有效的凭据信息，Credentials工具会检查环境变量 ALIBABA_CLOUD_CREDENTIALS_URI，如果该变量存在且指向一个有效的URI地址，Credentials会向该URI发起HTTP请求，获取临时安全凭证作为默认凭据。

Session类型凭据自动刷新机制

Session类型凭据包含RamRoleArn、ECS实例RAM角色、OIDCRoleArn以及URI凭据。该类型凭据Credentials工具中内置了自动刷新机制，在第一次调用服务获取访问凭据之后，Credentials工具会将获取的访问凭据保存到缓存中。当后续使用访问凭据时，若当前系统时间仍在缓存过期时间之前，将自动从缓存中提取凭据；否则，将重新调用相应服务获取访问凭据，并更新缓存中的值。

说明

针对ECS实例RAM角色凭据，Credentials工具会提前15分钟刷新缓存中的值。

下面将采用单例模式创建凭据客户端，并利用该凭据客户端初始化云产品客户端。随后，将通过多个时间段调用OpenAPI，以验证是否使用了内部缓存，并在缓存过期后检验凭据是否会刷新。

import os
import sys
import time
import threading
from functools import wraps
from threading import Lock

from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_credentials.models import Config as CredentialConfig
from alibabacloud_ecs20140526.client import Client
from alibabacloud_ecs20140526.models import DescribeRegionsRequest
from alibabacloud_tea_openapi.models import Config as EcsConfig


#
# 单例装饰器（线程安全）
#

def singleton(cls):
    """实现线程安全的单例模式"""
    instances = {}
    lock = Lock()

    @wraps(cls)
    def wrapper(*args, **kwargs):
        with lock:
            if cls not in instances:
                instances[cls] = cls(*args, **kwargs)
        return instances[cls]

    return wrapper


#
# 单例服务类
#

@singleton
class Credential:
    def __init__(self):
        self._client = self._init_client()

    @staticmethod
    def _init_client() -> CredentialClient:
        try:
            config = CredentialConfig(
                type="ram_role_arn",
                access_key_id=os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                access_key_secret=os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                role_arn=os.getenv("ALIBABA_CLOUD_ROLE_ARN"),
                role_session_name="RamRoleArnTest",
                role_session_expiration=3600,
            )
            return CredentialClient(config)
        except Exception as e:
            raise RuntimeError(f"Credential initialization failed: {e}") from e

    @property
    def client(self) -> CredentialClient:
        return self._client


@singleton
class EcsClient:
    def __init__(self, credential: CredentialClient):
        self._client = self._init_client(credential)

    @staticmethod
    def _init_client(credential: CredentialClient) -> Client:
        try:
            ecs_config = EcsConfig(credential=credential)
            ecs_config.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'
            return Client(ecs_config)
        except Exception as e:
            raise RuntimeError(f"ECS client initialization failed: {e}") from e

    @property
    def client(self) -> Client:
        return self._client


#
# 任务函数
#

def execute_task():
    try:
        # 获取凭证和ECS客户端
        credential = Credential().client.get_credential()
        ecs_client = EcsClient(Credential().client).client

        # 打印凭证信息
        print("Time:", time.strftime("%Y-%m-%d %H:%M:%S"))
        print("AK ID:", credential.access_key_id)
        print("AK Secret:", credential.access_key_secret)
        print("STS Token:", credential.security_token)

        # 调用API查询Region列表
        request = DescribeRegionsRequest()
        response = ecs_client.describe_regions(request)
        print("Invoke result:", response.to_map()["statusCode"])

    except Exception as e:
        print(f"ECS client execution failed: {e}")
        raise


def schedule_task():
    def run_execute_task():
        try:
            execute_task()
        except Exception as e:
            print(f"Task execution failed: {e}")
        finally:
            nonlocal task_count
            task_count += 1
            if task_count == len(DELAYS):
                print("All tasks completed. Exiting program.")
                sys.exit(0)

    def schedule_execution(delay):
        task_timer = threading.Timer(delay, run_execute_task)
        task_timer.start()
        return task_timer

    # 定时任务延迟定义
    DELAYS = [0, 600, 4200, 4300]
    task_count = 0

    timers = [schedule_execution(delay) for delay in DELAYS]

    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        print("Program interrupted by user.")
        for timer in timers:
            timer.cancel()


if __name__ == "__main__":
    schedule_task()

image

根据日志显示结果进行分析：

  • 在第一次调用时，由于未缓存凭据信息，系统根据配置获取凭据信息。获取到凭据后，凭据信息被保存在缓存中。

  • 第二次调用所使用的凭据信息与第一次相同，表明第二次调用是从缓存中提取的凭据信息。

  • 第三次调用时，由于凭据的过期时间（RoleSessionExpiration）被设置为3600秒，而第三次调用发生在第一次调用之后的4200秒，此时缓存中的凭据已过期。因此，SDK依据自动刷新机制重新获取了新的凭据信息，并将新获取的凭据信息再次保存于缓存中。

  • 第四次调用所使用的凭据信息与第三次重新获取的凭据信息一致，这表明缓存中的凭据在过期后已被更新为新的凭据。

相关文档

上一篇：Endpoint配置下一篇：进阶配置