當您通過阿里雲SDK調用OpenAPI進行資源操作時,必須正確配置憑證資訊。阿里雲的Credentials工具提供了一套強大的功能,使您能夠輕鬆地擷取和管理這些訪問憑證。無論是利用預設憑證,AccessKey(AK),還是Security Token Service(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。
自建網關類產品的自研SDK無法使用。
安裝Credentials工具
通過 .NET CLI 工具安裝。
dotnet add package Aliyun.Credentials
通過 NuGet 封裝管理員安裝。
在
方案總管面板
中右擊您的專案選擇管理 NuGet 程式包
菜單。通過開啟的
NuGet 管理面板
中單擊瀏覽
選項卡輸入Aliyun.Credentials
。下方列表中選擇
Authors
為Alibaba Cloud
由官方發布的包單擊安裝即可。
建議使用最新發行的Credentials工具版本。
請查看ChangeLog.txt擷取所有發行的版本列表。
初始化憑據用戶端
Credentials工具支援多種方式初始化憑據用戶端。您可通過設定Type
指定類型。
使用預設憑據鏈
當您在初始化憑據用戶端不傳入任何參數時,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",
// <ALIBABA_CLOUD_ACCESS_KEY_ID>需替換為返回資料中擷取的臨時AccessKeyId。
AccessKeyId = "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
// <ALIBABA_CLOUD_ACCESS_KEY_SECRET>需替換為返回資料中擷取的臨時AccessKeySecret。
AccessKeySecret = "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
// <ALIBABA_CLOUD_SECURITY_TOKEN>需替換為返回資料中擷取的臨時SecurityToken。
SecurityToken = "<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
RoleArn = "<RoleArn>",
// 角色會話名稱
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角色
該方式底層實現是STS Token。Credentials工具會自動擷取ECS執行個體綁定的RAM角色,調用ECS的中繼資料服務(Meta Data Server)換取STS Token,完成憑據用戶端初始化。ECI執行個體,Container Service for Kubernetes的Worker節點均支援綁定執行個體RAM角色。
using Aliyun.Credentials.Models;
namespace credentials_demo
{
class Program
{
static void Main(string[] args)
{
Config config = new Config()
{
Type = "ecs_ram_role",
// 選填,該ECS角色的角色名稱,不填會自動擷取,但是建議加上以減少請求次數
RoleName = "<RoleName>"
};
var ecsCredential = new Aliyun.Credentials.Client(config);
string accessKeyId = ecsCredential.GetAccessKeyId();
string accessSecret = ecsCredential.GetAccessKeySecret();
string credentialType = ecsCredential.GetType();
string securityToken = ecsCredential.GetSecurityToken();
}
}
}
介面調用方法
使用Bearer Token
目前只有Cloud Call CenterCCC這款產品支援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工具會優先使用它們作為預設憑據。
2. 使用設定檔
若不存在優先順序更高的憑據資訊,Credentials工具優先在如下位置尋找檔案是否存在。
Linux系統:~/.alibabacloud/credentials
Windows系統:C:\Users\USER_NAME\.alibabacloud\credentials
您也可通過指定 ALIBABA_CLOUD_CREDENTIALS_FILE 指定設定檔路徑。如果檔案存在,程式將會使用設定檔中default 指定的憑據資訊初始化憑據用戶端,當然您也可以通過設定 ALIBABA_CLOUD_PROFILE 環境變數修改預設讀取的憑據資訊。
[default]
type = access_key
access_key_id = foo
access_key_secret = bar
3. 使用ECS執行個體RAM角色
若不存在優先順序更高的憑據資訊,Credentials工具會在環境變數中擷取ALIBABA_CLOUD_ECS_METADATA(ECS執行個體RAM角色名稱),若存在,程式將會通過ECS的中繼資料服務(Meta Data Server)擷取ECS執行個體RAM角色的STS Token作為預設憑據資訊。
如何保護憑據資訊
憑據資訊泄露導致系統被攻擊是雲上業務普遍存在的一種安全問題,您可通過如下方案避免在代碼中暴露明文憑據資訊,降低憑據泄露的風險。
推薦使用ECS執行個體RAM角色或者使用STS方式。
推薦使用預設憑據鏈,使用環境變數或者設定檔記錄憑據資訊。
如使用顯示初始化方案初始化憑據用戶端,推薦使用系統屬性及環境變數記錄憑據資訊,通過
Environment.GetEnvironmentVariable
擷取。
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();
}
}
}
如何切換憑據
當您想要在程式中使用不同的訪問憑據調用不同OpenAPI時,可以通過如下方式。
使用多個憑據用戶端
通過初始化多個憑據用戶端,傳入到不同的介面請求用戶端。
using Aliyun.Credentials.Models;
namespace credentials_demo
{
class Program
{
static void Main(string[] args)
{
Config config1 = new Config()
{
Type = "access_key",
AccessKeyId = "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
AccessKeySecret = "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
};
var akCredential = new Aliyun.Credentials.Client(config1);
Config config2 = new Config()
{
Type = "access_key",
AccessKeyId = "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
AccessKeySecret = "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
};
var akCredential = new Aliyun.Credentials.Client(config2);
}
}
}
使用AuthUtils
當我們初始化憑據用戶端採用設定檔記錄憑據資訊時,可以使用auth_util.client_type
切換到不同的憑據配置上。
[default]
enable=true
type=access_key
access_key_id=<ALIBABA_CLOUD_ACCESS_KEY_ID>
access_key_secret=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
[client1]
enable=true
type=sts
access_key_id=<ACCESS_ALIBABA_CLOUD_ACCESS_KEY_IDKEY_ID>
access_key_secret=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>
security_token=<security_token>
[client2]
enable=true
type=ecs_ram_role
role_name=<ecs_ram_role_name>
範例程式碼如下。
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();
}
}
}