这个 @auth0/auth0-api-js 库允许在 JavaScript 运行时确保 API 运行 .
在您的 API 中使用 SDK 可能不是微不足道的, 因为它不是您框架的插件和游戏库 。 取而代之,它被设计为构建框架特有SDK的构件.
文档
- Docs 站点 - 探索我们的文件网站 了解更多关于Auth0.
开始
1. 安装SDK
npm i @auth0/auth0-api-js
这个库需要Node.js 20 LTS和较新的LTS版本.
2. 创建 Auth0 SDK 客户端
创建实例 ApiClient。这个实例将被导入并用于我们需要获取方法的任何地方.
import { ApiClient } from '@auth0/auth0-api-js';
const apiClient = new ApiClient({
domain: '<AUTH0_DOMAIN>',
audience: '<AUTH0_AUDIENCE>',
});
这个 AUTH0_DOMAIN 可从 Auth0 剪贴板 一旦你创建了一个应用程序.
这个 AUTH0_AUDIENCE 是 API 的标识符。 您可以在 Auth0 仪表板的 API 部分中找到这个 .
3. 验证访问托肯
SDK的车 verifyAccessToken 方法可用于验证访问符.
const apiClient = new ApiClient({
domain: '<AUTH0_DOMAIN>',
audience: '<AUTH0_AUDIENCE>',
});
const accessToken = '...';
const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
accessToken,
});
SDK自动验证索赔 iss, (中文(简体) ), aud, (中文(简体) ), exp,以及 nbf。您也可以通过配置来通过所需的额外索偿 requiredClaims数字 :
const apiClient = new ApiClient({
domain: '<AUTH0_DOMAIN>',
audience: '<AUTH0_AUDIENCE>',
});
const accessToken = '...';
const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
accessToken,
requiredClaims: ['my_custom_claim'],
});
当下游的API收到通过OBO签发的令牌时,经核实的索赔可能包括: act 索赔。 在这个情景中,下游API验证了符号,证实目前的演员是预期的 MCP 服务器,并记录整个授权链用于审计记录:
import { getCurrentActor, getDelegationChain } from '@auth0/auth0-api-js';
const claims = await apiClient.verifyAccessToken({ accessToken });
const currentActor = getCurrentActor(claims);
const delegationChain = getDelegationChain(claims);
// Authorize only the current actor.
if (currentActor && currentActor !== 'mcp_server_client_id') {
throw new Error('Unexpected actor');
}
// Use the full chain for logging or audit only.
auditLogger.info('delegated_request', {
user: claims.sub,
currentActor,
delegationChain,
});
只有最外层 act.sub 应用于作出授权决定。 使用 delegationChain 用于伐木、审计或归属.
4. 验证 DPoP 访问托肯斯
这个 verifyAccessToken 方法还支持验证 DPop 绑定访问符.
使用时 DPoP您必须提供 scheme, (中文(简体) ), dpopProof, (中文(简体) ), httpMethod,以及 httpUrl 从收到的 HTTP 请求中可以让 SDK 验证证据,并确保令牌与该请求相接.
const apiClient = new ApiClient({
domain: '<AUTH0_DOMAIN>',
audience: '<AUTH0_AUDIENCE>',
dpop: {
mode: 'required', // optional, defaults to 'allowed'
iatOffset: 400, // optional, defaults to 300 seconds
iatLeeway: 30, // optional, defaults to 30 seconds
},
});
const accessToken = '...';
const decodedAndVerifiedToken = await apiClient.verifyAccessToken({
accessToken,
requiredClaims: ['my_custom_claim'],
// Options required for DPoP bound token verification
scheme: '<AUTHENTICATION_SCHEME>',
dpopProof: '<DPOP_PROOF_JWT>',
httpMethod: '<HTTP_METHOD>',
httpUrl: '<HTTP_REQUEST_URL>'
});
5. 保护资源元数据(RFC 9728)
SDK 支持 OAuth 2.0 保护资源元数据,定义如下: RFC 9728 (英语)数字 :
import {
ProtectedResourceMetadataBuilder,
BearerMethod,
SigningAlgorithm,
} from '@auth0/auth0-api-js';
const resourceServerUrl = 'https://api.example.com';
const authServers = ['https://your-tenant.us.auth0.com'];
const metadata = new ProtectedResourceMetadataBuilder(resourceServerUrl, authServers)
.withBearerMethodsSupported([BearerMethod.HEADER])
.withResourceSigningAlgValuesSupported(
SigningAlgorithm.RS256,
SigningAlgorithm.ES256,
)
.withScopesSupported(['read', 'write', 'admin'])
.build();
// Serve metadata from the standard RFC 9728 endpoint
app.get('/.well-known/oauth-protected-resource', (req, res) => {
res.json(metadata.toJSON());
});
6. 托肯交易所
SDK支持 RFC 8693 OAuth 2. Token Exchange,允许您在保存用户身份的同时,为不同的API受众交换令牌.
何时使用哪个流程
-
自定义托肯交换: 当控制主题符号格式时使用。 常见情况:
- 交换 Auth0 的 MCP 服务器令牌
- 从遗留的认证系统迁移
- 与伙伴系统采用自定义符号格式
- 由您服务单位签发的换证
-
与 Token Vault 访问托肯交换 (通过)
getAccessTokenForConnection: 交换外部提供者的访问符时使用:- 使用用户的 Google 令牌访问 Google API
- 使用用户的 Facebook 令牌调用 Facebook Graph API
- Auth0 管理 Token 断层中外部提供者刷新符的任意情景
自定义托肯交换示例
import { ApiClient } from '@auth0/auth0-api-js';
const apiClient = new ApiClient({
domain: '<AUTH0_DOMAIN>',
audience: '<AUTH0_AUDIENCE>',
clientId: '<AUTH0_CLIENT_ID>',
clientSecret: '<AUTH0_CLIENT_SECRET>',
});
// Exchange a custom token (e.g., from an MCP server or legacy system)
const result = await apiClient.getTokenByExchangeProfile(
userToken, // The token to exchange
{
subjectTokenType: 'urn:example:custom-token', // Your custom token type URN
audience: 'https://api.backend.com',
}
);
// Handle token expiry - check expiresAt and re-exchange when needed
// Note: expiresAt is in seconds, Date.now() is in milliseconds
const tokenIsValid = Math.floor(Date.now() / 1000) < result.expiresAt;
if (!tokenIsValid) {
// Re-exchange with a fresh subject token (e.g., from your auth provider)
const newSubjectToken = await getNewTokenFromYourProvider();
const refreshed = await apiClient.getTokenByExchangeProfile(newSubjectToken, {
subjectTokenType: 'urn:example:custom-token',
audience: 'https://api.backend.com',
});
}
安全说明编号:
extra参数(如果在应用程序中暴露)绝不应包含个人识别信息或敏感数据。 额外的参数可能由Auth0记录或包含在审计线索中. 只用于不识别用户的非敏感技术参数.
在 Token 半个交换示例上
使用 getTokenOnBehalfOf() 当您的 API 接收到 Auth0 自身和需求访问符
换成另一个 Auth0 在保护下游 API 时, 访问符
同样的用户身份。 这对 MCP 服务器和其他中间API
需要代表用户调用下游API.
以下示例验证您 API 的进取访问令牌, 将它交换为下游 API 的令牌, 然后用交换令牌调用下游 API .
function getBearerToken(authorizationHeader: string | null): string {
if (!authorizationHeader?.toLowerCase().startsWith('bearer ')) {
throw new Error('Missing Bearer access token');
}
return authorizationHeader.slice('Bearer '.length).trim();
}
export async function handleCalendarRequest(request: Request) {
const incomingAccessToken = getBearerToken(request.headers.get('authorization'));
await apiClient.verifyAccessToken({ accessToken: incomingAccessToken });
const obo = await apiClient.getTokenOnBehalfOf(incomingAccessToken, {
audience: 'https://calendar-api.example.com',
scope: 'calendar:read calendar:write',
});
const downstreamResponse = await fetch('https://calendar-api.example.com/events', {
headers: {
authorization: `Bearer ${obo.accessToken}`,
},
});
if (!downstreamResponse.ok) {
throw new Error(`Downstream request failed with ${downstreamResponse.status}`);
}
return downstreamResponse.json();
}
getTokenOnBehalfOf() 将收到的访问符号转发为
RFC 8693 (法语) subject_token 无效
交换期间,DPoP自有的处理. 当您提供一个代号商店(见下文), SDK
在交换前还要核实主题符号.
这个 OBO 结果仅包括面向访问的字段。 它不会暴露 id_token 或者说
refresh_token。 。 。 .
缓存 OBO 标志
传递带有 a 的上下文对象 store 作为避免在每次请求中调用Auth0的第三个论据.
SDK在交换前检查商店,并将结果写回成功. 无内置
; 提供执行 TokenStore 接口.
const obo = await apiClient.getTokenOnBehalfOf(
incomingAccessToken,
{ audience: 'https://calendar-api.example.com', scope: 'calendar:read calendar:write' },
{ store }
);
在你依赖它之前要知道的一些行为:
- 核实取决于商店. 如果而且只有在商店是
提供,因为缓存需要它的主张来构建缓存密钥. 没有商店,代号是
已转发。 和商店和没有
verifiedsDK在上下文中核查 作为无请求语境的熊鼠指使符,不能满足dpop: { mode: 'required' }, (中文(简体) ), 无法接受 DPOP 绑定符,并给出domains解析器没有 URL 和信头 。 在那个 并传递结果为{ store, verified: { accessToken, claims } }。 。 。 . verified.claims必须是对象verifyAccessToken回到同一个地方ApiClient。 。 。 . 这个 SDK对照私人注册处检查物体身份 所以这些是手工制造的 克隆的, 通过JSON进行回转ApiClient实例或发送到 工序或工人边界以InvalidConfigurationError编辑accessToken债权不得过期:exp位于或位于 拒绝当前时间的几秒钟。 这两张支票VerifyAccessTokenError(单位:千美元)invalid_token,与通常的挑战头),因为它们涉及呼叫者的标志和 而不是整合。 限制之所以存在,是因为缓存密钥是 根据这些索赔。 如果接受未经核实的索偿要求,可以由打电话者阅读或覆盖 另一本金的缓存代币。 当入侵和交换 运行在不同的 进程、调用verifyAccessToken再次在交换方面。 本地验证是便宜的 因为JWKS是缓存的.- 范围匹配. 这个
scopeMatching选项ApiClient实值'strict'(违约)或'non_strict'两者都比较了准予交换的范围.'strict'只重用一个符号 当它被授予的范围等于要求的一组.'non_strict'也可以重新使用其授权的标志 范围涵盖请求,并要求IndexedTokenStore;否则将发出一个InvalidConfigurationError。条目存放在它们原来的范围 获准,则a'strict'检索使用新请求的确切范围集. 申请在赠款时按 等于请求。 包括没有答复的答复scope,这意味着补助金与 请求。 Auth0 缩小或拓宽的赠款存放在与它不同的套件中 请求中, 因此重复相同的请求会错失, 每次重交换 .'non_strict'服务 任何缓存信使的请求,其授权范围包括其中,包括更广泛的赠款. - 有限的赠款在此不被拒绝. 如果 Auth0 授予的范围比请求的要少, 则符号
被缓存在它批准并返回的范围之下
scope确定授权内容 服务器已发送 。 这一一揽子方案并不决定这是否可接受。 服务于 请求确实如此,因为它的背景是将数额有限的赠款转化为正确的响应。 检查grantedScopes如果您需要每个请求的范围,则使用结果。 它总是在,在新鲜的 交换和缓存击出, 它被规范化,被复制和排序。 与scope,这个 当服务器省略时,报告请求的集scope,而范围更广的缓存符号 进行非限制性的打击,以达到更窄的要求。 不测试scope对于真理:一个空的 字符串表示什么也没有被授予,并且不同于没有的字段,这意味着 根据请求授予了范围(RFC 6749 第5.1节),因此if (result.scope)读取为空 赠款作为全额赠款. - 密钥请求类型错误的令牌不会被缓存 . 若为
iss, (中文(简体) ),client_id, (中文(简体) ),azp, (中文(简体) ),sub, (中文(简体) ),org_id, (中文(简体) ),sid或者说jti以非字符串值显示,调用收益为普通无标记 交换。 一个符合要求的标志永远不会触发这个. - 库存合同. 返回的条目必须将其字段暴露为自己的属性,因为
字段读取
Object.hasOwn。普通物体和JSON.parse输出工作; 类 以原型获取器读取为空并失真。 记录或索引成员 超过1 000个瞄准镜被拒,因为其结构不当,非限制性匹配最多为20名候选人 每个查询条目。 索引是一个提示:指向不匹配自己的密钥的成员 记录的瞄准镜被跳过。 此软件包从不删除或删除条目或索引成员, 所以 驱逐属于你的执行. - 退取之窗. 缓存密钥的会话组件会比任何单个访问符都久远, 所以 a 届会早些时候铸造的委托代币重新用于同一届会的后期代币。 A 类 在授权服务器上取消的会话不会使已缓存的授权令牌无效 在那个信物过期之前 这对缓存授权的代币是固有的.
- 商店故障从不失败. 读出一个扔出,一个不正确的条目和一个条目关闭 中,所有缓存都丢失,并且一个丢出仍然返回新符号的写入.
- 保护活物. 缓存密钥不透明, 在清晰处没有请求值, 但是 此软件包不应用加密 。 由共享或持续存储支撑的商店负责 保护它所持有的象征物.
见 用托肯斯托雷来吊死OBO标志 内 缩略语.md 包括有缓存的DPoP、索引商店、 CachedToken 形状 和责任界限.
7. 客户证书(机器对机器)
SDK支持OAuth 2.0客户端认证授权,该授权允许保密客户端(服务器侧应用程序有客户端秘密或私人密钥JWT)在没有用户参与的情况下获得访问令牌. 这是机对机(M2M)通信的标准模式,如背景工作或微服务呼叫下游API.
要使用此流量, 您必须配置 ApiClient 具有客户资格:
import { ApiClient } from '@auth0/auth0-api-js';
const apiClient = new ApiClient({
domain: '<AUTH0_DOMAIN>',
audience: '<AUTH0_AUDIENCE>',
clientId: '<AUTH0_CLIENT_ID>',
clientSecret: '<AUTH0_CLIENT_SECRET>',
});
// Request a token using the audience configured at construction time.
const tokenSet = await apiClient.getClientCredentialsToken({});
您也可以覆盖观众, 或通过一个范围给给定的电话:
// Override audience and request specific scopes.
const tokenSet = await apiClient.getClientCredentialsToken({
audience: 'https://api.backend.com',
scope: 'read:data write:data',
});
// Use the access token to call a downstream API.
const response = await fetch('https://api.backend.com/data', {
headers: {
authorization: `Bearer ${tokenSet.accessToken}`,
},
});
scope 被转发到符号端点,将白空间正常化为单个空间。 过 null 或放它出去 以发出没有范围。 空或非字符串值抛出 InvalidScopeError 在提出任何请求之前,因为Auth0会视之为省略并发放全额赠款。 Auth0 不将签发的令牌缩入请求 scope,所以读出授予 scope 以观察一切迹象。 这需要 @auth0/auth0-auth-js 1.1.8.0 或较后.
方法返回 a TokenSet 具有下列属性的对象:
accessToken: Auth0发布的访问令牌.expiresAt:自Unix时代起,标志性过期时间为秒.scope: 授权服务器所授予的范围, 由于一个空间限制字符串正按给定的返回 。 缺席scope是指根据请求授予的范围(RFC 6749 第5.1节)。 空字符串意味着没有被允许。 将两者分开,测试undefined而不是为虚假.tokenType: 符号类型, 由基本的 OAuth 客户端规范为小写, 所以一个无记名符号会以bearer。 。 。 .
要检查一个符号是否在使用前过期, 请比较 expiresAt 改为当前时间 :
// expiresAt is in epoch seconds; Date.now() is in milliseconds.
const isExpired = Math.floor(Date.now() / 1000) >= tokenSet.expiresAt;
所需资源编号:
ApiClient必须用其中之一来构建clientSecret或者说clientAssertionSigningKey调用getClientCredentialsToken()不配置客户端认证MissingClientAuthError。 。 。 .
反馈
捐款
我们赞赏反馈和对这次再投资的贡献! 在开始前,请阅读以下内容:
提出问题
请提供反馈或报告错误 提出我们的问题追踪器。 。 。 .
脆弱性报告
请不要在公共 GitHub 问题跟踪器上报告安全漏洞 。 这个 负责任的披露程序 详细说明披露安全问题的程序.
什么是奥特?
Auth0是一个易于执行,可适应的认证和授权平台. 学习更多退房 为什么是Auth0?
这个项目根据麻省理工学院的许可证获得许可。 见 自由主义 需要更多信息的文件.