本文介绍如何在 Node.js 应用中集成 IDaaS TypeScript SDK,获取 M2M 客户端令牌。
适用范围
已完成环境准备,并准备好配置文件、凭据来源及目标 scope 的授权。JavaScript 应用使用相同 API。
安装 SDK
在项目目录中安装 Core SDK,以下示例使用 0.1.0-beta.2:
npm install --save-exact --registry=https://registry.npmjs.org/ @cloud-idaas/core-sdk@0.1.0-beta.2
SDK 初始化
init() 自动读取并校验配置,再获取默认 scope 的初始凭据。无参数时读取 CLOUD_IDAAS_CONFIG_PATH 指定的文件,未设置时使用 ~/.cloud_idaas/client-config.json;也可以传入文件绝对路径或配置对象。
以下片段在 async 函数中执行,完整用法见后文示例:
const factory = new IDaaSCredentialProviderFactory();
await factory.init();
// 或:await factory.init('/absolute/path/to/client-config.json');
-
初始化、获取 Provider 和获取令牌均为异步操作,调用时须
await。 -
配置错误或首次取凭据失败会使初始化失败,修复后可重试;只有成功完成初始化才能获取 Provider。
-
初始化成功后,重复
init()保留已有配置。需要切换身份或整份配置时创建新工厂;关闭后的工厂不能重新初始化。
获取 Access Token
通过已初始化的工厂获取 Provider,默认使用配置文件中的 scope:
const provider = await factory.getIDaaSCredentialProvider();
const accessToken = await provider.getAccessToken();
也可以先获取完整凭据对象,再读取令牌属性:
const credential = await provider.getCredential();
const accessToken = credential.accessToken;
Access Token 为 Bearer 类型。scope 的格式为受众标识与权限标识用竖线连接,例如 api.example.com|read:file。如需访问其他已授权的 scope,可调用 factory.getIDaaSCredentialProvider(scope)。在应用中复用工厂和 Provider,并在所有相关请求结束后关闭工厂。
完整代码示例
将以下 TypeScript 代码保存为 app.cts:
import {
IDaaSCredentialProviderFactory,
isIDaaSException,
} from '@cloud-idaas/core-sdk';
async function main(): Promise<void> {
const factory = new IDaaSCredentialProviderFactory();
try {
await factory.init();
const provider = await factory.getIDaaSCredentialProvider();
const accessToken = await provider.getAccessToken();
if (!accessToken) throw new Error('Token 为空');
// 将 accessToken 用于目标资源请求的 Authorization: Bearer 头。
// 不在日志中输出令牌。
console.log('SDK 初始化与令牌获取成功');
} finally {
// 长驻应用应在所有相关请求结束后统一关闭工厂。
await factory.close();
}
}
main().catch((error: unknown) => {
console.error('SDK 调用失败', {
errorCode: isIDaaSException(error) ? error.errorCode : 'UnexpectedError',
});
process.exitCode = 1;
});
安装编译依赖、编译并运行:
npm install --save-dev --save-exact --registry=https://registry.npmjs.org/ typescript@5.9.3 @types/node@20.17.0
npx tsc --module Node16 --moduleResolution Node16 --target ES2022 --strict --outDir dist app.cts
node dist/app.cjs
JavaScript 应用去掉类型标注即可使用相同逻辑。ESM 使用 .mjs 或在 package.json 中设置 type=module;CommonJS 使用 .cjs,并将顶部导入改为:
const { IDaaSCredentialProviderFactory, isIDaaSException } = require('@cloud-idaas/core-sdk');
阿里云 OpenAPI 认证(可选)
使用 PLUGIN 认证时,先按环境准备安装插件并配置权限、端点和 pluginName。在代码顶部增加导入:
import { AlibabaOpenApiCredentialProvider } from '@cloud-idaas/core-alibabacloud-authentication-plugin';
将完整示例中创建工厂的语句替换为以下内容,其余初始化和取令牌逻辑不变:
const factory = new IDaaSCredentialProviderFactory({
plugins: [new AlibabaOpenApiCredentialProvider()],
});
插件必须在同一工厂的 init() 之前注册。插件认证的每次请求只能包含一个受众,不支持 Token Exchange。
令牌交换
令牌交换(RFC 8693)将授权服务器信任的主体令牌交换为目标 scope 的访问令牌,适用于令牌降权和服务间调用。
以下示例保存为 exchange.cts。由可信业务流程提供有效的 IDaaS 用户 Access Token,并通过 IDAAS_SUBJECT_TOKEN 注入示例;该环境变量是示例约定,不是 SDK 自动读取的配置字段。将目标 scope 替换为实际已授权的受众与权限。
import {
IDaaSCredentialProviderFactory,
isIDaaSException,
} from '@cloud-idaas/core-sdk';
async function main(): Promise<void> {
const subjectToken = process.env.IDAAS_SUBJECT_TOKEN;
if (!subjectToken) throw new Error('缺少用于交换的主体令牌');
const factory = new IDaaSCredentialProviderFactory();
try {
await factory.init();
const provider = await factory.getIDaaSCredentialProvider();
const credential = await provider.tokenExchange({
subjectToken,
subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
scope: 'api.example.com|read:file',
});
const accessToken = credential.accessToken;
if (!accessToken) throw new Error('交换后的 Token 为空');
// 将 accessToken 用于目标资源请求,不输出令牌或凭据对象。
console.log('令牌交换成功');
} finally {
await factory.close();
}
}
main().catch((error: unknown) => {
console.error('令牌交换失败', {
errorCode: isIDaaSException(error) ? error.errorCode : 'UnexpectedError',
});
process.exitCode = 1;
});
npx tsc --module Node16 --moduleResolution Node16 --target ES2022 --strict --outDir dist exchange.cts
node dist/exchange.cjs
令牌交换参数说明
|
参数 |
类型 |
必填 |
描述 |
|
subjectToken |
string |
是 |
要交换的主体令牌。 |
|
subjectTokenType |
string |
否 |
默认 |
|
requestedTokenType |
string |
否 |
默认 |
|
scope |
string |
否 |
省略时使用当前 Provider 的 |
|
audience |
string |
否 |
显式指定时须与目标 |
本版令牌交换的接入范围为受信任的 IDaaS 用户 Access Token,目标 scope 只包含一个受众,不提供 actor-token 委托和 resource 扩展的接入支持。返回值为凭据对象,通过 credential.accessToken 读取令牌。
交换结果不写入普通 client_credentials 缓存,后续 getAccessToken() 仍返回原 Provider 的普通令牌;交换结果的使用期限由应用根据 expiresAt 管理,单位为 Unix 秒。