管理访问凭证
本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。
当您通过阿里云SDK调用OpenAPI进行资源操作时，必须正确配置凭证信息。阿里云的Credentials工具提供了一套强大的功能，使您能够轻松地获取和管理这些访问凭证。无论是利用默认凭证，AccessKey（AK），还是安全令牌服务（STS）令牌等，Credentials工具都能为您提供相应支持。此外，本文档将详细阐述如何根据优先级使用默认凭证。您将深入理解如何在阿里云SDK中配置和维护凭证，从而确保您对云资源的操作既有效率又具有高度安全性。
背景信息
凭据是指用户证明其身份的一组信息。用户在系统中进行登录时，需要提供正确的凭据才能验证身份。常见的凭据类型有：
阿里云主账号和RAM用户的永久凭据 AccessKey（简称AK）是由AccessKey ID和AccessKey Secret组成的密钥对。
阿里云RAM角色的STS临时访问Token，简称STS Token。它是可以自定义时效和访问权限的临时身份凭据，详情请参见什么是STS。
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 程序包管理器安装。
在
解决方案资源管理器面板中右击您的项目选择管理 NuGet 程序包菜单。通过打开的
NuGet 管理面板中单击浏览选项卡输入Aliyun.Credentials。下方列表中选择
Authors为Alibaba Cloud由官方发布的包单击安装即可。
使用最新发布Credentials依赖包，确保所有凭证支持。
请查看ChangeLog.txt获取所有已发布的版本列表。
初始化凭据客户端
Credentials工具支持多种方式初始化凭据客户端。您可通过设置Type指定类型。
在项目中使用明文AccessKey，容易因代码仓库权限管理不当造成AccessKey泄露，会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式获取AccessKey。
方式一：使用默认凭据链
当您在初始化凭据客户端不传入任何参数时，Credentials工具会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。
using Aliyun.Credentials.Models;
namespace credentials_demo
{
class Program
{
static void Main(string[] args)
{
// 不指定参数
Config config = new Config();
var credential = new Aliyun.Credentials.Client(config);
}
}
}接口调用方法
方式二：使用AK
阿里云账号、RAM用户可生成调用OpenAPI的密钥对AK。如何获取AK请参见文档创建AccessKey。您可使用AK初始化凭据客户端。
阿里云主账号拥有资源的全部权限，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();
}
}
}接口调用方法
方式三：使用STS Token
以一个RAM用户的身份调用STS服务的AssumeRole接口，设置Token的最大过期时间，即可换取到临时凭据STS Token。以下示例演示如何使用STS Token初始化凭据客户端（不包含如何获取到STS Token的过程）。
{
"RequestId": "EA7A3526-F7DB-54A5-8300-9B742CFAA5EA",
"AssumedRoleUser": {
"Arn": "acs:ram::125499367423****:role/STStokenTestRole/STSsessionName",
"AssumedRoleId": "35219123109646****:STSsessionName"
},
"Credentials": {
"SecurityToken": "exampleToken",
"AccessKeyId": "STS.exampleAccessKeyID",
"AccessKeySecret": "exampleAccessKeySecret",
"Expiration": "2023-03-26T05:26:06Z"
}
}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();
}
}接口调用方法
方式四：使用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实例RAM角色
ECS和ECI实例均支持绑定实例RAM角色，当在实例中使用Credentials工具时，将自动获取实例绑定的RAM角色，并通过访问元数据服务获取RAM角色的STS Token，以完成凭据客户端的初始化。
实例元数据服务器支持加固模式和普通模式两种访问方式，Credentials工具默认使用加固模式（IMDSv2）获取访问凭据。若使用加固模式时发生异常，您可以通过设置DisableIMDSv1来执行不同的异常处理逻辑：
当值为
false（默认值）时，会使用普通模式继续获取访问凭据。当值为
true时，表示只能使用加固模式获取访问凭据，会抛出异常。
服务端是否支持IMDSv2，取决于您在服务器的配置。
关于ECS实例元数据的介绍，请参见实例元数据。
如何为ECS和ECI实例授予RAM角色，具体操作请参见创建ECS实例RAM角色并授予给ECS和为ECI实例授予实例RAM角色。
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>"
};
// 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();
}
}
}接口调用方法
方式六：使用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文件路径；
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);
}
}
}接口调用方法
方式七：使用URI凭据
该方案底层实现是STS Token。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>"
};
}
}
}接口调用方法
方式八：使用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();
}
}
}接口调用方法
默认凭据链
当您的程序开发环境和生产环境采用不同的凭据类型，常见做法是在代码中获取当前环境信息，编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链，您可以用同一套代码，通过程序之外的配置来控制不同环境下的凭据获取方式。当您在不传入参数的情况下，直接调用new Client(config)传入null，初始化凭据客户端时，阿里云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时，可以通过如下方式。
使用多个凭据客户端
通过初始化多个凭据客户端，传入到不同的接口请求客户端。
using Aliyun.Credentials.Models;
namespace credentials_demo
{
class Program
{
static void Main(string[] args)
{
Config config1 = 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(config1);
Config config2 = new Config()
{
Type = "sts",
AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
SecurityToken = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_SECURITY_TOKEN")
};
var akCredential = new Aliyun.Credentials.Client(config2);
}
}
}使用AuthUtils
当我们初始化凭据客户端采用配置文件记录凭据信息时，可以使用auth_util.client_type切换到不同的凭据配置上。示例代码如下。
using Aliyun.Credentials.Models;
using Aliyun.Credentials.Utils;
namespace credentials_demo
{
class Program
{
static void Main(string[] args)
{
// 若不配置AuthUtils类clientType属性，则默认使用default。
Config config = new Config();
// 切换到client1凭据上
AuthUtils.ClientType = "client1";
Config config = new Config();
// 切换到client2凭据上
AuthUtils.ClientType = "client2";
Config config = new Config();
}
}
}