环境准备

更新时间:
复制 MD 格式

本文介绍使用 IDaaS TypeScript SDK 获取 M2M 客户端令牌前需要完成的环境准备。JavaScript 应用同样适用。

环境要求

  • Node.js 20、22 或 24;TypeScript 应用使用 TypeScript 4.7 或更高版本。

  • 可通过 npm 安装 SDK,运行环境可访问实际的 IDaaS Token 端点。

  • 已创建 M2M 客户端应用,配置对应的凭据或联邦信任,并授予目标受众和权限。

SDK 用于 Node.js 服务端,不适用于浏览器环境或交互式用户登录。

安装 SDK

Core SDK

源码:idaas-typescript-core-sdk;版本:npm。下面示例使用 0.1.0-beta.2,在已有 Node.js 项目目录中执行:

npm install --save-exact --registry=https://registry.npmjs.org/ @cloud-idaas/core-sdk@0.1.0-beta.2

TypeScript 和 ESM 使用 import,CommonJS 使用 require;完整示例见代码集成。

阿里云认证扩展插件

使用阿里云身份凭据调用 EIAM OpenAPI 获取 M2M 客户端令牌时,还需安装认证插件。

源码:idaas-typescript-core-alibabacloud-authentication-plugin;版本:npm。

npm install --save-exact --registry=https://registry.npmjs.org/ @cloud-idaas/core-alibabacloud-authentication-plugin@0.1.0-beta.2

插件需要在工厂初始化前显式注册,注册方式见代码集成中的阿里云 OpenAPI 认证示例。

路径说明

配置文件默认路径为 ~/.cloud_idaas/client-config.json。可通过环境变量指定路径:

export CLOUD_IDAAS_CONFIG_PATH=/absolute/path/to/client-config.json

也可以在初始化时传入文件路径。文件选择优先级从高到低为:

  1. init() 显式传入的路径。

  2. CLOUD_IDAAS_CONFIG_PATH 环境变量。

  3. 默认路径 ~/.cloud_idaas/client-config.json。

选定文件读取或 JSON 解析失败时会报错,不会继续尝试其他路径。也可通过 init(configObject) 直接传入配置对象;SDK 不会从独立环境变量补齐普通配置字段。

配置文件说明

将示例中的实例、客户端应用、端点、受众和权限替换为实际值。openApiEndpoint 仅在插件认证时需要,developerApiEndpoint 是可选的 Developer API 端点。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "openApiEndpoint": "eiam.cn-hangzhou.aliyuncs.com",
  "developerApiEndpoint": "eiam-developerapi.cn-hangzhou.aliyuncs.com",
  "authnConfiguration": {
    "authnMethod": "CLIENT_SECRET_POST",
    "identityType": "CLIENT",
    "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

参数说明

字段

说明

idaasInstanceId

必填,IDaaS EIAM 实例 ID。

clientId

必填,M2M 客户端应用 ID。

issuer

必填,从目标实例的 M2M 应用配置中复制实际 Issuer 端点。

tokenEndpoint

必填,完整的 Token 端点 URL,包含协议和路径。

scope

必填,目标服务端应用的受众与权限,格式为 受众标识|权限标识;多个条目以空格分隔。

openApiEndpoint

插件认证必填,使用目标实例地域的 EIAM OpenAPI 端点。

developerApiEndpoint

可选,目标地域的 EIAM Developer API 端点。

authnConfiguration

必填,认证方式及其所需配置,见下表。

authnConfiguration.identityType

可选,仅支持 CLIENT,表示 M2M 客户端机器身份。

httpConfiguration.connectTimeout

可选,连接超时,默认 5000 毫秒,取值为 2000–60000 的整数。

httpConfiguration.readTimeout

可选,读取超时,默认 10000 毫秒,取值为 2000–60000 的整数。

httpConfiguration.userAgent

可选,自定义请求标识,取值为 1–512 个可打印 ASCII 字符。

failureMode

可选,默认 LENIENT,可在刷新失败时复用尚未过期的凭据;STRICT 在必须同步刷新失败时抛错。两者均不返回过期凭据。

示例中的杭州端点仅作格式参考,实际地域以实例为准。配置文件保存凭据环境变量的名称,真实密钥由运行环境注入。使用 CLIENT_SECRET_POST 时,例如将真实 Client Secret 注入 IDAAS_CLIENT_SECRET。

authnMethod 与认证配置的对应关系

authnMethod

所需的 authnConfiguration 字段

说明

CLIENT_SECRET_BASIC

clientSecretEnvVarName

Client Secret 通过 HTTP Basic 发送。

CLIENT_SECRET_POST

clientSecretEnvVarName

Client Secret 通过表单发送。

CLIENT_SECRET_JWT

clientSecretEnvVarName

使用 Client Secret 进行 HS256 签名。

PRIVATE_KEY_JWT

privateKeyEnvVarName

使用 PEM 私钥签名。

PCA

privateKeyEnvVarName、clientX509Certificate、x509CertChains、applicationFederatedCredentialName

私有 CA 证书认证。

PKCS7

applicationFederatedCredentialName、clientDeployEnvironment

PKCS7 联邦认证。

OIDC

applicationFederatedCredentialName、clientDeployEnvironment

OIDC 联邦认证。

PLUGIN

pluginName

使用初始化前注册的插件;另需顶层 openApiEndpoint。

配置参数示例

选择一种认证方式,将对应的完整 JSON 保存为 client-config.json,并替换占位值。

Client Secret 凭据配置示例

以下使用 CLIENT_SECRET_POST,可按实际认证配置改为 CLIENT_SECRET_BASIC 或 CLIENT_SECRET_JWT。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "authnMethod": "CLIENT_SECRET_POST",
    "identityType": "CLIENT",
    "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

公私钥凭据配置示例

IDAAS_PRIVATE_KEY 的值是未加密 PEM 私钥内容,不是文件路径。RSA 至少 2048 位,使用 RS256;P-256、P-384、P-521 分别使用 ES256、ES384、ES512。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "authnMethod": "PRIVATE_KEY_JWT",
    "identityType": "CLIENT",
    "privateKeyEnvVarName": "IDAAS_PRIVATE_KEY"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

阿里云 ECS 配置示例(PKCS7 联邦认证)

先配置 IDaaS 联邦信任,运行环境需可访问 ECS IMDSv2。AWS EC2 可使用 AWS_EC2 部署环境。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "authnMethod": "PKCS7",
    "identityType": "CLIENT",
    "applicationFederatedCredentialName": "your_pkcs7_federated_credential",
    "clientDeployEnvironment": "ALIBABA_CLOUD_ECS"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Kubernetes OIDC 配置示例

先配置 IDaaS OIDC 联邦信任。内置文件来源支持 Kubernetes、ACK 和 EKS。未指定路径时,默认读取 ServiceAccount Token 文件;也可通过 oidcTokenFilePath 或 oidcTokenFilePathEnvVarName 指定路径。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "authnMethod": "OIDC",
    "identityType": "CLIENT",
    "applicationFederatedCredentialName": "your_oidc_federated_credential",
    "clientDeployEnvironment": "KUBERNETES",
    "oidcTokenFilePath": "/var/run/secrets/kubernetes.io/serviceaccount/token"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

PCA 证书凭据配置示例

私钥与终端证书必须匹配。x509CertChains 为一个字符串,包含 1–5 张中间 CA 证书的完整 PEM 块,各块直接拼接或用换行分隔,不使用逗号。下列证书正文均为占位内容,需替换为真实证书;服务端信任链也须完成配置。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "authnMethod": "PCA",
    "identityType": "CLIENT",
    "applicationFederatedCredentialName": "your_pca_federated_credential",
    "privateKeyEnvVarName": "IDAAS_PRIVATE_KEY",
    "clientX509Certificate": "-----BEGIN CERTIFICATE-----\nREPLACE_WITH_LEAF_BASE64\n-----END CERTIFICATE-----",
    "x509CertChains": "-----BEGIN CERTIFICATE-----\nREPLACE_WITH_INTERMEDIATE_CA_BASE64\n-----END CERTIFICATE-----"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

插件认证配置示例(阿里云 OpenAPI 认证)

使用阿里云身份凭据获取 M2M 客户端令牌时,需安装并注册阿里云认证插件,为运行身份授予目标客户端应用的 eiam:GenerateOauthToken 权限。角色和策略配置参见阿里云 OpenAPI 认证。

{
  "idaasInstanceId": "idaas_xxx",
  "clientId": "app_xxx",
  "issuer": "https://your-issuer.example/api/v2/iauths_system/oauth2",
  "tokenEndpoint": "https://your-issuer.example/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "openApiEndpoint": "eiam.cn-hangzhou.aliyuncs.com",
  "authnConfiguration": {
    "authnMethod": "PLUGIN",
    "identityType": "CLIENT",
    "pluginName": "alibabacloudPluginCredentialProvider"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

单次插件请求只能包含一个受众;同一受众的多个权限以空格分隔,每个条目均写完整的受众与权限。配置完成后,按代码集成中的示例注册插件。