本文介绍使用 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
也可以在初始化时传入文件路径。文件选择优先级从高到低为:
-
init()显式传入的路径。 -
CLOUD_IDAAS_CONFIG_PATH环境变量。 -
默认路径
~/.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 |
可选,仅支持 |
|
httpConfiguration.connectTimeout |
可选,连接超时,默认 5000 毫秒,取值为 2000–60000 的整数。 |
|
httpConfiguration.readTimeout |
可选,读取超时,默认 10000 毫秒,取值为 2000–60000 的整数。 |
|
httpConfiguration.userAgent |
可选,自定义请求标识,取值为 1–512 个可打印 ASCII 字符。 |
|
failureMode |
可选,默认 |
示例中的杭州端点仅作格式参考,实际地域以实例为准。配置文件保存凭据环境变量的名称,真实密钥由运行环境注入。使用 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 |
使用初始化前注册的插件;另需顶层 |
配置参数示例
选择一种认证方式,将对应的完整 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
}
}
单次插件请求只能包含一个受众;同一受众的多个权限以空格分隔,每个条目均写完整的受众与权限。配置完成后,按代码集成中的示例注册插件。