All Products
Search
Document Center

Alibaba Cloud SDK:Manage access credentials

Last Updated:Jun 27, 2024

When you call API operations to manage cloud resources by using Alibaba Cloud SDKs, you must configure valid credential information. The Alibaba Cloud Credentials tool provides a powerful set of features that allow you to easily obtain and manage access credentials. This topic describes how to use the Credentials tool to configure various types of credentials such as the default credential, AccessKey pairs, or Security Token Service (STS) tokens. This topic also describes the order based on which the Credentials tool obtains the default credential. You can develop a thorough knowledge of configuring and managing credentials in Alibaba Cloud SDKs. This ensures that your operations on cloud resources are efficient and secure.

Background information

A credential is a set of information that is used to prove the identity of a user. When you log on to the system, you must use a valid credential to complete identity authentication. The following types of credentials are commonly used:

  1. An AccessKey pair of an Alibaba Cloud account or a Resource Access Management (RAM) user. An AccessKey pair is permanently valid. It consists of an AccessKey ID and an AccessKey secret.

  2. An STS token of a RAM role. An STS token is a temporary credential. You can specify a validity period and access permissions for an STS token. For more information, see What is STS?

  3. A bearer token. It is used for identity authentication and authorization.

Prerequisites

  • Node.js 8.5.0 or later is installed.

  • Alibaba Cloud SDK V2.0 is installed.

  • The in-house SDKs of services that use self-managed gateways are not installed.

Install the Credentials tool

Run the following npm command to download and install Alibaba Cloud Credentials for Node.js:

npm install @alicloud/credentials

We recommend that you use the latest version of Alibaba Cloud Credentials for Node.js.

Initialize a Credentials client

You can use one of the following methods to initialize a Credentials client based on your business requirements:

Important

JavaScript is used in the following sample code.

Method 1: Use the default credential provider chain

If you do not specify a method to initialize a Credentials client, the default credential provider chain is used. For more information, see the Default credential provider chain section of this topic.

const Credential = require('@alicloud/credentials');

// Do not specify a method to initialize a Credentials client.
const credentialClient = new Credential.default();

Call example

You can use the default credential provider chain to automatically create access credentials and call the API operations of Alibaba Cloud services without the need to use a hard-coded AccessKey pair.

The following sample code provides an example on how to call the DescribeRegions operation of Elastic Compute Service (ECS). Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    // Use the default credential to initialize a Credentials client. 
    const credentialClient = new Credential.default();
    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((result) => {
        console.log(JSON.stringify(result.body));
    });
}

main().catch(console.error);

Method 2: Use an AccessKey pair

You can create an AccessKey pair that is used to call API operations for your Alibaba Cloud account or a RAM user. For more information, see Create an AccessKey pair. Then, you can use the AccessKey pair to initialize a Credentials client.

Warning

An Alibaba Cloud account has full access to all resources of the account. AccessKey pair leaks of an Alibaba Cloud account pose critical threats to the system.

Therefore, we recommend that you use an AccessKey pair of a RAM user that is granted minimum necessary permissions to initialize a Credentials client.

const Credential = require('@alicloud/credentials');

// Use an AccessKey pair to initialize a Credentials client. 
const credentialsConfig = new Credential.Config({
    // Specify the type of the credential. 
    type: 'access_key',
    // Specify the AccessKey ID. 
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // Specify the AccessKey secret. 
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET
})
const credentialClient = new Credential.default(credentialsConfig);

Call example

You can use the Credentials tool to read an AccessKey pair and call the API operations of Alibaba Cloud services.

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    // Use an AccessKey pair to initialize a Credentials client. 
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential. 
        type: 'access_key',
        // Specify the AccessKey ID. 
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
        // Specify the AccessKey secret. 
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response)=>{
        console.log(response.body.regions);
    });
}

main().catch(console.error);

Method 3: Use an STS token

You can call the AssumeRole operation of STS as a RAM user to obtain an STS token. You can specify the maximum validity period of the STS token. The following sample code provides an example on how to initialize a Credentials client by using an STS token. The example does not show how to obtain an 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"
  }
}
const Credential = require('@alicloud/credentials');

const credentialsConfig = new Credential.Config({
    type: 'sts',
    // Replace <ALIBABA_CLOUD_ACCESS_KEY_ID> with the temporary AccessKey ID that is obtained from the response to the AssumeRole operation. 
    accessKeyId: '<ALIBABA_CLOUD_ACCESS_KEY_ID>',
    // Replace <ALIBABA_CLOUD_ACCESS_KEY_SECRET> with the temporary AccessKey secret that is obtained from the response to the AssumeRole operation. 
    accessKeySecret: '<ALIBABA_CLOUD_ACCESS_KEY_SECRET>',
    // Replace <ALIBABA_CLOUD_SECURITY_TOKEN> with the STS token that is obtained from the response to the AssumeRole operation. 
    securityToken: '<ALIBABA_CLOUD_SECURITY_TOKEN>',
})
const cred = new Credential.default(credentialsConfig);

Call example

You can use the Credentials tool to read an STS token and call the API operations of Alibaba Cloud services.

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java and STS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const Sts20150401 = require('@alicloud/sts20150401');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    // Create an STS client and call the AssumeRole operation to obtain the STS token.
    const stsConfig = new OpenApi.Config();
    stsConfig.endpoint = 'sts.cn-hangzhou.aliyuncs.com';
    stsConfig.accessKeyId = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
    stsConfig.accessKeySecret = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
    const stsClient = new Sts20150401.default(stsConfig);
    const assumeRoleRequest = Sts20150401.AssumeRoleRequest;
    // Specify the validity period of the STS token.
    assumeRoleRequest.durationSeconds = 3600;
    // Specify the ARN of the RAM role to be assumed.
    assumeRoleRequest.roleArn = "acs:ram::125499367423****:role/STStokenTestRole/STSsessionName";
    // Specify the name of the role session.
    assumeRoleRequest.roleSessionName = "35219123109646****:STSsessionName";
    // assumeRoleRequest.policy = "";
    const assumeRoleResponsePromise = stsClient.assumeRole(assumeRoleRequest);
    const assumeRoleResponseBodyCredentials = (await assumeRoleResponsePromise).body.credentials;

    // Use an STS token to initialize a Credentials client. 
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential. 
        type: 'sts',
        // Replace <ALIBABA_CLOUD_ACCESS_KEY_ID> with the temporary AccessKey ID that is obtained from the response to the AssumeRole operation. 
        accessKeyId: assumeRoleResponseBodyCredentials.accessKeyId,
        // Replace <ALIBABA_CLOUD_ACCESS_KEY_SECRET> with the temporary AccessKey secret that is obtained from the response to the AssumeRole operation. 
        accessKeySecret: assumeRoleResponseBodyCredentials.accessKeySecret,
        // Replace <ALIBABA_CLOUD_SECURITY_TOKEN> with the STS token that is obtained from the response to the AssumeRole operation. 
        securityToken: assumeRoleResponseBodyCredentials.securityToken,
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body.regions);
    });
}

main().catch(console.error);

Method 4: Use an AccessKey pair and a RAM role

The underlying logic of this method is to use an STS token to initialize a Credentials client. After you specify the Alibaba Cloud Resource Name (ARN) of a RAM role, the Credentials tool can obtain an STS token from STS. You can also use the policy parameter to limit the permissions of the RAM role.

const Credential = require('@alicloud/credentials');

const credentialsConfig = new Credential.Config({
    type: 'ram_role_arn',
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // Specify the ARN of the RAM role to be assumed.
    roleArn: '<RoleArn>',
    // Specify the name of the role session.
    roleSessionName: '<RoleSessionName>',
    // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
    policy: '<Policy>',
    roleSessionExpiration: 3600,
})
const cred = new Credential.default(credentialsConfig);

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    // Use an AccessKey pair and a RAM role to initialize a Credentials client. 
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential. 
        type: 'ram_role_arn',
        // Specify the AccessKey ID. 
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
        // Specify the AccessKey secret. 
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
        // Specify the ARN of the RAM role to be assumed.
        roleArn: 'acs:ram::125499367423****:role/STStokenTestRole/STSsessionName',
        // Specify the name of the role session.
        roleSessionName: '35219123109646****:STSsessionName',
        // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
        // policy: '<Policy>',
        roleSessionExpiration: 3600,
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Method 5: Use the RAM role of an ECS instance and access the metadata of the ECS instance in normal mode

The underlying logic of this method is to use an STS token to initialize a Credentials client. The Credentials tool automatically obtains the RAM role attached to an ECS instance and uses the metadata server of ECS to obtain an STS token. The STS token is then used to initialize a Credentials client. You can also attach a RAM role to an elastic container instance or a worker node in an Container Service for Kubernetes cluster.

const Credential = require('@alicloud/credentials');

const credentialsConfig = new Credential.Config({
    type: 'ecs_ram_role',
    // Optional. Specify the name of the RAM role of the ECS instance. If you do not specify this parameter, its value is automatically obtained. To reduce the number of requests, we recommend that you specify this parameter.
    roleName: 'roleName',
})
const cred = new Credential.default(credentialsConfig);

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    // Use the RAM role of an ECS instance to initialize a Credentials client. 
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential. 
        type: 'ecs_ram_role',
        // Optional. Specify the name of the RAM role of the ECS instance. If you do not specify this parameter, its value is automatically obtained. To reduce the number of requests, we recommend that you specify this parameter.
        roleName: 'roleName',
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Method 6: Use the RAM role of an ECS instance and access the metadata of the ECS instance in security hardening mode

You can access the metadata of an ECS instance in security hardening mode and obtain the initial credential of the RAM role that is attached to the ECS instance. Compared with the normal mode, the security hardening mode implements the following security logic that is more rigorous: First, a token that has a validity period is automatically generated inside the ECS instance. Then, this token is used as a credential to request an STS token from the metadata server. These operations also constitute the secure initialization process of a Credentials client.

In security hardening mode, the token generated inside the ECS instance is dynamic and has a validity period. In this case, external attackers cannot illegally access the metadata server by predicting or forging a token. This effectively prevents network security risks such as server-side request forgery (SSRF). The security hardening mode not only adds an extra layer of protection to identity verification, but also significantly improves the security of the overall system. This mode ensures the secure access to and management of cloud resources.

const Credential = require('@alicloud/credentials');

const credentialsConfig = new Credential.Config({
    // Specify the type of the credential.
    type: 'ecs_ram_role',
    // Optional. Specify the name of the RAM role of the ECS instance. If you do not specify this parameter, its value is automatically obtained. To reduce the number of requests, we recommend that you specify this parameter.
    roleName: 'roleName',
    // Optional. We recommend that you set the enableIMDSv2 parameter to true. This parameter is equivalent to the ALIBABA_CLOUD_ECS_IMDSV2_ENABLE environment variable.
    enableIMDSv2: true,
})
const credentialClient = new Credential.default(credentialsConfig);
Important
  • The default value of the enableIMDSv2 parameter is false, which specifies that the metadata of the ECS instance is accessed in normal mode.

  • If you want to access the metadata of the ECS instance in security hardening mode, set the enableIMDSv2 parameter to true.

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential.
        type: 'ecs_ram_role',
        // Optional. Specify the name of the RAM role of the ECS instance. If you do not specify this parameter, its value is automatically obtained. To reduce the number of requests, we recommend that you specify this parameter.
        roleName: 'roleName',
        // Optional. We recommend that you set the enableIMDSv2 parameter to true. This parameter is equivalent to the ALIBABA_CLOUD_ECS_IMDSV2_ENABLE environment variable.
        enableIMDSv2: true,
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Method 7: Use the RAM role of an OIDC IdP

After you attach a RAM role to a worker node in an Container Service for Kubernetes, applications in the pods on the worker node can use the metadata server to obtain an STS token the same way in which applications on ECS instances do. However, if an untrusted application is deployed on the worker node, such as an application that is submitted by your customer and whose code is unavailable to you, you may not want the application to use the metadata server to obtain an STS token of the RAM role attached to the worker node. To ensure the security of cloud resources and enable untrusted applications to securely obtain required STS tokens, you can use the RAM Roles for Service Accounts (RRSA) feature to grant minimum necessary permissions to an application. In this case, the ACK cluster creates a service account OpenID Connect (OIDC) token file, associates the token file with a pod, and then injects relevant environment variables into the pod. Then, the Credentials tool uses the environment variables to call the AssumeRoleWithOIDC operation of STS and obtains an STS token of the RAM role. For more information about the RRSA feature, see Use RRSA to authorize different pods to access different cloud services.

The following environment variables are injected into the pod:

ALIBABA_CLOUD_ROLE_ARN: the ARN of the RAM role.

ALIBABA_CLOUD_OIDC_PROVIDER_ARN: the ARN of the OIDC identity provider (IdP).

ALIBABA_CLOUD_OIDC_TOKEN_FILE: the path of the OIDC token file.

const Credential = require('@alicloud/credentials');

const credentialsConfig = new Credential.Config({
    type: 'oidc_role_arn',
    roleArn: 'ALIBABA_CLOUD_ROLE_ARN',
    oidcProviderArn: 'ALIBABA_CLOUD_OIDC_PROVIDER_ARN',
    oidcTokenFilePath: 'ALIBABA_CLOUD_OIDC_TOKEN_FILE',
    // Specify the name of the role session.
    roleSessionName: 'roleSessionName',
    // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
    policy: '<Policy>',
    // Specify the validity period of the session.
    roleSessionExpiration: 3600,
})
const credentialClient = new Credential.default(credentialsConfig);

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential. 
        type: 'oidc_role_arn',
        roleArn: 'ALIBABA_CLOUD_ROLE_ARN',
        oidcProviderArn: 'ALIBABA_CLOUD_OIDC_PROVIDER_ARN',
        oidcTokenFilePath: 'ALIBABA_CLOUD_OIDC_TOKEN_FILE',
        // Specify the name of the role session.
        roleSessionName: 'roleSessionName',
        // Optional. Specify limited permissions for the RAM role. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}.
        policy: '<Policy>',
        // Specify the validity period of the session.
        roleSessionExpiration: 3600,
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpoint = 'ecs.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Method 8: Use a URI

The underlying logic of this method is to use an STS token to initialize a Credentials client. The Credentials tool uses the uniform resource identifier (URI) that you provide to obtain an STS token. The STS token is then used to initialize a Credentials client.

const Credential = require('@alicloud/credentials');

const config = new Credential.Config({
    type: 'credentials_uri',
    // Specify the URI of the credential, in the format of http://local_or_remote_uri/.
    credentialsURI: '<local_or_remote_uri>'
});
const credentialClient = new Credential(config);

The URI must meet the following requirements:

  • The status code 200 is returned.

  • The following response parameters are returned:

    {
      "Code": "Success",
      "AccessKeySecret": "AccessKeySecret",
      "AccessKeyId": "AccessKeyId",
      "Expiration": "2021-09-26T03:46:38Z",
      "SecurityToken": "SecurityToken"
    }

    Call example

    To call the API operations of Alibaba Cloud services, you can specify a local or remote URI for credentials and use the Credentials tool to obtain and automatically update an STS token based on the local or remote URI.

    To call the API operations of an Alibaba Cloud service, you must install dependencies for the Alibaba Cloud service. The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

    const Ecs20140526 = require('@alicloud/ecs20140526');
    const OpenApi = require('@alicloud/openapi-client');
    const Util = require('@alicloud/tea-util');
    const Credential = require('@alicloud/credentials');
    
    async function main() {
        // Use a URI to initialize a Credentials client. 
        const credentialsConfig = new Credential.Config({
            // Specify the type of the credential. 
            type: 'credentials_uri',
            // Specify the URI of the credential, in the format of http://local_or_remote_uri/.
            credentialsURI: '<local_or_remote_uri>'
        })
        const credentialClient = new Credential.default(credentialsConfig);
    
        const ecsConfig = new OpenApi.Config();
        // Specify the endpoint of the cloud service. 
        ecsConfig.endpointType = 'ecs.aliyuncs.com';
        // Use the SDK Credentials package to configure a credential. 
        ecsConfig.credential = credentialClient;
        // Initialize the ECS SDK client.
        const ecsClient = new Ecs20140526.default(ecsConfig);
        // Initialize the request to call the DescribeRegions operation. 
        const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
        // Initialize the runtime configurations. 
        const runtime = new Util.RuntimeOptions();
        // Call the DescribeRegions operation and obtain a response. 
        const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
        console.log((await response).body.regions);
    }
    
    main().catch(console.error);

Method 9: Use a bearer token

Only Cloud Call Center allows you to use a bearer token to initialize a Credentials client.

const Credential = require('@alicloud/credentials');

const config = new Credential.Config({
    type: 'bearer',
    // Enter the bearer token.
    bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(config);

Call example

The following sample code provides an example on how to call the DescribeRegions operation of ECS. Before you call this operation, you must install ECS SDK for Java.

const Ecs20140526 = require('@alicloud/ecs20140526');
const OpenApi = require('@alicloud/openapi-client');
const Util = require('@alicloud/tea-util');
const Credential = require('@alicloud/credentials');

async function main() {
    // Use a bearer token to initialize a Credentials client. 
    const credentialsConfig = new Credential.Config({
        // Specify the type of the credential. 
        type: 'bearer',
        // Enter the bearer token.
        bearerToken: '<BearerToken>',
    })
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    // Specify the endpoint of the cloud service. 
    ecsConfig.endpointType = 'ecs.aliyuncs.com';
    // Use the SDK Credentials package to configure a credential. 
    ecsConfig.credential = credentialClient;
    // Initialize the ECS SDK client.
    const ecsClient = new Ecs20140526.default(ecsConfig);
    // Initialize the request to call the DescribeRegions operation. 
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    // Initialize the runtime configurations. 
    const runtime = new Util.RuntimeOptions();
    // Call the DescribeRegions operation and obtain a response. 
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Default credential provider chain

If you want to use different types of credentials in the development and production environments of your application, you generally need to obtain the environment information from the code and write code branches to obtain different credentials for the development and production environments. The default credential provider chain of the Credentials tool allows you to use the same code to obtain credentials for different environments based on configurations independent of the application. If you use new Credential() to initialize a Credentials client without specifying an initialization method, the Credentials tool obtains the credential information in the following order:

1. Obtain the credential information from environment variables

The Credentials tool first obtains the credential information from environment variables. If the ALIBABA_CLOUD_ACCESS_KEY_ID (AccessKey ID) and ALIBABA_CLOUD_ACCESS_KEY_SECRET (AccessKey secret) system environment variables are specified, the Credentials tool uses the specified AccessKey pair as the default credential.

2. Obtain the credential information by using the RAM role of an OIDC IdP

If no credentials are found in the previous step, the Credentials tool obtains the values of the following environment variables:

ALIBABA_CLOUD_ROLE_ARN: the ARN of the RAM role.

ALIBABA_CLOUD_OIDC_PROVIDER_ARN: the ARN of the OIDC IdP.

ALIBABA_CLOUD_OIDC_TOKEN_FILE: the path of the OIDC token file.

If the preceding three environment variables are specified, the Credentials tool uses the environment variables to call the AssumeRoleWithOIDC operation of STS to obtain an STS token as the default credential.

3. Obtain the credential information from a configuration file

If no credentials are found in the previous step, the Credentials tool obtains the credential information from a configuration file. The path of the configuration file varies based on the operating system:

Linux: ~/.alibabacloud/credentials

Windows: C:\Users\USER_NAME\.alibabacloud\credentials

You can also specify the configuration file path by configuring the ALIBABA_CLOUD_CREDENTIALS_FILE environment variable. If the configuration file exists, the application initializes a Credentials client by using the credential information that is specified by default in the configuration file. You can also configure the ALIBABA_CLOUD_PROFILE environment variable to modify the default credential information that is read.

[default]                          
type = access_key                  
access_key_id = foo                
access_key_secret = bar            

4. Obtain the credential information by using the RAM role of an ECS instance

If no credentials are found in the previous step, the Credentials tool obtains the value of the ALIBABA_CLOUD_ECS_METADATA environment variable that specifies the RAM role name of an ECS instance. If the RAM role exists, the application obtains an STS token of the RAM role as the default credential by using the metadata server of ECS.

5. Obtain the credential information based on a URI

If no credentials are found in the previous step, the Credentials tool obtains the value of the ALIBABA_CLOUD_CREDENTIALS_URI environment variable. If the environment variable is specified, the application sets the value as the URI based on which the Credentials tool obtains a temporary security credential.

Protect credential information

Credential leaks may expose the system to attacks. This is one of the main threats to cloud services. To prevent the leaks of plaintext credential information and reduce security risks, you can use the following solutions:

  1. We recommend that you use the RAM role of an ECS instance or an STS token.

  2. We recommend that you use the default credential provider chain and record the credential information in environment variables or a configuration file.

  3. To use an explicit initialization method to initialize a Credentials client, we recommend that you use system properties or environment variables to record the credential information and obtain the credential information by using the process.env object.

import Credential, { Config } from '@alicloud/credentials';

const config: Config = {
	type: 'access_key',                 
	accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,         
	accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET, 
}
const cred = new Credential(config);
let accessKeyId: string = await cred.getAccessKeyId();
let accessKeySecret: string = await cred.getAccessKeySecret();
let type: string = cred.getType();

Switch between credentials

You can use the following method to use different credentials to call different API operations in your application:

Use multiple Credentials clients

Initialize multiple Credentials clients to pass different credentials to different request clients.

import Credential, { Config } from '@alicloud/credentials';
import * as process from 'process';

const config1: Config = {
    type: 'access_key',
    accessKeyId: '<ALIBABA_CLOUD_ACCESS_KEY_ID>',
    accessKeySecret: '<ALIBABA_CLOUD_ACCESS_KEY_SECRET>',
}
const cred1 = new Credential(config1);

const config2: Config = {
    type: 'access_key',
    accessKeyId: '<ALIBABA_CLOUD_ACCESS_KEY_ID>',
    accessKeySecret: '<ALIBABA_CLOUD_ACCESS_KEY_SECRET>',
}
const cred = new Credential(config2);

References