代码集成

更新时间:
复制 MD 格式

本文介绍如何在 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

否

默认 urn:ietf:params:oauth:token-type:access_token。

requestedTokenType

string

否

默认 urn:ietf:params:oauth:token-type:access_token。

scope

string

否

省略时使用当前 Provider 的 scope;显式空字符串会被拒绝。

audience

string

否

显式指定时须与目标 scope 的受众一致。

本版令牌交换的接入范围为受信任的 IDaaS 用户 Access Token,目标 scope 只包含一个受众,不提供 actor-token 委托和 resource 扩展的接入支持。返回值为凭据对象,通过 credential.accessToken 读取令牌。

交换结果不写入普通 client_credentials 缓存,后续 getAccessToken() 仍返回原 Provider 的普通令牌;交换结果的使用期限由应用根据 expiresAt 管理,单位为 Unix 秒。