使用C# SDK發起OSS請求,您需要配置訪問憑證。阿里雲服務會通過訪問憑證驗證您的身份資訊和存取權限。您可以根據使用情境對認證和授權的要求,選擇不同的方式提供憑證。
注意事項
如果您希望擷取關於OSS支援的Region與Endpoint的對應關係,請參見地區和Endpoint。
如果您希望建立RAM使用者的AccessKey,請參見建立AccessKey。
憑證提供者選型參考
OSS支援多種方式初始化憑證提供者,您可以根據使用情境對認證和授權的要求,選擇對應的方式初始化憑證提供者。
憑證提供者初始化方式 | 適用情境 | 是否需要提供前置的AK或STS Token | 底層實現基於的憑證 | 憑證有效期間 | 憑證輪轉或重新整理方式 |
部署運行在安全、穩定且不易受外部攻擊的環境的應用程式,無需頻繁輪轉憑證就可以長期訪問雲端服務 | 是 | AK | 長期 | 手動輪轉 | |
部署運行在不可信的環境的應用程式,希望能控制訪問的有效期間、許可權 | 是 | STS Token | 臨時 | 手動重新整理 | |
需要授權訪問雲端服務,例如跨阿里雲帳號訪問雲端服務的應用程式 | 是 | STS Token | 臨時 | 自動重新整理 | |
部署運行在阿里雲的ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中的應用程式 | 否 | STS Token | 臨時 | 自動重新整理 | |
部署運行在阿里雲的Container ServiceKubernetes版的Worker節點中的不可信應用程式 | 否 | STS Token | 臨時 | 自動重新整理 | |
需要通過外部系統擷取訪問憑證的應用程式 | 否 | STS Token | 臨時 | 自動重新整理 | |
如果以上憑證配置方式都不滿足要求時,您可以自訂擷取憑證的方式 | 自訂 | 自訂 | 自訂 | 自訂 |
常用配置樣本
使用RAM使用者的AK
如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中,需要長期訪問您的OSS,且不能頻繁輪轉憑證時,您可以使用阿里雲主帳號或RAM使用者的AK(Access Key ID、Access Key Secret)初始化憑證提供者。需要注意的是,該方式需要您手動維護一個AK,存在安全性風險和維護複雜度增加的風險。如何擷取AK,請參見CreateAccessKey - 建立主帳號或RAM使用者存取金鑰。
環境變數
阿里雲帳號擁有資源的全部許可權,AK一旦泄露,會給系統帶來巨大風險,不建議使用。推薦使用最小化授權的RAM使用者的AK。
使用AK設定環境變數。
Mac OS X/Linux/Unix
export ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID> export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>Windows
set ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID> set ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>使用環境變數來傳遞憑證資訊。
using Aliyun.OSS; using Aliyun.OSS.Common; using Aliyun.OSS.Common.Authentication; // 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。 var accessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"); var accessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"); var credentialsProvider = new DefaultCredentialsProvider(new DefaultCredentials(accessKeyId, accessKeySecret, "")); // 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。 const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。 const string region = "cn-hangzhou"; var conf = new ClientConfiguration(); var client = new OssClient(endpoint, credentialsProvider, conf); client.SetRegion(region);
靜態憑證
以下範例程式碼展示了如何對訪問憑據直接進行寫入程式碼,顯式設定要使用的存取金鑰。
請勿將訪問憑據嵌入到生產環境的應用程式中,此方法僅用於測試目的。
using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET。
var accessKeyId = "LTAI5tQQx1DWEYK7********" ;
var accessKeySecret = "s5LkMqKmmKbt3zjs7MNJTj********" ;
var credentialsProvider = new DefaultCredentialsProvider(new DefaultCredentials(accessKeyId, accessKeySecret, ""));
// 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region); 使用STS臨時訪問憑證
如果您的應用程式需要臨時訪問OSS,您可以使用通過STS服務擷取的臨時身份憑證(Access Key ID、Access Key Secret和Security Token)初始化憑證提供者。需要注意的是,該方式需要您手動維護一個STS Token,存在安全性風險和維護複雜度增加的風險。此外,如果您需要多次臨時訪問OSS,您需要手動重新整理STS Token。
如果您希望通過OpenAPI的方式簡單快速擷取到STS臨時訪問憑證,請參見AssumeRole - 擷取扮演角色的臨時身份憑證。
如果您希望通過SDK的方式擷取STS臨時訪問憑證,請參見使用STS臨時訪問憑證訪問OSS。
請注意,STS Token在產生的時候需要指定到期時間,到期後自動失效不能再使用。
如果您希望擷取關於STS服務的存取點列表,請參見服務存取點。
環境變數
使用臨時身份憑證設定環境變數。
Mac OS X/Linux/Unix
export ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID> export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET> export ALIBABA_CLOUD_SECURITY_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>Windows
set OSS_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID> set OSS_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET> set OSS_SESSION_TOKEN=<ALIBABA_CLOUD_SECURITY_TOKEN>通過環境變數來傳遞憑證資訊。
using Aliyun.OSS; using Aliyun.OSS.Common; using Aliyun.OSS.Common.Authentication; // 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET 和 OSS_SESSION_TOKEN。 var accessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"); var accessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"); var token = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_SECURITY_TOKEN"); var credentialsProvider = new DefaultCredentialsProvider(new DefaultCredentials(accessKeyId, accessKeySecret, token)); // 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。 const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。 const string region = "cn-hangzhou"; var conf = new ClientConfiguration(); var client = new OssClient(endpoint, credentialsProvider, conf); client.SetRegion(region);
靜態憑證
您可以在應用程式中對憑據直接進行寫入程式碼,顯式設定要使用的臨時存取金鑰。
using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;
// 從環境變數中擷取訪問憑證。運行本程式碼範例之前,請確保已設定環境變數OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET 和 OSS_SESSION_TOKEN。
var accessKeyId = "STS.NTZdStF79CVRTQuWCfXTT****";
var accessKeySecret = "5rm8PfEiK8enp56zzAMX4RbZUraoKbWXvCf1xAuT****"
var token = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_SECURITY_TOKEN");
var credentialsProvider = new DefaultCredentialsProvider(new DefaultCredentials(accessKeyId, accessKeySecret, token));
// 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);
更多情境化配置樣本
使用RAMRoleARN
如果您的應用程式需要授權訪問OSS,例如跨阿里雲帳號訪問OSS,您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN(Alibabacloud Resource Name),Credentials工具會前往STS服務擷取STS Token,並在會話到期前自動重新整理STS Token。此外,您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。
阿里雲帳號擁有資源的全部許可權,AK一旦泄露,會給系統帶來巨大風險,不建議使用。推薦使用最小化授權的RAM使用者的AK。
如需建立RAM使用者的AK,請直接存取建立AccessKey。RAM使用者的Access Key ID、Access Key Secret資訊僅在建立時顯示,請及時儲存,如若遺忘請考慮建立新的AK進行輪換。
如需擷取RAMRoleARN,請直接存取CreateRole - 建立角色。
安裝阿里雲憑證庫,具體請參見管理訪問憑證。
配置訪問憑證。
using Aliyun.OSS; using Aliyun.OSS.Common; using Aliyun.OSS.Common.Authentication; class CredentialsProviderWrapper : ICredentialsProvider { private Aliyun.Credentials.Client client; public CredentialsProviderWrapper(Aliyun.Credentials.Client client) { this.client = client; } public ICredentials GetCredentials() { var accessKeyId = client.GetAccessKeyId(); var accessKeySecret = client.GetAccessKeySecret(); var token = client.GetSecurityToken(); return new DefaultCredentials(accessKeyId, accessKeySecret, token); } public void SetCredentials(ICredentials creds) { } }; 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"), // 以下操作預設直接填入參數數值,您也可以通過添加環境變數,並使用Environment.GetEnvironmentVariable("<變數名稱>")的方式來get對應參數 // 要扮演的RAM角色ARN,樣本值:acs:ram::123456789012****:role/adminrole RoleArn = "<RoleArn>", // RoleArn預設環境變數正式名稱ALIBABA_CLOUD_ROLE_ARN // 角色會話名稱 RoleSessionName = "<RoleSessionName>", // RoleSessionName預設環境變數正式名稱ALIBABA_CLOUD_ROLE_SESSION_NAME }; var credentialsClient = new Aliyun.Credentials.Client(config); var credentialsProvider = new CredentialsProviderWrapper(credentialsClient); // 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。 const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com"; // 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。 const string region = "cn-hangzhou"; var conf = new ClientConfiguration(); var client = new OssClient(endpoint, credentialsProvider, conf); client.SetRegion(region);
使用ECSRAMRole
如果您的應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中,建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點,實現在執行個體內部自動重新整理STS Token。該方式無需您提供一個AK或STS Token,消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole,請參見CreateRole - 建立角色。
安裝阿里雲憑證庫,具體請參見管理訪問憑證。
配置ECSRAMRole作為訪問憑證。
using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;
class CredentialsProviderWrapper : ICredentialsProvider
{
private Aliyun.Credentials.Client client;
public CredentialsProviderWrapper(Aliyun.Credentials.Client client)
{
this.client = client;
}
public ICredentials GetCredentials()
{
var accessKeyId = client.GetAccessKeyId();
var accessKeySecret = client.GetAccessKeySecret();
var token = client.GetSecurityToken();
return new DefaultCredentials(accessKeyId, accessKeySecret, token);
}
public void SetCredentials(ICredentials creds)
{
}
};
var config = new Aliyun.Credentials.Models.Config()
{
Type = "ecs_ram_role",
// 選填,該ECS角色的角色名稱,不填會自動擷取,但是建議加上以減少請求次數
RoleName = "<RoleName>"
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);
// 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);
使用OIDCRoleARN
在Container ServiceKubernetes版中設定了Worker節點RAM角色後,對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣,通過中繼資料服務(Meta Data Server)擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用(比如部署您的客戶提交的應用,代碼也沒有對您開放),您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全,同時又能讓這些不可信的應用安全地擷取所需的STS Token,實現應用層級的許可權最小化,您可以使用RRSA(RAM Roles for Service Account)功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案,並將相關配置資訊注入到環境變數中,Credentials工具通過擷取環境變數的配置資訊,調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需您提供一個AK或STS Token,消除了手動維護AK或STS Token的風險。詳情請參見基於RRSA的Pod許可權隔離。
注入的環境變數如下:
ALIBABA_CLOUD_ROLE_ARN:RAM角色名稱ARN;
ALIBABA_CLOUD_OIDC_PROVIDER_ARN:OIDC供應商ARN;
ALIBABA_CLOUD_OIDC_TOKEN_FILE:OIDC Token檔案路徑;
配置OIDCRoleArn作為訪問憑證。
using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;
class CredentialsProviderWrapper : ICredentialsProvider
{
private Aliyun.Credentials.Client client;
public CredentialsProviderWrapper(Aliyun.Credentials.Client client)
{
this.client = client;
}
public ICredentials GetCredentials()
{
var accessKeyId = client.GetAccessKeyId();
var accessKeySecret = client.GetAccessKeySecret();
var token = client.GetSecurityToken();
return new DefaultCredentials(accessKeyId, accessKeySecret, token);
}
public void SetCredentials(ICredentials creds)
{}
};
var config = 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
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);
// 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);使用CredentialsURI
如果您的應用程式需要通過外部系統擷取阿里雲憑證,從而實現靈活的憑證管理和無密鑰訪問,您可以使用CredentialsURI初始化憑證提供者。該方式底層實現是STS Token。Credentials工具通過您提供的URI擷取STS Token,完成憑證用戶端初始化。該方式無需您提供一個AK或STS Token,消除了手動維護AK或STS Token的風險。需要注意的是,提供CredentialsURI響應的後端服務需要實現STS Token的自動重新整理邏輯,確保您的應用程式始終能擷取到有效憑證。
using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;
class CredentialsProviderWrapper : ICredentialsProvider
{
private Aliyun.Credentials.Client client;
public CredentialsProviderWrapper(Aliyun.Credentials.Client client)
{
this.client = client;
}
public ICredentials GetCredentials()
{
var accessKeyId = client.GetAccessKeyId();
var accessKeySecret = client.GetAccessKeySecret();
var token = client.GetSecurityToken();
return new DefaultCredentials(accessKeyId, accessKeySecret, token);
}
public void SetCredentials(ICredentials creds)
{}
};
var config = new Aliyun.Credentials.Models.Config()
{
// 憑證類型。
Type = "credentials_uri",
// 擷取憑證的 URI,格式為http://local_or_remote_uri/,可以通過環境變數ALIBABA_CLOUD_CREDENTIALS_URI設定CredentialsUri
CredentialsURI = "<CredentialsURI>"
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);
// 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);自訂訪問憑證
如果以上憑證配置方式都不滿足要求時,您還可以通過實現Credential Providers介面的方式,來自訂憑證提供方式。
using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;
class CustomCredentialsProvider : ICredentialsProvider
{
public CustomCredentialsProvider()
{
}
public ICredentials GetCredentials()
{
//TODO
//自訂訪問憑證的擷取方法
string accessKeyId;
string accessKeySecret;
//string token;
// 返回長期憑證 access_key_id, access_key_secrect
return new DefaultCredentials(accessKeyId, accessKeySecret, "");
// 返回 臨時憑證 access_key_id, access_key_secrect, token
// 對於臨時憑證,需要根據到期時間,重新整理憑證。
// return new DefaultCredentials(accessKeyId, accessKeySecrect, token);
}
public void SetCredentials(ICredentials creds)
{
}
};
var credentialsProvider = new CustomCredentialsProvider();
// 填寫Bucket所在地區對應的Endpoint。以華東1(杭州)為例,Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket所在地區對應的Region。以華東1(杭州)為例,Region填寫為cn-hangzhou。
const string region = "cn-hangzhou";
var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);