AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 阿里云SDK 开发参考 .NET SDK V2.0 .NET 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。它是一种身份验证和授权的令牌类型。

前提条件

  • .NET Framework 4.5 及其以上版本。

  • .NET Standard 2.0 及其以上版本。

  • C# 4.0 及其以上版本。

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

安装Credentials工具

  • 通过 .NET CLI 工具安装。

    dotnet add package Aliyun.Credentials

  • 通过 NuGet 程序包管理器安装。

    1. 在解决方案资源管理器面板中右击您的项目选择管理 NuGet 程序包菜单。

    2. 通过打开的NuGet 管理面板中单击浏览选项卡输入Aliyun.Credentials。

    3. 下方列表中选择Authors为Alibaba Cloud由官方发布的包单击安装即可。

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

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

Credentials工具配置参数介绍

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

说明

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

Type

access_key

sts

ram_role_arn

ecs_ram_role

oidc_role_arn

credentials_uri

bearer

AccessKeyId：访问凭据ID。

√

√

√

×

×

×

×

AccessKeySecret：访问凭据密钥。

√

√

√

×

×

×

×

SecurityToken：STS Token。

×

√

-

×

×

×

×

RoleArn：RAM角色的ARN。

×

×

√

×

√

×

×

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

×

×

-

×

-

×

×

RoleName：RAM角色名称。

×

×

×

-

×

×

×

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

×

×

×

-

×

×

×

BearerToken：bearer token。

×

×

×

×

×

×

√

Policy：自定义权限策略。

×

×

-

×

-

×

×

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

×

×

-

×

-

×

×

OidcProviderArn：OIDC提供商ARN。

×

×

×

×

√

×

×

OidcTokenFilePath：OIDC Token文件路径。

×

×

×

×

√

×

×

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

×

×

-

×

×

×

×

CredentialsURI：凭证的URI。

×

×

×

×

×

√

×

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

×

×

-

×

-

×

×

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

×

×

-

-

-

-

×

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

×

×

-

-

-

-

×

初始化凭据客户端

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

重要

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

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

方式一：使用默认凭据链

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

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            // 不指定参数或者传入null
            var credential = new Aliyun.Credentials.Client();
            // var credential = new Aliyun.Credentials.Client(null);
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用默认凭证初始化Credentials Client。
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(null);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

方式二：使用AK

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

警告

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

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

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "access_key",                    
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),          
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET")   
            };
            var akCredential = new Aliyun.Credentials.Client(config);

            string accessKeyId = akCredential.GetAccessKeyId();
            string accessSecret = akCredential.GetAccessKeySecret();
            string credentialType = akCredential.GetType();
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用AK初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "access_key",
                // 从环境变量中获取AccessKey ID值。
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 从环境变量中获取AccessKey Secret值。
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET")
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

方式三：使用STS Token

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

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "sts", 
                // 从环境变量中获取AccessKey ID值。
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 从环境变量中获取AccessKey Secret值。
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), 
                // 从环境变量中获取的临时SecurityToken。
              	SecurityToken = Environment.GetEnvironmentVariable("<ALIBABA_CLOUD_SECURITY_TOKEN>")
            };
            var stsCredential = new Aliyun.Credentials.Client(config);

            string accessKeyId = stsCredential.GetAccessKeyId();
            string accessSecret = stsCredential.GetAccessKeySecret();
            string credentialType = stsCredential.GetType();
            string securityToken = stsCredential.GetSecurityToken();
        }
    }

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用STS Token初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "sts", 
                // 从环境变量中获取AccessKey ID值。
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 从环境变量中获取AccessKey Secret值。
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), 
                // 从环境变量中获取的临时SecurityToken。
              	SecurityToken = Environment.GetEnvironmentVariable("<ALIBABA_CLOUD_SECURITY_TOKEN>")
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

方式四：使用AK及RamRoleArn

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

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "ram_role_arn",                  
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
              	// 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
                RoleArn = "<RoleArn>",  
              	// 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
                RoleSessionName = "<RoleSessionName>", 
            };
            var arnCredential = new Aliyun.Credentials.Client(config);

            string accessKeyId = arnCredential.GetAccessKeyId();
            string accessSecret = arnCredential.GetAccessKeySecret();
            string credentialType = arnCredential.GetType();
            string securityToken = arnCredential.GetSecurityToken();
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用AK和RamRoleArn初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "ram_role_arn",
                // 设置为AccessKey ID值。
                AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 设置为AccessKey Secret值。
                AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
                RoleArn = "<RoleArn>",
                // 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
                RoleSessionName = "<RoleSessionName>",
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

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

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

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

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

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

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

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

说明 
using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            var config = new Config()
            {
                Type = "ecs_ram_role",
              	// 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName
                RoleName = "<RoleName>" 
            };
            // 选填，默认值：false。true：表示强制使用加固模式。false：系统将首先尝试在加固模式下获取凭据。如果失败，则会切换到普通模式（IMDSv1）进行尝试
            // config.DisableIMDSv1 = true;
            
            var ecsCredential = new Aliyun.Credentials.Client(config);

            string accessKeyId = ecsCredential.GetAccessKeyId();
            string accessSecret = ecsCredential.GetAccessKeySecret();
            string credentialType = ecsCredential.GetType();
            string securityToken = ecsCredential.GetSecurityToken();
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用Ecs实例绑定角色初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "ecs_ram_role",
              	// 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置RoleName
                RoleName = "<RoleName>"
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

方式六：使用OIDCRoleArn

为了避免影响云上资源的安全，同时又能让不可信的应用安全地获取所需的 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文件路径；

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "oidc_role_arn",
                // RAM角色名称ARN，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
                RoleArn = "<RoleArn>",
                // OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OidcProviderArn
                OIDCProviderArn = "<OidcProviderArn>",
                // OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OidcTokenFilePath
                OIDCTokenFilePath = "<OidcTokenFilePath>",
                // 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
                RoleSessionName = "<RoleSessionName>",
                // 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
                Policy = "<Policy>",
                RoleSessionExpiration = 3600
            };
            var ecsCredential = new Aliyun.Credentials.Client(config);
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用OIDCRoleArn初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "oidc_role_arn",
                // RAM角色名称ARN，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置RoleArn
                RoleArn = "<RoleArn>",
                // OIDC提供商ARN，可以通过环境变量ALIBABA_CLOUD_OIDC_PROVIDER_ARN设置OidcProviderArn
                OIDCProviderArn = "<OidcProviderArn>",
                // OIDC Token文件路径，可以通过环境变量ALIBABA_CLOUD_OIDC_TOKEN_FILE设置OidcTokenFilePath
                OIDCTokenFilePath = "<OidcTokenFilePath>",
                // 角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
                RoleSessionName = "<RoleSessionName>",
                // 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
                Policy = "<Policy>",
                RoleSessionExpiration = 3600
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

方式七：使用URI凭据

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

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "credentials_uri",
              	// 获取凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置CredentialsUri
                CredentialsURI = "<CredentialsURI>"     
            };
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用URI初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "credentials_uri",
              	// 获取凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置CredentialsUri
                CredentialsURI = "<CredentialsURI>" 
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config();
            // 配置云产品服务接入地址（endpoint）。
            ecsConfig.Endpoint = "ecs.cn-beijing.aliyuncs.com";
            // 使用Credentials配置凭证。
            ecsConfig.Credential = credentialClient;
            // 初始化ECS Client。
            AlibabaCloud.SDK.Ecs20140526.Client escClient = new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            // 初始化DescribeRegions请求。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeInstancesRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse response = escClient.DescribeRegionsWithOptions(describeInstancesRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

方式八：使用Bearer Token

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

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "bearer",     
              	// 填入您的Bearer Token
                BearerToken = "<BearerToken>"      
            };
            var bearerCredential = new Aliyun.Credentials.Client(config);

            string bearerToken = bearerCredential.GetBearerToken();
            string credentialType = bearerCredential.GetType();
        }
    }
}

接口调用示例

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

using System;
using Aliyun.Credentials.Models;
using Tea;
using Tea.Utils;

namespace credentials_demo
{
    public class Sample
    {
        static void Main(string[] args)
        {
            // 使用Bearer Token初始化Credentials Client。
            Aliyun.Credentials.Models.Config credentialsConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "bearer",
                // 填入您的Bearer Token
                BearerToken = "<BearerToken>"
            };
            Aliyun.Credentials.Client credentialClient = new Aliyun.Credentials.Client(credentialsConfig);

            AlibabaCloud.OpenApiClient.Models.Config cccConfig = new AlibabaCloud.OpenApiClient.Models.Config()
            {
                // 配置云产品服务接入地址（endpoint）。
                Endpoint = "ccc.cn-shanghai.aliyuncs.com",
                // 使用Credentials配置凭证。
                Credential = credentialClient
            };

            // 初始化CCC Client。
            AlibabaCloud.SDK.CCC20200701.Client cccClient = new AlibabaCloud.SDK.CCC20200701.Client(cccConfig);
            // 初始化GetInstance请求。
            AlibabaCloud.SDK.CCC20200701.Models.GetInstanceRequest getInstanceRequest = new AlibabaCloud.SDK.CCC20200701.Models.GetInstanceRequest
            {
                InstanceId = "ccc-test",
            };
            // 初始化运行时配置。
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            // 调用DescribeRegions接口并获得响应。
            AlibabaCloud.SDK.CCC20200701.Models.GetInstanceResponse response = cccClient.GetInstanceWithOptions(getInstanceRequest, runtime);
            Console.WriteLine(response.Body.ToMap());
        }
    }
}

默认凭据链

当您的程序开发环境和生产环境采用不同的凭据类型，常见做法是在代码中获取当前环境信息，编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链，您可以用同一套代码，通过程序之外的配置来控制不同环境下的凭据获取方式。当您在不传入参数的情况下，直接调用new Client(config)传入null，初始化凭据客户端时，阿里云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.使用config.json配置文件

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

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

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

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

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

4. 使用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，执行不同的异常处理逻辑：

  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，以验证是否使用了内部缓存，并在缓存过期后检验凭据是否会刷新。

using System;
using System.Threading.Tasks;
using Aliyun.Credentials.Models;
using AlibabaCloud.SDK.Ecs20140526;
using AlibabaCloud.OpenApiClient.Models;
using AlibabaCloud.TeaUtil.Models;

namespace Example
{
    /// <summary>
    /// Credential 类用于管理阿里云凭证实例，采用静态单例模式。
    /// </summary>
    public static class Credential
    {
        private static readonly Lazy<Aliyun.Credentials.Client> _instance = new(() =>
        {
            try
            {
                var config = new Aliyun.Credentials.Models.Config
                {
                    Type = "ram_role_arn",
                    AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                    AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                    RoleArn = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ROLE_ARN"),
                    RoleSessionName = "RamRoleArnTest",
                    RoleSessionExpiration = 3600
                };

                return new Aliyun.Credentials.Client(config);
            }
            catch (Exception ex)
            {
                throw new InvalidOperationException("Credential initialization failed: " + ex.Message, ex);
            }
        });

        public static Aliyun.Credentials.Client Instance => _instance.Value;
    }

    /// <summary>
    /// EcsClient 类用于管理 ECS 客户端实例，采用静态单例模式。
    /// 必须通过 Initialize 设置 endpoint 和 credential。
    /// </summary>
    public static class EcsClient
    {
        private static string _endpoint = string.Empty; // 显式初始化，不能为 null
        private static Aliyun.Credentials.Client _credential = null!; // 显式初始化，不能为 null

        private static readonly Lazy<AlibabaCloud.SDK.Ecs20140526.Client> _instance = new(() =>
        {
            if (string.IsNullOrEmpty(_endpoint))
            {
                throw new InvalidOperationException("Endpoint must be set before initializing the ECS client.");
            }

            if (_credential == null)
            {
                throw new InvalidOperationException("Credential must be set before initializing the ECS client.");
            }

            try
            {
                var ecsConfig = new AlibabaCloud.OpenApiClient.Models.Config
                {
                    Endpoint = _endpoint,
                    Credential = _credential
                };

                return new AlibabaCloud.SDK.Ecs20140526.Client(ecsConfig);
            }
            catch (Exception ex)
            {
                throw new InvalidOperationException("ECS client initialization failed: " + ex.Message, ex);
            }
        });

        public static void Initialize(string endpoint, Aliyun.Credentials.Client credential)
        {
            if (string.IsNullOrEmpty(endpoint))
            {
                throw new ArgumentException("Endpoint cannot be null or empty.", nameof(endpoint));
            }

            if (credential == null)
            {
                throw new ArgumentNullException(nameof(credential), "Credential cannot be null.");
            }

            _endpoint = endpoint;
            _credential = credential;
        }

        public static AlibabaCloud.SDK.Ecs20140526.Client Instance => _instance.Value;
    }

    public class Program
    {
        public static async Task Main(string[] args)
        {
            // 初始化 EcsClient
            EcsClient.Initialize("ecs.cn-hangzhou.aliyuncs.com", Credential.Instance);

            Action task = () =>
            {
                try
                {
                    var credential = Credential.Instance.GetCredential();
                    Console.WriteLine(DateTime.Now);
                    Console.WriteLine($"AK ID: {credential.AccessKeyId}, AK Secret: {credential.AccessKeySecret}, STS Token: {credential.SecurityToken}");

                    var ecsClient = EcsClient.Instance;
                    var request = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
                    var runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();

                    var response = ecsClient.DescribeRegionsWithOptions(request, runtime);
                    Console.WriteLine($"Invoke result: {response.StatusCode}");
                }
                catch (Exception ex)
                {
                    Console.WriteLine($"ECS client execution failed: {ex.Message}");
                }
            };

            // 立即执行一次
            task();

            // 并发启动异步任务
            var tasks = new[]
            {
                ScheduleTaskAsync(task, 600),
                ScheduleTaskAsync(task, 4200),
                ScheduleTaskAsync(task, 4300)
            };

            await Task.WhenAll(tasks);

            Console.WriteLine("All tasks completed.");
        }

        private static async Task ScheduleTaskAsync(Action task, int delaySeconds)
        {
            await Task.Delay(TimeSpan.FromSeconds(delaySeconds));
            task();
        }
    }
}

image

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

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

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

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

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

相关文档

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