如何进行Credentials配置(.NETSDK)_阿里云SDK-阿里云帮助中心

本文介绍如何通过阿里云提供的Credentials工具，配置访问接口时的身份验证。

背景信息

AccessKey（简称AK）是阿里云提供给阿里云用户的访问密钥，用于访问阿里云OpenAPI时的身份验证。AccessKey包括AccessKey ID和AccessKey Secret，需妥善保管。AK如果泄露，会威胁该账号下所有资源的安全。访问阿里云OpenAPI时，如果在代码中硬编码明文AK，容易因代码仓库权限管理不当造成AK泄露。

Alibaba Cloud Credentials是阿里云为阿里云开发者用户提供的身份凭证管理工具。配置了Credentials默认凭据链后，访问阿里云OpenAPI时，您无需在代码中硬编码明文AK，可有效保证您账号下云资源的安全。

前提条件

已获取RAM用户账号的AccessKey ID和AccessKey Secret。相关操作，请参见查看RAM用户的AccessKey信息。
重要
- 阿里云账号（即主账号）的AccessKey泄露会威胁该账号下所有资源的安全。为保证账号安全，强烈建议您为RAM用户创建AccessKey，非必要情况下请勿为阿里云主账号创建AccessKey。
- RAM用户的AccessKey Secret只能在创建AccessKey时显示，创建完成后不支持查看。请在创建好AccessKey后，及时并妥善保存AccessKey Secret。
已安装阿里云SDK Credentials工具。

安装方式（推荐使用Credentials最新版本）：

通过.NET CLI工具安装：
```
dotnet add package Aliyun.Credentials
```
通过NuGet程序包管理器来安装：
定位到解决方案资源管理器面板，选择管理NuGet程序，在打开的NuGet管理面板中点击浏览选项卡，输入Aliyun.Credentials，在下方列表中选择Authors为Alibaba Cloud，点击安装。

配置方案

您可以选用以下任意一种方案进行配置。

重要

使用配置文件的方案时，请确保您系统中不存在环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。否则，配置文件将不生效。

配置环境变量

阿里云SDK支持通过定义ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET环境变量来创建默认的访问凭证。调用接口时，程序直接访问凭证，读取您的访问密钥（即AccessKey）并自动完成鉴权。

配置方法

配置环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。

Linux和macOS系统配置方法
执行以下命令：
```
export ALIBABA_CLOUD_ACCESS_KEY_ID=<access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<access_key_secret>
```
<access_key_id>需替换为已准备好的AccessKey ID，<access_key_secret>替换为AccessKey Secret。
Windows系统配置方法
1. 新建环境变量文件，添加环境变量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET，并写入已准备好的AccessKey ID和AccessKey Secret。
2. 重启Windows系统。

接口调用方法

using System;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        public static void Main(string[] args)
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential=new Aliyun.Credentials.Client(null)
            };
            // 访问的域名
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            AlibabaCloud.SDK.Ecs20140526.Client client = new AlibabaCloud.SDK.Ecs20140526.Client(config);
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeRegionsRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse resp = client.DescribeRegionsWithOptions(describeRegionsRequest, runtime);
            AlibabaCloud.TeaConsole.Client.Log(AlibabaCloud.TeaUtil.Common.ToJSONString(resp));
        }

    }
}

配置文件

通过配置credentials文件创建默认的访问凭证，调用接口时，程序直接访问凭证，读取您的访问密钥（即AccessKey）并自动完成鉴权。

配置方法

创建credentials文件。
重要
credentials文件需要严格按照ini格式来编写，键值对之间不可存在空格。
- Linux/macOS系统
  执行以下命令（默认安装路径为~/.alibabacloud/credentials.ini）：
```
sudo vi ~/.alibabacloud/credentials.ini
```
- Windows系统
  新建文件，并将文件存放在C:\Users\<user_name>\.alibabacloud\credentials.ini。
说明
如果您想将credentials文件安装到其他指定目录，您需要先配置环境变量ALIBABA_CLOUD_CREDENTIALS_FILE。以Linux和macOS系统为例，执行命令export ALIBABA_CLOUD_CREDENTIALS_FILE=~/<example_path>/credentials。

配置credentials文件。

Credentials工具支持以下几类鉴权方式：

通过RAM角色ARN配置访问凭证

适用于希望通过阿里云SDK自动更新STS凭证，避免临时凭证失效后还需手动更新凭证。

阿里云STS（Security Token Service）是阿里云提供的一种临时访问权限管理服务，仅支持通过RAM用户使用，不支持通过阿里云主账号使用。

; 凭证配置名称。
[default]
; 鉴权方式为ram_role_arn。
type=ram_role_arn
; 选填，为STS凭证指定权限策略，进一步限制STS Token的权限，请参见https://help.aliyun.com/document_detail/371864.html。
policy=<test_policy>
; 已准备好的AccessKeyID。
access_key_id=<access_key_id>
; 已准备好的AccessKeySecret。
access_key_secret=<access_key_secret>
; 您阿里云RAM用户的角色Arn，请参见https://help.aliyun.com/document_detail/39744.html。
role_arn=<ram_role_arn>
; 自定义的角色会话名称，用于日志审计时识别对应的操作者。通常设置为调用阿里云访问控制AssumeRole接口时使用的用户身份。
role_session_name=<session_name>

通过ECS实例RAM角色配置访问凭证
适用于希望免创建AccessKey、通过为阿里云ECS实例授予RAM角色，来调用云产品接口。
使用该鉴权方式前，您需要先为ECS实例授予RAM角色。详细信息，请参见授予实例RAM角色。
运行以下示例代码，启用ECS实例RAM角色鉴权方式。
```
; 默认配置。
[default]
; 鉴权方式为ecs_ram_role。
type=ecs_ram_role
; ECS实例的RAM角色名称。
role_name=<ecs_ram_role_name>
```

通过RSA密钥对配置访问凭证

仅适用于支持RSA密钥对鉴权的接口。

; 默认配置。
[default]
; 鉴权方式为rsa_key_pair。
type=rsa_key_pair
; Public Key ID
public_key_id=<public_key_id>
; Private Key 文件
private_key_file=<private_key_file

通过credentials文件配置访问凭证

仅需配置一次AccessKey信息，适用于希望快速接入Credentials工具的用户。

; 默认配置。
[default]
; 鉴权方式为access_key。
type=access_key
; 已准备好的AccessKeyID。
access_key_id=<access_key_id>
; 已准备好的AccessKeySecret。
access_key_secret=<access_key_secret>

需要不定期切换凭证类型
如果您配置了多个凭证类型，需要不定期启用其中某个凭证，您需要先变更ALIBABA_CLOUD_PROFILE环境变量，将环境变量的值设置为待启用凭证的配置名称。
```
export  ALIBABA_CLOUD_PROFILE=client1
```
运行以下示例代码，启用指定的凭证：

[default]
type=access_key
access_key_id=<access_key_id>
access_key_secret=<access_key_secret>

[client1]
type=ecs_ram_role
role_name=<ecs_ram_role_name>

[client2]
type=ram_role_arn
policy=<policy_name>
access_key_id=<access_key_id>
access_key_secret=<access_key_secret>
role_arn=<ram_role_arn>
role_session_name=<role_session_name>

[client3]
type=rsa_key_pair
public_key_id=<public_key_id>
private_key_file=<file_name>

需要同时启用多个凭证类型

如果您配置了多个凭证类型，需要同时启用多个凭证类型，可以通过设置Credentials包中AuthUtils类ClientType属性为待启用凭证的配置名称。

[default]
enable=true
type=access_key
access_key_id=<access_key_id>
access_key_secret=<access_key_secret>

[client1]
enable=true
type=ecs_ram_role
role_name=<ecs_ram_role_name>

[client2]
enable=true
type=ram_role_arn
policy=<policy_name>
access_key_id=<access_key_id>
access_key_secret=<access_key_secret>
role_arn=<ram_role_arn>
role_session_name=<role_session_name>

// 若不定义Credentials包中AuthUtils类ClientType属性，则默认启用default配置
var bearerCredential = new Aliyun.Credentials.Client(null);
// 若需默认启用client1配置，则配置ClientType值为client1
Aliyun.Credentials.Utils.AuthUtils.ClientType = "client1";
var bearerCredential = new Aliyun.Credentials.Client(null);
// 同理默认启用client2配置，则配置ClientType值为client2
Aliyun.Credentials.Utils.AuthUtils.ClientType = "client2";
var bearerCredential = new Aliyun.Credentials.Client(null);

接口调用方法

调用单个云产品的接口需要云产品依赖。本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS .NET SDK。

using System;


namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential = new Aliyun.Credentials.Client(null)
            };
            /* 若需默认启用client1配置，则设置ClientType值为client1，若不设置，则默认为default。
            Aliyun.Credentials.Utils.AuthUtils.ClientType = "client1";
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential = new Aliyun.Credentials.Client(null)
            };
            */
            // 访问的域名
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            AlibabaCloud.SDK.Ecs20140526.Client client = new AlibabaCloud.SDK.Ecs20140526.Client(config);
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeRegionsRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse resp = client.DescribeRegionsWithOptions(describeRegionsRequest, runtime);
            AlibabaCloud.TeaConsole.Client.Log(AlibabaCloud.TeaUtil.Common.ToJSONString(resp));
        }
    }
}

配置访问令牌（Token）

本章节介绍SDK支持的三种令牌鉴权能力：

STS Token：通过调用AssumeRole接口扮演角色获取令牌凭证并调用openapi，临时凭证有过期时间，需要用户更新凭证。
RamRoleArn：通过您已获取的AccessKey，SDK将自动调用AssumeRole获取STS Token并定期刷新凭证。
Bearer Token：使用OAuth协议进行用户认证和应用授权，当前仅有极少数产品支持，例如云呼叫中心，您可以前往OpenAPI门户查看。

STS Token

有权限的RAM用户可以使用自己的访问密钥调用AssumeRole接口，以获取某个RAM角色的STS Token，实现通过Credentials工具读取临时安全令牌（STS Token），访问云产品接口。

STS Token具有时效性，到期后会自动失效。相比于AK硬编码方式访问接口，使用STS Token可有效减少因长期访问AK导致AK泄露的风险。

本配置方案仅适用于支持阿里云STS的云服务。

配置方法

为该RAM用户授予AliyunRAMFullAccess权限、AliyunSTSAssumeRoleAccess权限。
详细操作，请参见为RAM用户授权。

调用AssumeRole接口，获取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"
  }
}

配置访问凭证。

运行以下代码示例，传入步骤2中返回的SecurityToken、AccessKeyId、AccessKeySecret值。

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "sts",                             // 凭证类型。
                AccessKeyId = "<access_key_id>",          // 设置为调用AssumeRole接口时返回的AccessKeyId值。
                AccessKeySecret = "<access_key_secret>",  // 设置为调用AssumeRole接口时返回的AccessKeySecret值。
                SecurityToken = "<security_token>"        // 临时的STS Token，设置为调用AssumeRole接口时返回的SecurityToken值。
            };
            var stsCredential = new Aliyun.Credentials.Client(config);

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

重要

由于STS Token仅为临时凭证，后续再次通过STS Token方式访问云产品SDK代码时，请调用AssumeRole接口获取新的临时身份凭证。

接口调用方法

调用单个云产品的接口需要云产品依赖。本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS .NET SDK。

using System;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {

        public static void Main(string[] args)
        {

            Aliyun.Credentials.Models.Config creConfig = new Aliyun.Credentials.Models.Config()
            {
                Type = "sts",                             // 凭证类型。
                AccessKeyId = "<access_key_id>",          // 设置为调用AssumeRole接口时返回的AccessKeyId值。
                AccessKeySecret = "<access_key_secret>",  // 设置为调用AssumeRole接口时返回的AccessKeySecret值。
                SecurityToken = "<security_token>"        // 临时的STS Token，设置为调用AssumeRole接口时返回的SecurityToken值。
            };
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential = new Aliyun.Credentials.Client(creConfig)
            };
            // 访问的域名
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            AlibabaCloud.SDK.Ecs20140526.Client client = new AlibabaCloud.SDK.Ecs20140526.Client(config);
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeRegionsRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse resp = client.DescribeRegionsWithOptions(describeRegionsRequest, runtime);
            AlibabaCloud.TeaConsole.Client.Log(AlibabaCloud.TeaUtil.Common.ToJSONString(resp));
        }
    }
}

RamRoleArn

通过指定具体的RAM角色ARN，实现Credentials凭证自动更新STS Token，避免使用AK硬编码的方式访问云产品接口。

本配置方案仅适用于支持阿里云STS的云服务。

配置方法

为该RAM用户授予AliyunRAMFullAccess权限、AliyunSTSAssumeRoleAccess权限。
详细操作，请参见为RAM用户授权。

配置访问凭证。

运行以下代码示例，传入AccessKeyId、AccessKeySecret、Arn等值。

public class Sample
{

    public static void Main(string[] args)
    {

        Aliyun.Credentials.Models.Config creConfig = new Aliyun.Credentials.Models.Config()
        {
            // 凭证类型。
            Type = "ram_role_arn",
            // 您的 AccessKeyId。
            AccessKeyId = "<access_key_id>",
            // 您的 AccessKeySecret。
            AccessKeySecret = "<access_key_secret>",
            // 阿里云RAM用户的角色ARN，格式为：acs:ram::userId:role/roleName。
            RoleArn = "<role_arn>",
            // 自定义的角色会话名称。
            RoleSessionName = "<role_session_name>"
        };
        Aliyun.Credentials.Client client = new Aliyun.Credentials.Client(creConfig);
    }
}

接口调用方法

调用单个云产品的接口需要云产品依赖。本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS .NET SDK。

using System;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {

        public static void Main(string[] args)
        {

            Aliyun.Credentials.Models.Config creConfig = new Aliyun.Credentials.Models.Config()
            {
                // 凭证类型。
                Type = "ram_role_arn",
                // 您的 AccessKeyId。
                AccessKeyId = "<access_key_id>",
                // 您的 AccessKeySecret。
                AccessKeySecret = "<access_key_secret>",
                // 阿里云RAM用户的角色ARN，格式为：acs:ram::userId:role/roleName。
                RoleArn = "<role_arn>",
                // 自定义的角色会话名称。
                RoleSessionName = "<role_session_name>"
            };
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential = new Aliyun.Credentials.Client(creConfig)
            };
            // 访问的域名
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            AlibabaCloud.SDK.Ecs20140526.Client client = new AlibabaCloud.SDK.Ecs20140526.Client(config);
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeRegionsRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse resp = client.DescribeRegionsWithOptions(describeRegionsRequest, runtime);
            AlibabaCloud.TeaConsole.Client.Log(AlibabaCloud.TeaUtil.Common.ToJSONString(resp));
        }
    }

Bearer Token

说明

Bearer Token并非通用鉴权Token，仅有部分产品接口支持，例如云呼叫中心。

通过指定的Bearer Token，实现免创建AK和Token的方式访问云产品接口。

配置方法

运行以下示例代码，配置访问凭证。

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "bearer",                // 凭证类型。
                BearerToken = "<bearer_token>"  // 服务器端自动生成的Bearer Token，带有效期。
            };
            var bearerCredential = new Aliyun.Credentials.Client(config);

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

接口调用方法

调用单个云产品的接口需要云产品依赖。本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS Go SDK。

using System;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {

        public static void Main(string[] args)
        {

            Aliyun.Credentials.Models.Config creConfig = new Aliyun.Credentials.Models.Config()
            {
                Type = "bearer",                // 凭证类型。
                BearerToken = "<bearer_token>"  // 服务器端自动生成的Bearer Token，带有效期。
            };
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential = new Aliyun.Credentials.Client(creConfig)
            };
            // 访问的域名
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            AlibabaCloud.SDK.Ecs20140526.Client client = new AlibabaCloud.SDK.Ecs20140526.Client(config);
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeRegionsRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse resp = client.DescribeRegionsWithOptions(describeRegionsRequest, runtime);
            AlibabaCloud.TeaConsole.Client.Log(AlibabaCloud.TeaUtil.Common.ToJSONString(resp));
        }
    }

免创建AK和Token

通过EcsRamRole配置访问凭证

指定具体的ECS角色名称，通过免手动创建AK和Token的方式配置访问凭证。

本方案仅适用于支持阿里云RAM的云服务。

配置方法

为ECS实例授予RAM角色。详细信息，请参见授予实例RAM角色。

运行以下示例代码，配置访问凭证。

using Aliyun.Credentials.Models;

namespace credentials_demo
{
    class Program
    {
        static void Main(string[] args)
        {
            Config config = new Config()
            {
                Type = "ecs_ram_role",    // 凭证类型。
                RoleName = "<role_name>"  // 选填，不填则自动获取ECS的实例角色名称。建议设置，可以减少不必要的请求次数。
            };
            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 .NET SDK。

using System;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {

        public static void Main(string[] args)
        {

            Aliyun.Credentials.Models.Config creConfig = new Aliyun.Credentials.Models.Config()
            {
                Type = "ecs_ram_role",    // 凭证类型。
                RoleName = "<role_name>"  // 选填，不填则自动获取ECS的实例角色名称。建议设置，可以减少不必要的请求次数。
            };
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config
            {
                Credential = new Aliyun.Credentials.Client(creConfig)
            };
            // 访问的域名
            config.Endpoint = "ecs-cn-hangzhou.aliyuncs.com";
            AlibabaCloud.SDK.Ecs20140526.Client client = new AlibabaCloud.SDK.Ecs20140526.Client(config);
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest describeRegionsRequest = new AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsRequest();
            AlibabaCloud.TeaUtil.Models.RuntimeOptions runtime = new AlibabaCloud.TeaUtil.Models.RuntimeOptions();
            AlibabaCloud.SDK.Ecs20140526.Models.DescribeRegionsResponse resp = client.DescribeRegionsWithOptions(describeRegionsRequest, runtime);
            AlibabaCloud.TeaConsole.Client.Log(AlibabaCloud.TeaUtil.Common.ToJSONString(resp));
        }
    }