@ growth- labs/ auth (音乐)
打开认证 客户端 astro + Cloudflare 软件包。 验证JWTs,管理会话 cookie,闸门被保护路径,发布一个签名的服务器可读身份cookie,并注入登录/日志出/调回路径.
这仅仅是一个客户. 它不运行 OpenAuth 发行器 。 峡谷发行商运行时间住在 growth-labs/identity-platform· ; apps/auth-server/ 在这个repo中,只是一个最小的样本工人.
身份,不是授权. 回答"这个用户是谁?"——而不是"他们能访问什么?". 角色、应享待遇和保险费检查是消费者关切的问题(例如:. @fulcrum/auth) (中文(简体) ).
配置
import auth from '@growth-labs/auth'
auth({
issuer: 'https://auth.fedweek.com', // Browser-facing OpenAuth issuer URL
issuerInternal: 'https://auth-internal.example.com', // Optional back-channel issuer URL
clientId: 'fedweek-prod', // Optional; defaults to request hostname
clientSecret: 'AUTH_CLIENT_SECRET', // Worker secret or Secrets Store binding name, resolved at request time
resource: 'https://fedweek.com', // Required RFC 8707 resource/JWT audience URI
cookiePrefix: 'fedweek', // → fedweek_at, fedweek_rt, fedweek_provider cookies
sessionCookieDomain: '.fedweek.com', // Cross-subdomain sharing (optional)
gatedPaths: ['/premium/*', '/account/*'], // Glob patterns for protected routes
loginPath: '/login', // Redirect target for unauthenticated users
logoutRedirect: '/',
callbackPath: '/api/auth/callback',
passwordPath: '/password', // Local branded password form when renderers.password is set
verifyCodePath: '/verify-code', // Local branded magic-code form when renderers.verifyCode is set
providers: ['google', 'password', 'email-code'],
loginPage: {
title: 'Sign in',
brandName: 'FEDweek',
logoUrl: 'https://media.fedweek.com/logos/header.png',
},
renderers: {
// Optional all-or-nothing UI overrides per auth surface.
// Flow logic, cookies, callback exchange, and issuer URLs remain package-owned.
login: { module: '/src/auth/auth-render', export: 'renderLogin' },
password: { module: '/src/auth/auth-render', export: 'renderPassword' },
verifyCode: { module: '/src/auth/auth-render', export: 'renderVerifyCode' },
},
accessTokenMaxAge: 900, // 15 min (seconds)
refreshTokenMaxAge: 2592000, // 30 days
})
输入什么
中间软件 (每个请求运行):
- 读取
{cookiePrefix}_at财务报告和审定财务报表{cookiePrefix}_rt饼干 - 对照内部发行商的JWKS(
{issuerInternal ?? issuer}/.well-known/jwks.json,在工人记忆中缓存) - 需要访问符号
aud以匹配resource; 错误或缺失的受众仍然未经认证 - 如果过期但刷新令牌有效 ~ 静默刷新, 请验证新的访问令牌受众, 然后设置新的 cookie
——每个同位素进行一对一的交换,而绝不在信标上或先入为主(那些被作为客人回答)
425,然后下一个真正的请求刷新) —— 发行人拒绝的刷新符号被记住于<prefix>_rtx; 发行者在匹配时不会再次被询问, 只有当文档导航% 60s 被第二次拒绝时, 才清除符号 cookie - 分布
context.locals.user作为User | null, (中文(简体) ),context.locals.authSession会话是如何解决的,并且——每当刷新路径被输入时——context.locals.authRefreshFingerprint带有SHA-256前缀的提交刷新符号(决不是符号),用于将一个站点的会话活动加入发行商的发行tokenFingerprint - 如果路径匹配
gatedPaths财务报告和审定财务报表user无效 重新定向到loginPath
路线 :
GET /login提供者-选择网页;?provider=google|password|email-code启动本地认证并重定向到发行人的通用/authorize结束点GET /logout——清除饼干,撤销内部发行商的刷新令牌,重新定向GET /api/auth/callback– OAuth 调用处理器( PKCE 代码交换, cookie seting)GET /forgot-password编号 :GET /reset-password——本地重定向到发行者拥有的密码 UI, 除非配置出纸器GET /password编号 :GET /verify-code- 本地品牌密码和魔法码查看时renderers.password编号 :renderers.verifyCode已配置POST /api/auth/password/verify, (中文(简体) ),/api/auth/code/request, (中文(简体) ),/api/auth/code/verify, (中文(简体) ),/api/auth/password/reset/request, (中文(简体) ),/api/auth/password/reset/confirm——包自有后通道表单处理器,通过JSON API调用发行者issuerInternal,然后返回 a303浏览器重定向或 JSON 重定向合同Accept: application/json请求
已命名的 Auth UI
消费者可以供应 renderers.login, (中文(简体) ), renderers.forgotPassword,以及
renderers.resetPassword 内 auth() 选项。 消费者想要
密码和魔法码步骤可以保留在自己的域中,也可以提供
renderers.password 财务报告和审定财务报表 renderers.verifyCode每个渲染器收到一个
从 @growth-labs/auth/types 带有本地格式的软件包
操作、 提供者或发行者 URL, 以及品牌值, 然后返回一个
HTML 字符串或一个 Response。 。 。 .
渲染器只替换格式视图 。 召回,登出,交换信使,
cookie, PKCE/状态, POST CSRF 检查, 以及发行商的通讯
软件包拥有。 何时
renderers.password 或者说 renderers.verifyCode 已配置, /login
将这些供应商按钮链接到本地品牌路由;否则
保持现有发行商托管的 OpenAuth UI 流量.
被遗忘/重置的渲染器既接收历史发行商的URL,又接收新的
本地 API 格式目标 。 使用 passwordResetRequestUrl 财务报告和审定财务报表
passwordResetConfirmUrl 用于消费者托管的重置表格.
软件包拥有的 POST 路线对本地表格安全,并加固
造物师. 收到的土著表格 303 See Other 调头 获取呼叫者应该
发送 Accept: application/json; 成功返回 { ok: true, redirect },以及
返回错误 { error, redirect } 带有 400 状态。 后置请求不包含
同一来源 Origin 拒绝标题为 403 在发行人
电话.
服务器 SDK
import { authClient } from '@growth-labs/auth/server'
const client = authClient(context)
await client.password.verify({ email, password })
await client.code.request({ email })
await client.code.verify({ email, code })
await client.password.reset.request({ email })
await client.password.reset.confirm({ token, newPassword })
authClient(context) 读取已解析的集成配置和工作人
绑定,帖子到 {issuerInternal ?? issuer}/api/v1/auth/*,解决
clientSecret 应请求保存绑定名称
使用模块 - 私密请求 - 寿命缓存存储 (Request, binding name)发送 client_secret_basic 保密客户,以及
包含 client_id, (中文(简体) ), redirect_uri电脑交换中心
code_challenge, (中文(简体) ), state,以及 resource 签发授权代码
打电话 密码重置请求呼叫还包括 reset_url_base 从
当前消费源, 发行商可以将重置链接发送回相同的
注册主机。 软件包拥有的 POST 路线直接使用这种 SDK ;
消费者也可以从自定义服务器路由中使用.
如果配置的保密客户端装订缺失, 空的,
每一个 SDK 方法均不正确或被拒绝
{ error: 'auth_service_unavailable' } 并且不执行发行人请求.
分析事件
何时 @growth-labs/[email protected] 或新安装, 成功
调用和 JSON 校验路径 signup_completed 或者说
login_completed 结束 trackServerEvent 从
@growth-labs/analytics/utils有效载荷是:
{
provider: 'google' | 'password' | 'email-code' | 'unknown',
isNewUser: boolean,
auth_path: string,
identity_user_id: string,
}
事件来自消费网站请求的背景,所以分析
可以保存网站的匿名 visitor_id, (中文(简体) ), session_id属性
饼干,和 gl_identity_links 排队 身份平台不需要这个
查看网站归属饼干.
Auth 失败释放操作事件 auth_failed 与
provider, (中文(简体) ), reason,以及 auth_path失败的有效载荷从不包含原始载荷
电子邮件地址,密码,魔法代码,或重设符.
使用 context.locals.user
// Gated page — user guaranteed authenticated
const { user } = Astro.locals
// user.id, user.email, user.name, user.avatarUrl
// Non-gated page — check first
if (user) {
// show personalized content
}
类型脚本
interface User {
id: string
email: string
name?: string | null
avatarUrl?: string | null
}
// Available as User | null on context.locals.user (Astro.locals.user in .astro files)
装订
GL_IDENTITY_SECRET 当分析仪表板需要登录与匿名分区时,则需要。 必须是32字节的秘密编码,并有标准基数64,每个租户都应该独一无二.
注入的路由读取“工人绑定” cloudflare:workers,匹配 Astro 6 + @astrojs/cloudflare v13. 他们不依赖 Astro.locals.runtime 或者说 context.locals.runtime。 。 。 .
发行商需要 KV + D1 ——参见 growth-labs/identity-platform 用于生产运行时形状,或 apps/auth-server/README.md 这里的样本很少.
融合顺序
Auth 中间软件 MUST 在同意和分析中间软件之前运行. 列表 auth() 先进 astro.config.mjs 集成数组.
无法接触到的发行商( 启动游戏)
JWKS被缓存于工人记忆. 如果冷起步时无法接触到发行者 :
- 非建议路径 : 无法打开..
user = null,页面正常服务 - 有线路径 : 已关闭失败 — 重定向到登录Path
此普通发行者无法获取的行为不适用于配置
客户端秘密解析失败 。 如果有刷新符号,则
中间软件在访问端验证和返回前解决了这个秘密
a 固定的503,不带JWKS或发行器取取. 浏览器请求收到纯
* 文本; Accept: application/json 收到的请求
{"error":"auth_service_unavailable"}。日志仍然清除本地饼干.
驱逐JWKS缓存没有公开运行时间/admin API. 缓存
遵守工人隔离生命周期的规定; _resetJwksCache() 是一个
内部软件包测试帮助器,而不导出
@growth-labs/auth/utils。 。 。 .
OAuth 流量摘要
- 用户点击本地登录页面上的供应商 – 浏览器点击
/login?provider=...或当地品牌/password编号 :/verify-code配置渲染器时的路由 - 当地
/login启动路由存储 PKCE/状态/重定向/提供者 cookie并重定向到{issuer}/authorize?provider=...; 已配置resource作为RFC 8707资源指标发送。 消费者主办/password财务报告和审定财务报表/verify-code页面种子{cookiePrefix}_pkce两者/财务报告和审定财务报表callbackPath:root-path复制件可见于软件包拥有的POST处理器和JSON验证流量,而Callback-path复制件则通过Callback路由保留了原生形式交接. 被遗忘的密码路由种子 本地流 cookie 但没有设置一个提供者 cookie . - 对于消费者托管的密码或魔法码流,包拥有的POST线路呼叫
{issuerInternal ?? issuer}/api/v1/auth/*; 接收本地表格303重定向通过/api/auth/callback?code=...&state=...时Accept: application/json验证调用者在位置上交换代码, 设定会话 cookie, 发送成功事件并接收{ ok, redirect }为最终目的地. - 发行人认证或发布 JSON 授权代码 – 回调交换代码
{issuerInternal ?? issuer}/token通过PKCE,发送Authorization: Basic base64(client_id:client_secret)何时clientSecret包含resource,读取properties.isNewUser从JWT有效载荷返回到顶级isNewUser对于遗留的发行者,使用{cookiePrefix}_provider登录时设置了认证流程 cookie , 用于提供者归属、 设定会话 cookie、 设定gl_id何时GL_IDENTITY_SECRET配置、 释放成功/失败分析, 并重定向到原始页面或返回 JSON 重定向合同Accept: application/json。 。 。 .
签名身份Cookie
gl_id 允许服务器侧分析器区分登录请求,而不将PII存储在工人分析引擎中,也不信任一个客户端可写入的旗帜.
- 格式 :
<base64url(payload)>.<base64url(hmac_sha256(payload_bytes, secret_bytes))>没有补丁 - 有效载荷: 小写十六进制
sha256(sub + GL_IDENTITY_SECRET)时sub是访问对象。 原始主题从未被写入饼干. - 秘诀 :
GL_IDENTITY_SECRET32字节标准基数64 - 属性 :
HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=2592000 - 发布: 回调成功或 JSON 在符交换后验证成功
- 已清除 :
/logout与Max-Age=0
验证助手 :
import { verifyIdentityCookie } from '@growth-labs/auth/utils'
const result = await verifyIdentityCookie(cookieValue, env.GL_IDENTITY_SECRET)
if (result.valid) {
console.log(result.payload) // 64-char opaque hex digest
}
signIdentityCookie(payload, secret) 财务报告和审定财务报表 verifyIdentityCookie(cookieValue, secret) 使用网络加密( W)crypto.subtle并且是同声的。 Cookie在签署前就把信使主题搁置了.
分析一体化
可选分析助手 login_completed, (中文(简体) ),
signup_completed,以及 auth_failed。成功事件名称来源于
从访问文件夹 JWT isNewUser 索赔,主张
payload.properties.isNewUser 然后掉回顶层
payload.isNewUser 为遗产发行商。 软件包使用公众
@growth-labs/analytics/utils.trackServerEvent 可选合同时
已安装分析端点 .
密钥模式
- 虚拟模块 :
virtual:growth-labs/auth/config(斜,不是连字符) - Cookie 名称 :
{cookiePrefix}_at, (中文(简体) ),{cookiePrefix}_rt, (中文(简体) ),{cookiePrefix}_pkce, (中文(简体) ),{cookiePrefix}_state, (中文(简体) ),{cookiePrefix}_redirect, (中文(简体) ),{cookiePrefix}_provider, (中文(简体) ),gl_id - PKCE 流动
code_verifier编号 :code_challenge(S/256);{cookiePrefix}_pkce范围为callbackPath用于发行者重定向流量,并设置在两者/财务报告和审定财务报表callbackPath用于消费者托管的密码/代码流,既可在现场张贴JSON,也可交出回调 issuer是浏览器- 显示; 可选issuerInternal用于符号交换、静态刷新、JWT核查/JWKS查询和撤销。 如果省略,则,issuerInternal倒计时issuer。 。 。 .issuerFetch(仅限工人客户端):用于这些后道通话的取回. 一个工人 同一云层区域 由于发行人必须在此通过服务装订的取回(issuerFetch: (input, init) => env.IDENTITY.fetch(input, init)与[[services]] binding = "IDENTITY" service = "<issuer worker>"),因为同区工人/工人fetch()以主机名失败 。 全局默认值fetch。 。 。 .- 使用机密用户
client_secret_basic值交换和刷新时clientSecret已配置。 偏好工人秘密或 Cloudflare 秘密存储器绑定名称, 如AUTH_CLIENT_SECRET; 运行时代码解决了每次绑定一次(Request, binding name)在模块-私有请求-寿命缓存中,在发行者/JWKS I/O之前返回固定的已关闭的503或SDK出错。 没有缓存符号、承诺、结果或秘密字节附在可见消费者身上Request。 。 。 . - RFC 8707 (英语)
resource以授权、 令牌交换和配置时刷新方式发送 email-code是发行方 OpenAuth 的客户端别名code提供者- CSRF 状态参数在回调时被验证
- A. 用户使用权要求
payload.properties.*; 客户端倒回顶级payload.email, (中文(简体) ),payload.name, (中文(简体) ),payload.image,以及payload.isNewUser遗产发行人 - 被遗忘/重置的密码路由仍可以是发行商拥有的重定向或使用渲染器提供的本地API格式目标
- 软件包自定义 POST 路由需要同样来源
Origin页眉; 缺少 或跨场表格提交回复403 - 使用标记认证屏幕
renderers,而不是消费者-地方影子路线 - 访问端
aud必须匹配配置的 RFC 8707resource没错 .astro组件文件为源文件, 未编译