Configure authentication for C# SDK V1.0 - Alibaba Cloud SDK

The Alibaba Cloud SDK for C# V1.0 supports several credential types. Choose the one that fits your deployment environment and security requirements.

Choose a credential type

Credential type	When to use
AccessKey	Development and testing. Avoid in production — an exposed AccessKey compromises all resources in the account.
STS token	Short-lived access with fine-grained permissions. Typically obtained via AssumeRole.
RAM role ARN	Cross-account access or delegating permissions to a RAM user via STS.
Instance RAM role	Applications running on ECS. No AccessKey required — the SDK fetches credentials automatically from the instance metadata service.
RAM role with OIDC	Applications running in ACK (Kubernetes). Each pod assumes a distinct RAM role without an AccessKey.
Bearer token	Cloud Call Center (CCC) only.
Default credential provider chain	Local development or environments where credentials are managed externally (environment variables, config file, or instance metadata).

Use an AccessKey

Important

Leaking an AccessKey from your Alibaba Cloud account compromises all resources within it. For improved security, we strongly recommend using an AccessKey that belongs to a RAM user. For more information, see Create an AccessKey.
Ensure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are set in your runtime environment. For more information, see Configure environment variables in Linux, macOS, and Windows.

Initialize the client with an AccessKey by using IClientProfile.

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            IClientProfile profile = DefaultProfile.GetProfile(
                // The region ID.
                "<REGION_ID>",
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            DefaultAcsClient client = new DefaultAcsClient(profile);
            // Code for calling API operations is omitted.
        }
    }
}

Initialize the client with an AccessKey by using AlibabaCloudCredentialsProvider.

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Profile;
using Aliyun.Acs.Core.Auth;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            AlibabaCloudCredentialsProvider provider = new AccessKeyCredentialProvider(
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            DefaultAcsClient client = new DefaultAcsClient(profile, provider);
            // Code for calling API operations is omitted.
        }
    }
}

Use an STS token

Initialize the client with a temporary access credential obtained via Security Token Service (STS).

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Auth;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            AlibabaCloudCredentialsProvider provider = new StsCredentialProvider(
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
                // Retrieve the security token of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_SECURITY_TOKEN"));
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            DefaultAcsClient client = new DefaultAcsClient(profile, provider);
            // Code for calling API operations is omitted.
        }
    }
}

Use a RAM role ARN

Obtain an STS token by calling the STS AssumeRole operation as a Resource Access Management (RAM) user.

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Auth;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            AlibabaCloudCredentialsProvider provider = new AccessKeyCredentialProvider(
                // Retrieve the AccessKey ID of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Retrieve the AccessKey secret of the RAM user from an environment variable.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            // Use the RAM role ARN.
            STSAssumeRoleSessionCredentialsProvider stsProvider = new STSAssumeRoleSessionCredentialsProvider(
                provider,
                "<ROLE_ARN>",
                profile
                );

            DefaultAcsClient client = new DefaultAcsClient(profile, stsProvider);
            // Code for calling API operations is omitted.
        }
    }
}

Use an instance RAM role

The SDK retrieves temporary credentials from an instance RAM role attached to your Elastic Compute Service (ECS) instance. Applications access Alibaba Cloud APIs without a hardcoded AccessKey — the SDK automatically uses the permissions granted to the role.

Important

Ensure that a RAM role is attached to your ECS instance.

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Profile;
using Aliyun.Acs.Core.Auth;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            // Use an instance RAM role.
            InstanceProfileCredentialsProvider provider = new InstanceProfileCredentialsProvider(
                "<ROLE_NAME>");
            DefaultAcsClient client = new DefaultAcsClient(profile, provider);
            // Code for calling API operations is omitted.
        }
    }
}

Use a RAM role with OIDC

In Container Service for Kubernetes (ACK), RAM Roles for Service Accounts (RRSA) lets each pod assume a distinct RAM role and access cloud resources with temporary credentials. This enforces least privilege and eliminates AccessKeys, preventing credential leaks.

ACK creates and mounts a service account OpenID Connect (OIDC) token file for each pod and injects configuration details into environment variables. The SDK reads these variables and calls the STS AssumeRoleWithOIDC operation to exchange the OIDC token for a temporary STS token. For more information, see Isolate pod permissions by using RAM Roles for Service Accounts (RRSA).

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Auth;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            AlibabaCloudCredentialsProvider provider = new OIDCCredentialsProvider(
                // The ARN of the RAM role.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_ROLE_ARN"), 
                // The ARN of the OIDC provider.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_OIDC_PROVIDER_ARN"), 
                // The file path of the OIDC token.
                Environment.GetEnvironmentVariable("ALIBABA_CLOUD_OIDC_TOKEN_FILE"),
                // A custom role session name.
                "<ROLE_SESSION_NAME>",
                // The region ID for the STS service.
                "<REGION_ID>");
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            DefaultAcsClient client = new DefaultAcsClient(profile, provider);
            // Code for calling API operations is omitted.
        }
    }
}

Use a bearer token

Note

This method is supported only by Cloud Call Center (CCC).

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Auth;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            AlibabaCloudCredentialsProvider provider = new BearerTokenCredentialProvider("<BEARER_TOKEN>");
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            DefaultAcsClient client = new DefaultAcsClient(profile, provider);
            // Code for calling API operations is omitted.
        }
    }
}

Use the default credential provider chain

DefaultCredentialProvider searches for credentials in the following order and uses the first match:

Priority	Source	Credential type
1	Environment variables (`ALIBABA_CLOUD_ACCESS_KEY_ID` + `ALIBABA_CLOUD_ACCESS_KEY_SECRET`)	AccessKey
2	Environment variables (`ALIBABA_CLOUD_ROLE_ARN` + `ALIBABA_CLOUD_OIDC_PROVIDER_ARN` + `ALIBABA_CLOUD_OIDC_TOKEN_FILE`)	OIDC RAM role
3	Credentials file (`~/.alibabacloud/credentials.ini`)	Any supported type
4	Environment variable `ALIBABA_CLOUD_ECS_METADATA` (instance RAM role name)	Instance RAM role

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Auth.Provider;
using Aliyun.Acs.Core.Profile;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample
    {
        public static void Main(string[] args)
        {
            IClientProfile profile = DefaultProfile.GetProfile("<REGION_ID>");
            var alibabaCloudClientCredential = new DefaultCredentialProvider();
            var client = new DefaultAcsClient(profile,alibabaCloudClientCredential);
            // Code for calling API operations is omitted.
        }
    }
}

Important

DefaultCredentialProvider is convenient for local development and testing, but is not recommended for production. When authentication fails, identifying the offending credential source can be difficult. In production, use an explicit credential type that matches your deployment environment — such as an instance RAM role for ECS or an OIDC RAM role for ACK.

1. Environment credentials

The SDK checks for ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. If both are set and non-empty, they are used to create credentials.

2. OIDC RAM role

If no higher-priority credentials are found, the SDK reads the following environment variables:

Variable	Description
`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 file path of the OIDC token.

If all three are set, the SDK calls the AssumeRoleWithOIDC operation and uses the returned STS token.

3. Configuration file

If a file exists at ~/.alibabacloud/credentials.ini (or C:\Users\USER_NAME\.alibabacloud\credentials.ini on Windows), the SDK reads credentials from it. Override the default path with the ALIBABA_CLOUD_CREDENTIALS_FILE environment variable. Specify a profile with ALIBABA_CLOUD_PROFILE; if unset, the SDK uses the default profile.

The file supports all credential types:

[default]                            # Default profile
type = access_key                    # Authentication type: access_key
access_key_id = foo                  # Your AccessKey ID
access_key_secret = bar              # Your AccessKey Secret

[client1]                            # Profile named 'client1'
type = ecs_ram_role                  # Authentication type: ecs_ram_role
role_name = EcsRamRoleTest           # The role name

[client2]                            # Profile named 'client2'
type = ram_role_arn                  # Authentication type: ram_role_arn
access_key_id = foo
access_key_secret = bar
role_arn = role_arn                  # The role ARN
role_session_name = role_session_name # A custom session name

[client3]                            # Profile named 'client3'
type = oidc_role_arn                 # Authentication type: oidc_role_arn
access_key_id = foo
access_key_secret = bar
role_arn = role_arn                  # The role ARN
oidc_provider_arn = oidc_provider_arn # The OIDC provider ARN
oidc_token_file_path = /path/to/token # The OIDC token file path
role_session_name = role_session_name # A custom session name

4. Instance RAM role

If no credentials are found through the previous sources, the SDK checks the ALIBABA_CLOUD_ECS_METADATA environment variable for an instance RAM role name. If set, the SDK fetches an STS token from the ECS metadata server.