通过配置Credentials实现OpenAPI安全调用（Node.js SDK）-阿里云SDK(Alibaba Cloud SDK)-阿里云帮助中心

在使用阿里云SDK时，凭据信息（例如AccessKey、STS Token等）由Credentials工具统一管理。本文将为您介绍Credentials工具支持的凭据类型及其配置方法，帮助您快速掌握Credentials工具的使用。

背景信息

凭据是指用户证明其身份的一组信息。用户在系统中进行登录时，需要提供正确的凭据才能验证身份。常见的凭据类型有：

阿里云主账号和RAM用户的永久凭据 AccessKey（简称AK）是由AccessKey ID和AccessKey Secret组成的密钥对。
阿里云RAM角色的STS临时访问Token，简称STS Token。它是可以自定义时效和访问权限的临时身份凭据，详情请参见什么是STS。
Bearer Token。它是一种身份验证和授权的令牌类型。

前提条件

使用Credentials工具要求Node.js 环境版本 >= 8.5.0。
使用V2.0代系的阿里云SDK，详情请参见通过IDE使用阿里云Node.js SDK。

安装Credentials工具

使用npm下载安装。

npm install @alicloud/credentials

使用最新发布Credentials依赖包，确保所有凭证支持。版本列表请参见Releases · aliyun/credentials-nodejs · GitHub。

Credentials工具配置参数介绍

Credentials工具的配置参数定义在@alicloud/credentials模块的Config 构造函数中，凭据类型由必填参数type指定。确定凭据类型后，需根据该凭据类型选择相应的参数。下表将详细介绍type的取值范围及各类凭据类型所支持的参数。其中，√表示必填参数，-表示可选参数，×表示不支持参数。

说明

未在下表中列出的凭据类型及参数表示不建议继续使用。

type	access_key	sts	ram_role_arn	ecs_ram_role	oidc_role_arn	credentials_uri	bearer
accessKeyId：访问凭据ID。	√	√	√	×	×	×	×
accessKeySecret：访问凭据密钥。	√	√	√	×	×	×	×
securityToken：STS Token。	×	√	-	×	×	×	×
roleArn：RAM角色的ARN。	×	×	√	×	√	×	×
roleSessionName：自定义会话名称，默认格式为`credentials-nodejs-当前时间的时间戳`。	×	×	-	×	-	×	×
roleName：RAM角色名称。	×	×	×	-	×	×	×
disableIMDSv1：是否强制使用加固模式，默认值为`false`。	×	×	×	-	×	×	×
bearerToken：bearer token。	×	×	×	×	×	×	√
policy：自定义权限策略。	×	×	-	×	-	×	×
roleSessionExpiration：会话过期时间，默认3600秒。	×	×	-	×	-	×	×
oidcProviderArn：OIDC提供商ARN。	×	×	×	×	√	×	×
oidcTokenFilePath：OIDC Token文件路径。	×	×	×	×	√	×	×
externalId：角色外部 ID，主要功能是防止混淆代理人问题。更多信息，请参见使用ExternalId防止混淆代理人问题。	×	×	-	×	×	×	×
credentialsURI：凭证的URI。	×	×	×	×	×	√	×
STSEndpoint：STS的服务接入点，支持VPC服务接入点和公网服务接入点，可选的值请参见服务接入点，默认值为`sts.aliyuncs.com`。	×	×	-	×	-	×	×
timeout：HTTP请求的读超时时间，默认值为5000毫秒。	×	×	-	-	-	-	×
connectTimeout：HTTP请求的连接超时时间，默认值为10000毫秒。	×	×	-	-	-	-	×

初始化凭据客户端

前文已介绍Credentials工具所支持的凭据类型及其配置参数，接下来将通过详细的代码示例进一步说明，您可以根据具体情况选择适合的使用方式。

重要

在项目中使用明文AccessKey，容易因代码仓库权限管理不当造成AccessKey泄露，会威胁该账号下所有资源的安全。建议通过环境变量、配置文件等方式保存AccessKey。
在使用Credentials工具时，建议采用单例模式。这一做法能够启用Credentials工具内置的凭据缓存功能，有效防止因多次调用接口而导致的限流问题，以及因创建多个实例而引起的资源浪费问题。详细信息请参见Session类型凭据自动刷新机制。

方式一：使用默认凭据链

当您在初始化凭据客户端不传入任何参数时，Credentials工具会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。

Node.js

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

// 不指定参数
const credentialClient = new Credential.default();

const credential = credentialClient.getCredential();
credential.then(credential => {
    console.log(credential);
});

Typescript

import Credential from '@alicloud/credentials';

const credential = new Credential();

credential.getCredential().then(credential => {
    console.log(credential);
});

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

Node.js

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() {
    // 使用默认凭证初始化Credentials Client。
    const credentialClient = new Credential.default();
    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    });
    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((result) => {
        console.log(JSON.stringify(result.body));
    });
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
import Credential from '@alicloud/credentials';

export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        // 使用默认凭据初始化Credentials Client
        let credential = new Credential();
        let config = new $OpenApi.Config({
            credential: credential, // 使用Credentials配置凭证。
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}

const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

方式二：使用AK

Credentials工具将使用您提供的AccessKey作为访问凭据。

警告

阿里云账号（主账号）拥有资源的全部权限，AK一旦泄露，会给系统带来巨大风险，不建议使用。

推荐使用最小化授权的RAM用户的AK。

Node.js

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

const credentialsConfig = new Credential.Config({
    // 凭证类型。
    type: 'access_key',
    // 设置accessKeyId值，此处已从环境变量中获取accessKeyId为例。
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // 设置accessKeySecret值，此处已从环境变量中获取accessKeySecret为例。
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
});
const credentialClient = new Credential.default(credentialsConfig);

Typescript

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

const credentialsConfig  = new Config({
    // 凭证类型。
    type: 'access_key',
    // 设置accessKeyId值，此处已从环境变量中获取accessKeyId为例。
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // 设置accessKeySecret值，此处已从环境变量中获取accessKeySecret为例。
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
});
const credentialClient = new Credential(credentialsConfig);

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

Node.js

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({
        // 凭证类型。
        type: 'access_key',
        // 设置accessKeyId值，此处已从环境变量中获取accessKeyId为例。
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
        // 设置accessKeySecret值，此处已从环境变量中获取accessKeySecret为例。
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    });
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config();
    ecsConfig.endpoint = 'ecs.cn-hangzhou.aliyuncs.com'; // 配置云产品服务接入地址（endpoint）。
    ecsConfig.credential = credentialClient; // 使用Credentials配置凭证。
    const ecsClient = new Ecs20140526.default(ecsConfig);
    
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body.regions);
    });
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            // 凭证类型。
            type: 'access_key',
            // 设置accessKeyId值，此处已从环境变量中获取accessKeyId为例。
            accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
            // 设置accessKeySecret值，此处已从环境变量中获取accessKeySecret为例。
            accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // 使用Credentials配置凭证。
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}

const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

方式三：使用STS Token

Credentials工具将使用您提供的静态STS Token作为访问凭据。

Node.js

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

const credentialsConfig = new Credential.Config({
    type: 'sts',
    // 设置accessKeyId值，此处已从环境变量中获取accessKeyId为例。
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // 设置accessKeySecret值，此处已从环境变量中获取accessKeySecret为例。
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // 设置securityToken值，此处已从环境变量中获取securityToken为例。
    securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
});
const cred = new Credential.default(credentialsConfig);

Typescript

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

const credentialsConfig = new Config({
    // 凭证类型。
    type: 'access_key',
    // 设置accessKeyId值，此处已从环境变量中获取accessKeyId为例。
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    // 设置accessKeySecret值，此处已从环境变量中获取accessKeySecret为例。
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // 设置securityToken值，此处已从环境变量中获取securityToken为例。
    securityToken: process.env.ALIBABA_CLOUD_SECURITY_TOKEN,
});
const credentialClient = new Credential(credentialsConfig);

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK和STS SDK。

Node.js

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 assumeRole() {
    // 创建STS client，获取STS token
    const stsConfig = new OpenApi.Config({
        endpoint: 'sts.cn-hangzhou.aliyuncs.com', // STS服务接入地址（endpoint）。
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID, // 从环境变量中获取 accessKeyId
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET, // 从环境变量中获取 accessKeySecret
    });
    const stsClient = new Sts20150401.default(stsConfig);
    const assumeRoleRequest = new Sts20150401.AssumeRoleRequest({
        durationSeconds: 3600, // STS token有效时间
        roleArn: '<RoleArn>', // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置roleArn 
        roleSessionName: '<RoleSessionName>', // 自定义角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName 
        policy: '', // 权限策略集合，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    });
    try {
        const assumeRoleResponsePromise = await stsClient.assumeRole(assumeRoleRequest);
        const assumeRoleResponseBodyCredentials = assumeRoleResponsePromise.body.credentials;
        return {
            accessKeyId: assumeRoleResponseBodyCredentials.accessKeyId,
            accessKeySecret: assumeRoleResponseBodyCredentials.accessKeySecret,
            securityToken: assumeRoleResponseBodyCredentials.securityToken,
        };
    } catch (error) {
        console.error('AssumeRole 请求失败:', error);
        throw error;
    }
}
async function main() {
    const stsToken = await assumeRole()
    const credentialsConfig = new Credential.Config({
        // 凭证类型。
        type: 'sts',
        accessKeyId: stsToken.accessKeyId,
        accessKeySecret: stsToken.accessKeySecret,
        securityToken: stsToken.securityToken,
    });
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    })

    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // 调用DescribeRegions接口并获得响应。
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body.regions);
    });
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Sts20150401, * as $Sts20150401 from '@alicloud/sts20150401';
import OpenApi, { Config } from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';
import Credential, { Config as CredentialConfig } from '@alicloud/credentials';

async function assumeRole() {
    // 创建STS client，获取STS token
    const stsConfig = new Config({
        endpoint: 'sts.cn-hangzhou.aliyuncs.com', // STS服务接入地址（endpoint）。
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID, // 从环境变量中获取 accessKeyId
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET, // 从环境变量中获取 accessKeySecret
    });
    const stsClient = new Sts20150401(stsConfig);
    const assumeRoleRequest = new $Sts20150401.AssumeRoleRequest({
        durationSeconds: 3600, // STS token有效时间
        roleArn: '<RoleArn>', // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置roleArn  
        roleSessionName: '<RoleSessionName>', // 自定义角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName 
        policy: '', // 权限策略集合，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    });
    try {
        const assumeRoleResponsePromise = await stsClient.assumeRole(assumeRoleRequest);
        const assumeRoleResponseBodyCredentials = assumeRoleResponsePromise.body?.credentials;
        return {
            accessKeyId: assumeRoleResponseBodyCredentials?.accessKeyId,
            accessKeySecret: assumeRoleResponseBodyCredentials?.accessKeySecret,
            securityToken: assumeRoleResponseBodyCredentials?.securityToken,
        };
    } catch (error) {
        console.error('AssumeRole 请求失败:', error);
        throw error;
    }
}
async function main() {
    const stsToken = await assumeRole()
    const credentialsConfig = new CredentialConfig({
        // 凭证类型。
        type: 'sts',
        accessKeyId: stsToken.accessKeyId,
        accessKeySecret: stsToken.accessKeySecret,
        securityToken: stsToken.securityToken,
    });
    const credentialClient = new Credential(credentialsConfig);

    const ecsConfig = new Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    })

    const ecsClient = new Ecs20140526(ecsConfig);
    const describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest();
    const runtime = new $Util.RuntimeOptions();
    // 调用DescribeRegions接口并获得响应。
    ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime).then((response) => {
        console.log(response.body?.regions);
    });
}

main().catch(console.error);

方式四：使用AK及RamRoleArn

该方式底层实现是STS Token。通过指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具可以帮助开发者前往STS换取STS Token。您也可以通过为policy赋值来限制RAM角色到一个更小的权限集合。

Node.js

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,
    // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置roleArn
    roleArn: '<RoleArn>',
    // 自定义角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
    roleSessionName: '<RoleSessionName>',
    // 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy: '<Policy>',
    roleSessionExpiration: 3600,
});
const cred = new Credential.default(credentialsConfig);

Typescript

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

const credentialsConfig = new Config({
    type: 'ram_role_arn',
    accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
    accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
    // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置roleArn
    roleArn: '<RoleArn>',
    // 自定义角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
    roleSessionName: '<RoleSessionName>',
    // 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
    policy: '<Policy>',
    roleSessionExpiration: 3600,
});
const credentialClient = new Credential(credentialsConfig);

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

Node.js

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({
        // 凭证类型。
        type: 'ram_role_arn',
        // 设置为AccessKey ID值。
        accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
        // 设置为AccessKey Secret值。
        accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
        // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置roleArn
        roleArn: '<RoleArn>',
        // 自定义角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
        roleSessionName: '<RoleSessionName>',
        // 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
        policy: '<Policy>',
        roleSessionExpiration: 3600,
    });
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    });

    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // 调用DescribeRegions接口并获得响应。
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            type: 'ram_role_arn',
            accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
            accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
            // 要扮演的RAM角色ARN，示例值：acs:ram::123456789012****:role/adminrole，可以通过环境变量ALIBABA_CLOUD_ROLE_ARN设置roleArn
            roleArn: '<RoleArn>',
            // 自定义角色会话名称，可以通过环境变量ALIBABA_CLOUD_ROLE_SESSION_NAME设置RoleSessionName
            roleSessionName: '<RoleSessionName>',
            // 设置更小的权限策略，非必填。示例值：{"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
            policy: '<Policy>',
            roleSessionExpiration: 3600,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // 使用Credentials配置凭证。
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}

const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

方式五：使用ECS实例RAM角色

ECS和ECI实例均支持绑定实例RAM角色，运行于实例中的程序可通过Credentials工具自动获取该角色的STS Token，从而完成凭据客户端的初始化。

Credentials工具将默认采用加固模式（IMDSv2）访问ECS的元数据服务（Meta Data Server），在使用加固模式时若发生异常，将使用普通模式兜底来获取访问凭据。您也可以通过设置参数disableIMDSv1或环境变量ALIBABA_CLOUD_IMDSV1_DISABLE，执行不同的异常处理逻辑：

当值为false（默认）时，会使用普通模式继续获取访问凭据。
当值为true时，表示只能使用加固模式获取访问凭据，会抛出异常。

服务端是否支持IMDSv2，取决于您在服务器的配置。

另外，您可以通过配置环境变量ALIBABA_CLOUD_ECS_METADATA_DISABLED=true来关闭ECS元数据的凭证访问。

说明

使用加固模式获取临时身份凭证时，credentials的版本不低于2.3.1。
关于ECS实例元数据的介绍，请参见实例元数据。
如何为ECS和ECI实例授予RAM角色，具体操作请参见步骤一：创建RAM角色和为ECI实例授予实例RAM角色。

Node.js

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

const credentialsConfig = new Credential.Config({
    type: 'ecs_ram_role',
    // 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置roleName
    roleName: '<RoleName>',
    // 选填，默认值：false。true：表示强制使用加固模式。false：系统将首先尝试在加固模式下获取凭据。如果失败，则会切换到普通模式（IMDSv1）进行尝试
    // disableIMDSv1: true,
});
const cred = new Credential.default(credentialsConfig);

Typescript

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

const credentialsConfig = new Config({
    type: 'ecs_ram_role',
    // 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置roleName
    roleName: '<RoleName>',
    // 选填，默认值：false。true：表示强制使用加固模式。false：系统将首先尝试在加固模式下获取凭据。如果失败，则会切换到普通模式（IMDSv1）进行尝试
    // disableIMDSv1: true,
});
const credentialClient = new Credential(credentialsConfig);

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

Node.js

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({
        // 凭证类型。
        type: 'ecs_ram_role',
        // 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置roleName
        roleName: '<RoleName>',
    });
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    });

    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // 调用DescribeRegions接口并获得响应。
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new Config({
            type: 'ecs_ram_role',
            // 选填，该ECS角色的角色名称，不填会自动获取，但是建议加上以减少请求次数，可以通过环境变量ALIBABA_CLOUD_ECS_METADATA设置roleName
            roleName: '<RoleName>',
            // 选填，默认值：false。true：表示强制使用加固模式。false：系统将首先尝试在加固模式下获取凭据。如果失败，则会切换到普通模式（IMDSv1）进行尝试
            // disableIMDSv1: true,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // 使用Credentials配置凭证。
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}

const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

方式六：使用OIDCRoleArn

若您使用OIDC认证协议，并已创建OIDC身份提供商的RAM角色，您可以通过Credentials工具传入OIDC身份提供商ARN、OIDC Token及RAM角色ARN，系统将自动调用AssumeRoleWithOIDC接口获取RAM角色的STS Token，并将该STS Token作为访问凭据。通过此方式获取的凭据支持自动刷新，详情请参见Session类型凭据自动刷新机制。例如当您的应用程序运行于已启用RRSA功能的ACK集群中时，Credentials工具支持通过读取Pod环境变量中的OIDC配置信息，调用AssumeRoleWithOIDC接口获取服务角色的STS Token，从而利用该STS Token访问阿里云相关服务。

Node.js

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

const credentialsConfig = new Credential.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>',
    // 设置session过期时间
    roleSessionExpiration: 3600,
});
const credentialClient = new Credential.default(credentialsConfig);

Typescript

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

const credentialsConfig = new 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>',
    // 设置session过期时间
    roleSessionExpiration: 3600,
});
const credentialClient = new Credential(credentialsConfig);

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

Node.js

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({
        // 凭证类型。
        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>',
        // 设置session过期时间
        roleSessionExpiration: 3600,
    });
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    });

    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // 调用DescribeRegions接口并获得响应。
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        const credentialsConfig = new 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>',
            // 设置session过期时间
            roleSessionExpiration: 3600,
        });
        const credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // 使用Credentials配置凭证。
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}

const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

方式七：使用URI凭据

通过封装STS服务并对外暴露服务的URI，外部服务能够通过该URI获取STS Token，从而有效降低AK等敏感信息的暴露风险。Credentials工具支持通过访问您所提供的URI来获取STS Token，并将该STS Token作为访问凭据。通过此方式获取的凭据支持自动刷新，详情请参见Session类型凭据自动刷新机制。

Node.js

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

const config = new Credential.Config({
    type: 'credentials_uri',
    // 获取凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentialsUri
    credentialsURI: '<CredentialsUri>',
});
const credentialClient = new Credential(config);

Typescript

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

const credentialsConfig = new Config({
    type: 'credentials_uri',
    // 获取凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentialsUri
    credentialsURI: '<CredentialsUri>',
});
const credentialClient = new Credential(credentialsConfig);

该地址必须满足如下条件：

响应状态码为200

响应体为如下的结构

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

接口调用方法

本示例以调用云服务器ECS的DescribeRegions接口为例，因此需先安装ECS SDK。

Node.js

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({
        // 凭证类型。
        type: 'credentials_uri',
        // 获取凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentialsUri
        credentialsURI: '<CredentialsUri>',
    });
    const credentialClient = new Credential.default(credentialsConfig);

    const ecsConfig = new OpenApi.Config({
        endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        credential: credentialClient, // 使用Credentials配置凭证。
    });

    const ecsClient = new Ecs20140526.default(ecsConfig);
    const describeRegionsRequest = new Ecs20140526.DescribeRegionsRequest();
    const runtime = new Util.RuntimeOptions();
    // 调用DescribeRegions接口并获得响应。
    const response = ecsClient.describeRegionsWithOptions(describeRegionsRequest, runtime);
    console.log((await response).body.regions);
}

main().catch(console.error);

Typescript

import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {
    static async main(): Promise<$Ecs20140526.DescribeRegionsResponse> {
        let credentialsConfig = new Config({
            type: 'credentials_uri',
            // 获取凭证的 URI，格式为http://local_or_remote_uri/，可以通过环境变量ALIBABA_CLOUD_CREDENTIALS_URI设置credentialsUri
            credentialsURI: '<CredentialsUri>',
        });
        let credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // 使用Credentials配置凭证。
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new Ecs20140526(config);
        let describeRegionsRequest = new $Ecs20140526.DescribeRegionsRequest({});
        let runtime = new $Util.RuntimeOptions({});
        return await client.describeRegionsWithOptions(describeRegionsRequest, runtime);
    }
}

const response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

方式八：使用Bearer Token

目前只有云呼叫中心CCC这款产品支持Bearer Token。

Node.js

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

const config = new Credential.Config({
    type: 'bearer',
    // 填入您的Bearer Token
    bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(config);

Typescript

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

const credentialsConfig = new Config({
    type: 'bearer',
    // 填入您的Bearer Token
    bearerToken: '<BearerToken>',
});
const credentialClient = new Credential(credentialsConfig);

接口调用方法

本示例以调用呼叫中心CCC的GetInstance接口为例，因此需先安装CCC SDK。

Node.js

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

async function main() {
    let credentialsConfig = new Credential.Config({
        // 凭证类型。
        type: 'bearer',
        // 填入您的Bearer Token
        bearerToken: '<BearerToken>',
    });
    let credentialClient = new Credential.default(credentialsConfig);

    let config = new OpenApi.Config({
        endpoint: 'ccc.cn-shanghai.aliyuncs.com',
        credential: credentialClient
    });

    let client = new CCC20200701.default(config);
    let getInstanceRequest = new CCC20200701.GetInstanceRequest({
        instanceId: 'ccc-test',
    });
    let runtime = new Util.RuntimeOptions({});
    let response = client.getInstanceWithOptions(getInstanceRequest, runtime);
    console.log((await response).body);
}

main().catch(console.error);

Typescript

import ccc20200701, * as $ccc20200701 from '@alicloud/ccc20200701';
import Credential, { Config } from '@alicloud/credentials';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import Util, * as $Util from '@alicloud/tea-util';

export default class Client {
    static async main(): Promise<$ccc20200701.GetInstanceResponse> {
        let credentialsConfig = new Config({
            type: 'bearer',
            // 填入您的Bearer Token
            bearerToken: '<BearerToken>',
        });
        let credentialClient = new Credential(credentialsConfig);
        let config = new $OpenApi.Config({
            credential: credentialClient, // 使用Credentials配置凭证。
            endpoint: 'ccc.cn-shanghai.aliyuncs.com', // 配置云产品服务接入地址（endpoint）。
        });

        let client = new ccc20200701(config);
        let GetInstanceRequest = new $ccc20200701.GetInstanceRequest({
            instanceId: 'ccc-test',
        });
        let runtime = new $Util.RuntimeOptions({});
        return await client.getInstanceWithOptions(GetInstanceRequest, runtime);
    }
}

let response = Client.main();
response.then(res => {
    console.log(res.body?.regions);
});

默认凭据链

当您的程序开发环境和生产环境采用不同的凭据类型，常见做法是在代码中获取当前环境信息，编写获取不同凭据的分支代码。借助Credentials工具的默认凭据链，您可以用同一套代码，通过程序之外的配置来控制不同环境下的凭据获取方式。当您在不传入参数的情况下，直接使用new Credential()初始化凭据客户端时，阿里云SDK将会尝试按照如下顺序查找相关凭据信息。

1. 使用环境变量

如果未找到系统属性中的凭据信息，Credentials工具会继续检查环境变量。

如果 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 均存在且非空，则使用它们作为默认凭据。
如果同时设置了 ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET 和 ALIBABA_CLOUD_SECURITY_TOKEN，则使用STS Token作为默认凭据。

2. 使用OIDC RAM角色

如果仍未获取到凭据信息，Credentials工具会检查以下与OIDC RAM角色相关的环境变量：

ALIBABA_CLOUD_ROLE_ARN：RAM角色名称ARN。
ALIBABA_CLOUD_OIDC_PROVIDER_ARN：OIDC提供商ARN。
ALIBABA_CLOUD_OIDC_TOKEN_FILE：OIDC Token文件路径。

如果以上三个环境变量均存在且非空，Credentials将会使用变量内容调用STS服务的AssumeRoleWithOIDC接口换取STS Token作为默认凭据。

3. 使用config.json配置文件

如果仍未获取到凭据信息，Credentials工具会尝试从默认路径加载config.json配置文件，并获取指定的凭据作为默认凭据。该文件的默认完整路径如下：

Linux/Mac：~/.aliyun/config.json
Windows： C:\Users\USER_NAME\.aliyun\config.json

如果您需要通过此方式配置凭据，您可以使用阿里云CLI工具配置凭据，或手动在相应路径下创建config.json配置文件。内容格式示例如下：

{
  "current": "<PROFILE_NAME>",
  "profiles": [
    {
      "name": "<PROFILE_NAME>",
      "mode": "AK",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
    },
    {
      "name": "<PROFILE_NAME1>",
      "mode": "StsToken",
      "access_key_id": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "sts_token": "<SECURITY_TOKEN>"
    },
    {
      "name":"<PROFILE_NAME2>",
      "mode":"RamRoleArn",
      "access_key_id":"<ALIBABA_CLOUD_ACCESS_KEY_ID>",
      "access_key_secret":"<ALIBABA_CLOUD_ACCESS_KEY_SECRET>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    },
    {
      "name":"<PROFILE_NAME3>",
      "mode":"EcsRamRole",
      "ram_role_name":"<RAM_ROLE_ARN>"
    },
    {
      "name":"<PROFILE_NAME4>",
      "mode":"OIDC",
      "oidc_provider_arn":"<OIDC_PROVIDER_ARN>",
      "oidc_token_file":"<OIDC_TOKEN_FILE>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    },
    {
      "name":"<PROFILE_NAME5>",
      "mode":"ChainableRamRoleArn",
      "source_profile":"<PROFILE_NAME>",
      "ram_role_arn":"<ROLE_ARN>",
      "ram_session_name":"<ROLE_SESSION_NAME>",
      "expired_seconds":3600
    }
  ]
}

参数名称

参数介绍

current

指定凭据名称以获取相应的凭据配置信息，其值为profiles中参数name的值。默认情况下，系统优先使用环境变量 ALIBABA_CLOUD_PROFILE 指定的凭据名称；若该环境变量未配置，则将使用current指定的凭据名称。

profiles

凭据信息集合。通过参数mode指定凭据的类型：

AK：使用用户的AccessKey作为凭据信息；
StsToken：使用STS Token作为凭据信息；
RamRoleArn：通过RAM用户扮演RAM角色获取凭证信息。
EcsRamRole：通过实例元数据获取凭据信息；
OIDC：通过OIDC身份提供商ARN、OIDC Token和RAM角色ARN获取凭据信息；
ChainableRamRoleArn：采用角色链的方式，通过source_profile指定profiles中其他凭据的名称，以重新获取新的凭据信息。

4. 使用ECS实例RAM角色

如果未找到更高优先级的凭据信息，Credentials会尝试通过ECS实例绑定的RAM角色获取凭据。默认情况下，Credentials会使用加固模式（IMDSv2）访问ECS的元数据服务（Meta Data Server），以获取ECS实例RAM角色的STS Token作为默认凭据信息。程序会自动访问ECS的元数据服务拿到RoleName信息，再去获取凭证，也就是两次请求。若想减少一次请求，可以直接在环境变量中配置 ALIBABA_CLOUD_ECS_METADATA 来指定实例RAM角色名称。在使用加固模式时若发生异常，将使用普通模式兜底来获取访问凭据。您也可以通过设置环境变量ALIBABA_CLOUD_IMDSV1_DISABLE，执行不同的异常处理逻辑：

当值为false时，会使用普通模式继续获取访问凭据。
当值为true时，表示只能使用加固模式获取访问凭据，会抛出异常。

服务端是否支持IMDSv2，取决于您在服务器的配置。

另外，您可以通过配置环境变量ALIBABA_CLOUD_ECS_METADATA_DISABLED=true来关闭ECS元数据的凭证访问。

说明

关于ECS实例元数据的介绍，请参见实例元数据。
如何为ECS和ECI实例授予RAM角色，具体操作请参见步骤一：创建RAM角色和为ECI实例授予实例RAM角色。

5. 使用Credentials工具URI

如果仍未获取到凭据信息，Credentials工具会检查环境变量 ALIBABA_CLOUD_CREDENTIALS_URI，如果该变量存在且指向一个有效的URI地址，Credentials通过访问该URI来获取STS Token作为默认凭据。

Session类型凭据自动刷新机制

Session类型凭据包含ram_role_arn、ecs_ram_role、oidc_role_arn以及credentials_uri，该类型凭据在Credentials工具中内置了凭据自动刷新机制。当凭据客户端首次获取凭据后，Credentials工具会将获取的凭据信息保存至缓存中。在后续使用过程中，同一凭据客户端实例将自动从缓存中提取凭据；若缓存中的凭据信息已过期，则凭据客户端实例将重新获取凭据，并更新缓存中的值。

说明

对于ecs_ram_role类型凭据，Credentials工具将会在缓存中的值过期前15分钟进行提前刷新。

下面将采用单例模式创建凭据客户端，通过多个时间段获取凭据来验证凭据刷新机制，并通过调用OpenAPI确保所获取的凭据处于可用状态。

Node.js

const Credential = require('@alicloud/credentials');
const Ecs20140526 = require('@alicloud/ecs20140526');
const { Config } = require('@alicloud/openapi-client');
const { RuntimeOptions } = require('@alicloud/tea-util');

// 获取环境变量
const accessKeyId = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
const accessKeySecret = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
const roleArn = process.env.ALIBABA_CLOUD_ROLE_ARN;

/**
 * Credential 单例类，用于管理阿里云凭证实例。
 */
class CredentialClient {
    constructor() {
        if (!CredentialClient.instance) {
            var credentialsConfig = new Credential.Config({
                type: 'ram_role_arn',
                accessKeyId: accessKeyId,
                accessKeySecret: accessKeySecret,
                roleArn: roleArn,
                roleSessionName: 'RoleSessionNameTest',
                roleSessionExpiration: 3600,
            });
            this.credentialsClient = new Credential.default(credentialsConfig);
            CredentialClient.instance = this;
        }

        return CredentialClient.instance;
    }

    static getInstance() {
        return new CredentialClient().credentialsClient;
    }
}

/**
 * ECS Client 单例类，用于管理 ECS 客户端实例。
 */
class EcsClient {
    constructor(credentialClient) {
        if (!EcsClient.instance) {
            const config = new Config({
                endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
                credential: credentialClient
            });

            this.ecsClient = new Ecs20140526.default(config);
            EcsClient.instance = this;
        }

        return EcsClient.instance;
    }

    static getInstance(credentialClient) {
        return new EcsClient(credentialClient).ecsClient;
    }
}

/**
 * 执行任务逻辑
 */
async function executeTask() {
    try {
        const credentialClient = CredentialClient.getInstance();
        const credential = await credentialClient.getCredential();
        console.log(new Date());
        console.log(`AK ID: ${credential.accessKeyId}`);
        console.log(`AK Secret: ${credential.accessKeySecret}`);
        console.log(`STS Token: ${credential.securityToken}`);

        // 这里以调用ECS接口为例验证凭据是否可用，您可根据实际情况修改
        const ecsClient = EcsClient.getInstance(credentialClient);
        const request = new Ecs20140526.DescribeRegionsRequest();
        const runtime = new RuntimeOptions({});
        const response = await ecsClient.describeRegionsWithOptions(request, runtime);
        console.log(`Invoke result: ${response.statusCode}`);
    } catch (error) {
        throw new Error(`ECS client execution failed: ${error.message}`, { cause: error });
    }
}

/**
 * 使用定时器调度任务执行
 */
function scheduleTasks() {
    // 立即执行一次
    executeTask();
    // 设置后续任务延迟执行
    setTimeout(executeTask, 600 * 1000); // 第二次：600秒后
    setTimeout(executeTask, 4200 * 1000); // 第三次：4200秒后
    setTimeout(executeTask, 4300 * 1000); // 第四次：4300秒后
}

// 启动任务调度
scheduleTasks();

Typescript

import Credential, { Config as CredentialsConfig }  from '@alicloud/credentials';
import Ecs20140526, * as $Ecs20140526 from '@alicloud/ecs20140526';
import { Config } from '@alicloud/openapi-client';
import { RuntimeOptions } from '@alicloud/tea-util';

// 获取环境变量
const accessKeyId: string | undefined = process.env.ALIBABA_CLOUD_ACCESS_KEY_ID;
const accessKeySecret: string | undefined = process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET;
const roleArn: string | undefined = process.env.ALIBABA_CLOUD_ROLE_ARN;

if (!accessKeyId || !accessKeySecret || !roleArn) {
    throw new Error('Missing required environment variables.');
}

/**
 * Credential 单例类，用于管理阿里云凭证实例。
 */
class CredentialClient {
    private static instance: CredentialClient;

    private readonly credentialsClient: InstanceType<typeof Credential>;

    private constructor() {
        const credentialsConfig = new CredentialsConfig({
            type: 'ram_role_arn',
            accessKeyId,
            accessKeySecret,
            roleArn,
            roleSessionName: 'RoleSessionNameTest',
            roleSessionExpiration: 3600,
        });

        this.credentialsClient = new Credential(credentialsConfig);
    }

    static getInstance(): InstanceType<typeof Credential> {
        if (!CredentialClient.instance) {
            CredentialClient.instance = new CredentialClient();
        }
        return CredentialClient.instance.credentialsClient;
    }
}

/**
 * ECS Client 单例类，用于管理 ECS 客户端实例。
 */
class EcsClient {
    private static instance: EcsClient;

    private readonly ecsClient: InstanceType<typeof Ecs20140526>;

    private constructor(credentialClient: InstanceType<typeof Credential>) {
        const config = new Config({
            endpoint: 'ecs.cn-hangzhou.aliyuncs.com',
            credential: credentialClient
        });

        this.ecsClient = new Ecs20140526(config);
    }

    static getInstance(credentialClient: InstanceType<typeof Credential>): InstanceType<typeof Ecs20140526> {
        if (!EcsClient.instance) {
            EcsClient.instance = new EcsClient(credentialClient);
        }
        return EcsClient.instance.ecsClient;
    }
}

/**
 * 执行任务逻辑
 */
async function executeTask(): Promise<void> {
    try {
        const credentialClient = CredentialClient.getInstance();
        const credential = await credentialClient.getCredential();

        console.log(new Date());
        console.log(`AK ID: ${credential.accessKeyId}`);
        console.log(`AK Secret: ${credential.accessKeySecret}`);
        console.log(`STS Token: ${credential.securityToken}`);

        // 这里以调用ECS接口为例验证凭据是否可用，您可根据实际情况修改
        const ecsClient = EcsClient.getInstance(credentialClient);
        const request = new $Ecs20140526.DescribeRegionsRequest();
        const runtime = new RuntimeOptions({});
        const response = await ecsClient.describeRegionsWithOptions(request, runtime);
        console.log(`Invoke result: ${response.statusCode}`);
    } catch (error) {
        throw new Error(`ECS client execution failed: ${error}`);
    }
}

/**
 * 使用定时器调度任务执行
 */
function scheduleTasks(): void {
    // 立即执行一次
    executeTask();

    // 设置后续任务延迟执行
    setTimeout(executeTask, 600 * 1000); // 第二次：600秒后
    setTimeout(executeTask, 4200 * 1000); // 第三次：4200秒后
    setTimeout(executeTask, 4300 * 1000); // 第四次：4300秒后
}

// 启动任务调度
scheduleTasks();

根据日志显示结果进行分析：

在第一次调用时，由于未缓存凭据信息，系统根据配置获取凭据信息。获取到凭据后，凭据信息被保存在缓存中。
第二次调用所使用的凭据信息与第一次相同，表明第二次调用是从缓存中提取的凭据信息。
第三次调用时，由于凭据的过期时间（RoleSessionExpiration）被设置为3600秒，而第三次调用发生在第一次调用之后的4200秒，此时缓存中的凭据已过期。因此，SDK依据自动刷新机制重新获取了新的凭据信息，并将新获取的凭据信息再次保存于缓存中。
第四次调用所使用的凭据信息与第三次重新获取的凭据信息一致，这表明缓存中的凭据在过期后已被更新为新的凭据。

管理访问凭证

背景信息

前提条件

安装Credentials工具

Credentials工具配置参数介绍

初始化凭据客户端

方式一：使用默认凭据链

接口调用方法

方式二：使用AK

接口调用方法

方式三：使用STS Token

接口调用方法

方式四：使用AK及RamRoleArn

接口调用方法

方式五：使用ECS实例RAM角色

接口调用方法

方式六：使用OIDCRoleArn

接口调用方法

方式七：使用URI凭据

接口调用方法

方式八：使用Bearer Token

接口调用方法

默认凭据链

1. 使用环境变量

2. 使用OIDC RAM角色

3. 使用config.json配置文件

4. 使用ECS实例RAM角色

5. 使用Credentials工具URI

Session类型凭据自动刷新机制

相关文档