Object Storage Service:Configure access credentials (C# SDK V1)

Choose a credential provider

Select a credential provider based on your deployment environment and security requirements.

Recommended approach: Use role-based providers (ECSRAMRole, RAMRoleARN, OIDCRoleARN) whenever possible. These providers use STS tokens that auto-refresh, eliminating the need to manage long-term credentials manually. Unlike static AccessKey pairs, STS tokens expire automatically, limiting the impact of any exposure.

RAM user AccessKey pair

Use this method when your application runs in a secure, stable environment and requires long-term OSS access without frequent credential rotation. Maintain the AccessKey pair manually; if it is compromised, rotate it immediately.

To get an AccessKey pair, see CreateAccessKey.

export ALIBABA_CLOUD_ACCESS_KEY_ID=<ALIBABA_CLOUD_ACCESS_KEY_ID>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<ALIBABA_CLOUD_ACCESS_KEY_SECRET>

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;

// Read credentials from environment variables.
// Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET before running.
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, ""));

// Replace with the endpoint of your bucket's region.
// Example: China (Hangzhou) -> https://oss-cn-hangzhou.aliyuncs.com
const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
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;

// Replace with your actual AccessKey ID and AccessKey secret.
var accessKeyId = "LTAI5tQQx1DWEYK7********";
var accessKeySecret = "s5LkMqKmmKbt3zjs7MNJTj********";
var credentialsProvider = new DefaultCredentialsProvider(new DefaultCredentials(accessKeyId, accessKeySecret, ""));

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

STS temporary credentials

Use this method when your application needs temporary OSS access. Obtain an STS token (AccessKey ID, AccessKey secret, and security token) from Security Token Service (STS) and pass it directly to the credential provider. Refresh the token manually before it expires.

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>

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;

// Read STS credentials from environment variables.
// Set ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET,
// and ALIBABA_CLOUD_SECURITY_TOKEN before running.
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));

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
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;

// Replace with your actual temporary AccessKey ID, AccessKey secret, and security 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));

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

RAMRoleARN

Use this method for cross-account access or any scenario that requires delegating OSS access to a RAM role. Specify the Alibaba Cloud Resource Name (ARN) of the RAM role; the credentials library retrieves an STS token from STS and refreshes it automatically before expiration. Optionally, set a Policy value to further restrict the role's permissions.

Step 1: Install the Alibaba Cloud credentials library.

See Manage access credentials.

Step 2: Configure the credential provider.

using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;

// CredentialsProviderWrapper bridges the Alibaba Cloud credentials library
// and the OSS SDK's ICredentialsProvider interface.
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",
    // Read the caller's AccessKey pair from environment variables.
    AccessKeyId = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    AccessKeySecret = Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole
    // Default environment variable: ALIBABA_CLOUD_ROLE_ARN
    RoleArn = "<RoleArn>",
    // The role session name. Default environment variable: ALIBABA_CLOUD_ROLE_SESSION_NAME
    RoleSessionName = "<RoleSessionName>",
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

ECSRAMRole

Use this method when your application runs on an ECS instance, an Elastic Container Instance (ECI) instance, or a Container Service for Kubernetes worker node. Associate a RAM role with the instance; the credentials library fetches and auto-refreshes the STS token from the instance metadata. No AccessKey pair or STS token is required.

To create an ECSRAMRole, see CreateRole.

Step 1: Install the Alibaba Cloud credentials library.

See Manage access credentials.

Step 2: Configure the credential provider.

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",
    // Optional, but recommended to reduce the number of requests.
    // If not set, the role name is retrieved automatically from instance metadata.
    RoleName = "<RoleName>"
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

OIDCRoleARN

Use this method to grant application-level permissions to pods running on Container Service for Kubernetes worker nodes, without exposing the node's instance RAM role to untrusted workloads. This implements RAM Roles for Service Accounts (RRSA): the cluster mounts an OpenID Connect (OIDC) token file into each pod and injects configuration into environment variables. The credentials library reads those variables and calls AssumeRoleWithOIDC to exchange the OIDC token for an STS token. No AccessKey pair is required.

The following environment variables are injected by the cluster:

• ALIBABA_CLOUD_ROLE_ARN: The ARN of the RAM role.

• ALIBABA_CLOUD_OIDC_PROVIDER_ARN: The ARN of the OIDC provider.

• ALIBABA_CLOUD_OIDC_TOKEN_FILE: The path to the OIDC token file.

For setup instructions, see Isolate pod permissions using RRSA.

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",
    // The RAM role ARN. Can also be set via ALIBABA_CLOUD_ROLE_ARN.
    RoleArn = "<RoleArn>",
    // The OIDC provider ARN. Can also be set via ALIBABA_CLOUD_OIDC_PROVIDER_ARN.
    OIDCProviderArn = "<OidcProviderArn>",
    // Path to the OIDC token file. Can also be set via ALIBABA_CLOUD_OIDC_TOKEN_FILE.
    OIDCTokenFilePath = "<OidcTokenFilePath>",
    // The role session name. Can also be set via ALIBABA_CLOUD_ROLE_SESSION_NAME.
    RoleSessionName = "<RoleSessionName>",
    // Optional. A JSON policy to further restrict the role's permissions.
    // Example: {"Statement":[{"Action":["*"],"Effect":"Allow","Resource":["*"]}],"Version":"1"}
    Policy = "<Policy>",
    RoleSessionExpiration = 3600
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

CredentialsURI

Use this method when your application retrieves credentials from an external service. Provide a URI that returns valid STS credentials; the credentials library fetches tokens from that URI and handles refresh. Your backend service must implement its own token-refresh logic to ensure credentials remain valid. No AccessKey pair is required.

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()
{
    // The credential type.
    Type = "credentials_uri",
    // The URI to fetch credentials from. Format: http://local_or_remote_uri/
    // Can also be set via ALIBABA_CLOUD_CREDENTIALS_URI.
    CredentialsURI = "<CredentialsURI>"
};
var credentialsClient = new Aliyun.Credentials.Client(config);
var credentialsProvider = new CredentialsProviderWrapper(credentialsClient);

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

Custom credential provider

Implement the ICredentialsProvider interface to define your own credential-fetching logic.

using Aliyun.OSS;
using Aliyun.OSS.Common;
using Aliyun.OSS.Common.Authentication;

class CustomCredentialsProvider : ICredentialsProvider
{
    public CustomCredentialsProvider() { }

    public ICredentials GetCredentials()
    {
        // TODO: Add your custom credential-fetching logic here.

        string accessKeyId;
        string accessKeySecret;
        // string token;

        // For long-term credentials, omit the token.
        return new DefaultCredentials(accessKeyId, accessKeySecret, "");

        // For temporary credentials, include the token.
        // Refresh credentials before they expire.
        // return new DefaultCredentials(accessKeyId, accessKeySecret, token);
    }

    public void SetCredentials(ICredentials creds) { }
};

var credentialsProvider = new CustomCredentialsProvider();

const string endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
const string region = "cn-hangzhou";

var conf = new ClientConfiguration();
var client = new OssClient(endpoint, credentialsProvider, conf);
client.SetRegion(region);

FAQ