本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
使用C# SDK发起OSS请求,您需要配置访问凭证。阿里云服务会通过访问凭证验证您的身份信息和访问权限。您可以根据使用场景对认证和授权的要求,选择不同的方式提供凭证。
注意事项
如果您希望获取关于OSS支持的Region与Endpoint的对应关系,请参见地域和Endpoint。
如果您希望创建RAM用户的AccessKey,请参见创建AccessKey。
凭证提供者选型参考
OSS支持多种方式初始化凭证提供者,您可以根据使用场景对认证和授权的要求,选择对应的方式初始化凭证提供者。
凭证提供者初始化方式 | 适用场景 | 是否需要提供前置的AK或STS Token | 底层实现基于的凭证 | 凭证有效期 | 凭证轮转或刷新方式 |
部署运行在安全、稳定且不易受外部攻击的环境的应用程序,无需频繁轮转凭证就可以长期访问云服务 | 是 | AK | 长期 | 手动轮转 | |
部署运行在不可信的环境的应用程序,希望能控制访问的有效期、权限 | 是 | STS Token | 临时 | 手动刷新 | |
需要授权访问云服务,例如跨阿里云账号访问云服务的应用程序 | 是 | STS Token | 临时 | 自动刷新 | |
部署运行在阿里云的ECS实例、ECI实例、容器服务Kubernetes版的Worker节点中的应用程序 | 否 | STS Token | 临时 | 自动刷新 | |
部署运行在阿里云的容器服务Kubernetes版的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实例、容器服务Kubernetes版的Worker节点中,建议您使用ECSRAMRole初始化凭证提供者。该方式底层实现是STS Token。ECSRAMRole允许您将一个角色关联到ECS实例、ECI实例或容器服务 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
在容器服务Kubernetes版中设置了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配置ServiceAccount的RAM权限实现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);