@hanzo/iam (英语)
用于认证的单向类型SDK 汉佐 IAM a 包括: 以标准为首的OIDC供应商服务于一个可配置来源的每个品牌:
| 品牌 | serverUrl |
|---|---|
| 汉三 | https://hanzo.id |
| 吕克思 | https://lux.id |
| 动物园 | https://zoolabs.id |
| 启动节点 | https://id.bootno.de |
| 参数 | https://pars.id |
品牌-原生地图导出为 BRAND_SERVER_URLS 编号 :
serverUrlForBrand(brand) 从 @hanzo/iam (和 @hanzo/iam/paths)——一个
位置,代码.
一个OIDC路径设置. 每事取一一名相. 无倒相相相相相相相相相.
读取身份的唯一方法
const iam = { serverUrl: "https://hanzo.id", clientId: "my-app" };
const me = await getServerSession(req, iam); // Bearer/cookie + X-Org-Id; null → 401
// off HTTP: const r = await validateToken(token, iam, org); if (!r.ok) deny(r.reason);
me.sub; // opaque id — never parse it
me.org; // tenant: X-Org-Id if ∈ orgs, else orgs[0]; an app's owner
me.orgs; // signed membership set, home first
me.role; // coarse role in me.org — an ORG role
me.isSuperAdmin; // a person whose home org (orgs[0]) is `admin` — the only platform authority
me.app; // machine principal (client_credentials)
IAM的(英语: sub 是用户的 UUID 和用户代号 owner 这是 应用程序 奥尔格,所以
sub.split("/")[0], (中文(简体) ), claims.owner 财务报告和审定财务报表 ?? orgName 所有用户都映射到一个
租户. validateToken 只有读者:
iss以配置为主( q)issuer默认值serverUrl; 多个列表 (品牌)——从来不是象征自己的iss从来没有发现。 每个牌子都签了 同一键;iss是什么告诉他们分开.aud总是执行:clientId,或audience许可列表 .- 用户 +
orgs请求; 应用( a)type: "application"页:1owner。无orgs- 拒绝. - 请求的
X-Org-Id)必须是...orgs- 其它的吗iam_org_forbidden。 。 。 . - SuperAdmin 一个人的家 Org,
orgs[0],为admin—— 说superAdmin(claims), (中文(简体) ), 汉萨伊/奥斯Claims.Sudo没错 一个admin更下一组成员,owner, (中文(简体) ),isAdmin财务报告和审定财务报表role === "admin"没有一个是平台权威.
失败原因 : iam_token_missing, (中文(简体) ), iam_issuer_unset, (中文(简体) ), iam_audience_unset, (中文(简体) ),
iam_discovery_failed, (中文(简体) ), iam_token_expired, (中文(简体) ), iam_issuer_invalid, (中文(简体) ),
iam_audience_invalid, (中文(简体) ), iam_signature_invalid, (中文(简体) ), iam_subject_missing, (中文(简体) ),
iam_org_missing, (中文(简体) ), iam_org_forbidden。 。 。 .
lint/ (单位:千美元)ast- grep 图像,与汉佐艾/西)相同的规则拒绝
绕道而来.. ast-grep scan -c node_modules/@hanzo/iam/lint/sgconfig.yml数字 :
sub.split, (中文(简体) ), ?? orgName, (中文(简体) ), .owner 证明结果, jwtVerify 无
audience一个发行人从信物, X-Org-Id 读于此包外.
单向模式
IAM是经过改造的 改为 每个框架;框架保持 本地语言 认证
路线。 下一个 Auth/ Auth.js 硬山 /api/auth (或 /auth- 护照,Remix,
Express,而Hono各自都有自己的路线惯例——这个SDK从不移动
它们进入 /v1SDK的唯一工作就是把每个框架交给一个
提供者/适应者 原生形状 授权/接听/用户信息点
在我们的峡谷 /v1/iam/oauth/*翻译在这里,代码,一次
(单位:千美元)src/paths.ts);每个适配器都会通过它解决端点而无处可去
硬码路径。 PKCE-S256一直使用;保密客户使用
client_secret_basic。 。 。 .
条条路
每个终点都通过一个单一的真相来源解决—— OIDC_PATHS
(单位:千美元)@hanzo/iam/paths) (中文(简体) ). 这些是 仅限 路径; 没有遗留
/oauth/* 没有 /api/login/*。 。 。 .
| 终点 | 路径 |
|---|---|
| 发现 | /.well-known/openid-configuration |
| 授权 | /v1/iam/oauth/authorize |
| 符号 | /v1/iam/oauth/token |
| 用户信息 | /v1/iam/oauth/userinfo |
| 竖起 | /v1/iam/.well-known/jwks |
| 登录 | /v1/iam/oauth/logout |
抓到他们了 IAM服务于
200 text/html任何未注册路径的SPA. 一个错误的路径返回 HTML,而不是一个 404 ——无声断裂. 这个SDK接头 准确的路径,永远不要让发现 解决错误的路径: OAuth 适配器完全跳过发现(显式终点), JWT 核查 降入峡谷jwks路径 当发现时 失败或返回 HTML 夹- 全部 —— 这样一个发现 blip 永远无法使用 关闭符号验证.
PKCE(S256)始终在运行. 使用保密客户 client_secret_basic。 。 。 .
范围是: ["openid", "profile", "email"]。 。 。 .
安装
pnpm add @hanzo/iam
每个集成区使用一克南克
服务器(Next.js App路由器/节点/Hono/Remix) - @hanzo/iam/server
PaaS级应用软件需要的作品: 解决呼叫者的身份 无记名标志或会话饼干 与IAM的JWKS核对.
import { getServerSession, withSession } from "@hanzo/iam/server";
const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };
// Option A — read the session yourself
export async function GET(req: Request) {
const session = await getServerSession(req, iam);
if (!session) return new Response("unauthorized", { status: 401 });
return Response.json({ user: session.sub, org: session.org, email: session.email });
}
// Option B — guard the handler (401 before your code runs)
export const POST = withSession(iam, (req, session) =>
Response.json({ org: session.org }),
);
getServerSession(req, config, options?) 返回 a Principal 或者说 null。
读取 Authorization: Bearer … 首先,然后是 hanzo_iam_access_token 饼干
(与 options.cookieName))和行为 X-Org-Id org,必须
成为.. orgs (次数) null) (中文(简体) ).
JWT 验证 - @hanzo/iam (或 @hanzo/iam/auth(中文(简体) )
import { validateToken } from "@hanzo/iam";
const result = await validateToken(accessToken, {
serverUrl: "https://hanzo.id",
clientId: "my-app",
}, org); // optional; must be ∈ orgs
if (result.ok) {
// result.sub, result.org, result.orgs, result.isSuperAdmin, result.app
}
见 读取身份的唯一方法。 。 。 .
JWKS URI来自OIDC的发现,当可达到和 降解为
犬类 /v1/iam/.well-known/jwks 路径 否则(发现5xx,
暂停,或 200 text/html SPA call- all). 符号签名是
总是对照取来JWKS进行校验——倒计时不是绕行.
更好一点.. @hanzo/iam/betterauth
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { iamProvider } from "@hanzo/iam/betterauth";
export const auth = betterAuth({
plugins: [
genericOAuth({
config: [
iamProvider({
serverUrl: process.env.IAM_ENDPOINT!,
clientId: process.env.IAM_CLIENT_ID!,
clientSecret: process.env.IAM_CLIENT_SECRET!,
}),
],
}),
],
});
iamProvider 返回真实 genericOAuth 配置条目
(单位:千美元)providerId: "hanzo",绑定授权/托肯/用户信息 URL, pkce: true, (中文(简体) ), authentication: "basic") (中文(简体) ). 没有 discoveryUrl。 。 。 .
下一个 Auth.js / Auth.js - @hanzo/iam/nextauth
import NextAuth from "next-auth";
import { HanzoIamProvider } from "@hanzo/iam/nextauth";
export default NextAuth({
providers: [
HanzoIamProvider({
serverUrl: process.env.IAM_SERVER_URL!,
clientId: process.env.IAM_CLIENT_ID!,
clientSecret: process.env.IAM_CLIENT_SECRET,
}),
],
});
提供者 id 默认为 "hanzo-iam"。终点是 明确 —— 说
authorization编号 :token编号 :userinfo编号 :jwks_endpoint 直接从
OIDC_PATHS; 存在 没有 wellKnown/发现来回旅行 (发现)
获取失败或解答错误会击出 IAM HTML SPA 全部 ——
寂灭相断相. issuer + 键 jwks_endpoint 提供如此开放的客户端
仍然验证 id token 不被发现. checks 默认为
["state", "pkce"]; 符号认证为 client_secret_basic。 。 。 . IamProvider 是一个
稳定同函数的别名;导出配置文件类型为
HanzoIamProfile。 。 。 .
SvelteKit / Auth.js 核心 —— @hanzo/iam/sveltekit
@auth/core (SvelteKit、SolidStart, ) (SvelteKit、SolidStart, @auth/express,)消耗同样
作为 NextAuth 的提供者形状,所以 SvelteKit 适配器是在 under a
Auth.js-idiomatic name——一个构建器,相同的显式终点.
import { SvelteKitAuth } from "@auth/sveltekit";
import { HanzoIam } from "@hanzo/iam/sveltekit";
import { env } from "$env/dynamic/private";
export const { handle, signIn, signOut } = SvelteKitAuth({
providers: [
HanzoIam({
serverUrl: env.IAM_SERVER_URL,
clientId: env.IAM_CLIENT_ID,
clientSecret: env.IAM_CLIENT_SECRET,
}),
],
});
调和 - @hanzo/iam/remix
登录通过 remix-auth + 键 remix-auth-oauth2 (你设计战略,所以)
它的版本会保留你的版本);通过框架不可知核查器进行守卫.
// app/auth.server.ts — login strategy
import { Authenticator } from "remix-auth";
import { OAuth2Strategy } from "remix-auth-oauth2";
import { hanzoIamStrategyOptions } from "@hanzo/iam/remix";
export const authenticator = new Authenticator(sessionStorage);
authenticator.use(
new OAuth2Strategy(
hanzoIamStrategyOptions({
serverUrl: process.env.IAM_SERVER_URL!,
clientId: process.env.IAM_CLIENT_ID!,
clientSecret: process.env.IAM_CLIENT_SECRET!,
redirectURI: "https://app.hanzo.ai/auth/hanzo-iam/callback",
}),
async ({ tokens }) => tokens,
),
"hanzo-iam",
);
// guarded loader/action
import { requireSession } from "@hanzo/iam/remix";
const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };
export async function loader({ request }: { request: Request }) {
const session = await requireSession(request, iam); // throws 401 Response if absent
return Response.json({ org: session.org });
}
Express / 连接 - @hanzo/iam/express
import express from "express";
import { requireAuth, getIamSession } from "@hanzo/iam/express";
const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };
const app = express();
app.get("/me", requireAuth(iam), (req, res) => {
const session = getIamSession(req); // typed, present after requireAuth
res.json({ user: session.sub, org: session.org });
});
requireAuth(config) 401次无符号请求并附上已核实
页 次 req.iamSession。用于可选自动线路
getSession(req, config) (回报) null (在缺席时).
浩诺.. @hanzo/iam/hono
import { Hono } from "hono";
import { requireAuth, getIamSession } from "@hanzo/iam/hono";
const iam = { serverUrl: "https://hanzo.id", clientId: process.env.IAM_CLIENT_ID! };
const app = new Hono();
app.use("/api/*", requireAuth(iam));
app.get("/api/me", (c) => {
const session = getIamSession(c);
return c.json({ user: session.sub, org: session.org });
});
反应(SPA) - @hanzo/iam/react
<Login> 是 DEFAULT 登录 UI — 一个组件, 安装在您的
应用。 每个方法都保留 IN-PLACE(应用程序窗口从不导航到
主机登录页面:通过弹出+进行社交 postMessage,钱包通过内部 SIWx,
电子邮件/密码字/OTP通过PKCE绑定的代码.
import { IamProvider, useIam, Login, completePopupSignin } from "@hanzo/iam/react";
function App() {
return (
<IamProvider config={{
serverUrl: "https://hanzo.id",
clientId: "my-app",
redirectUri: `${window.location.origin}/auth/callback`,
}}>
<Main />
</IamProvider>
);
}
function Main() {
const { user, isAuthenticated } = useIam();
if (!isAuthenticated)
return (
<Login
serverUrl="https://hanzo.id"
clientId="my-app"
redirectUri={`${location.origin}/auth/callback`}
state=""
providers={["google", "github", "wallet"]}
onSuccess={(token) => { /* signed in, in-place */ }}
/>
);
return <div>Welcome, {user?.displayName}</div>;
}
挂起弹出回调桥 redirect_uri 路线——一行. 这个
将代码递回打开器,用于弹出签名和无操作(返回)
false为了正常的导航,所以你通常 handleCallback() 运行 :
// pages/auth/callback
import { completePopupSignin, handleCallback } from "@hanzo/iam/browser";
if (!completePopupSignin()) {
await handleCallback(); // normal top-level redirect callback
}
useIam().login() (全页) signinRedirect) 仅作为明示
独立倒计时——偏好 <Login> 或者说 loginPopup 因此,登录保留
在现场.
浏览器(无框架 PKCE) - @hanzo/iam (或 @hanzo/iam/browser(中文(简体) )
import { IAM, completePopupSignin } from "@hanzo/iam";
const iam = new IAM({
serverUrl: "https://hanzo.id",
clientId: "my-spa",
redirectUri: "https://myapp.com/auth/callback",
});
// In-place social (Google/GitHub can't be iframed → popup + postMessage):
const token = await iam.signinPopup({ additionalParams: { provider: "google" } });
// In-place wallet (SIWx / EIP-4361, no redirect, no loop):
const walletToken = await iam.loginWithWallet();
// Standalone fallback only — full-page redirect to the hosted page:
await iam.signinRedirect();
const t = await iam.handleCallback(); // on the callback route
await iam.logout();
signinPopup 校验回电信息 origin, (中文(简体) ), source 标签,以及
state 在它接触密码之前; completePopupSignin (挂在
redirect_uri 路径) targetOrigin 被绑在自己的地盘上,
永远 "*"。光码没有开口的 PKCE 验证器是没用的
永远不要离开打开器.
登录的IAM持有,在应用程序自己的页面上完成
一个第一党的站点 自己签入并张贴IAM的证书
自己来源的登录端点( n)proxyBaseUrl)),而IAM则在此举行届会
挑战饼干 当IAM持有的登录, 证书电话扔
所欠的, 页面完成它:
import { EmailRequired, IAM, Refused, SecondFactor } from "@hanzo/iam";
try {
location.assign(await iam.loginWithPassword(email, password));
} catch (err) {
if (err instanceof SecondFactor) err.factors; // [{ type: "app" | "email" | "sms", sent, remember }]
if (err instanceof EmailRequired) err.email; // where IAM sent a code, "" for none
if (err instanceof Refused) err.code; // "login_required", "email_code_sent", or ""
}
await iam.verifyFactor(held, { type: "app", passcode }); // or { recovery }
await iam.confirmEmail(held, code); // or changeEmail(held, address), then confirmEmail
await iam.resetPassword(email, code, password); // code from sendLoginCode(email)
await iam.acceptInvite(owner, inviteCode, emailCode); // with the signed-in access token
resume() 当登录的 IAM 持有此浏览器时, 询问什么
待定:一个没有证书的职位被读作答案,并将花费
第二个因素的挑战.
一个通过 Google 或 GitHub 的登录,其账户有第二个因素 返回
改为 /login/mfa 提供商返回的宿主 面对IAM的挑战
那边只有主机饼干 那页回答,然后走到IAM说的地方:
location.assign(await iam.finishFederation({ type: "app", passcode })); // or { recovery }
另一个应用程序的登录, 完成在这个页面
另一个应用打开网站自己的登录页面,并附带标准授权查询:
本地应用程序( 桌面窗口、 CLI 、 电话) 或另一个来源的站点保存
及其PKCE核查员和保密服务器不得发出质疑并赎回
它的秘诀。 页面读取请求 asked (数量) nonce (列入)和
把它交给 ask页面上的每一个登录,然后将应用程序的代码和
返回回调,IAM对照客户端注册的回调进行核对。 这个
在应用程序的应用程序和组织中注册,如
/v1/iam/auth/application 以及地址查询、方法和
发送的代码是应用软件的太, 所以在应用签名的人
用于:
import { asked } from "@hanzo/iam";
iam.ask(asked(new URLSearchParams(location.search))); // null: the page's own
location.assign(await iam.loginWithPassword(email, password)); // hanzo://oauth/hanzo?code=…&state=…
滴入登录 + 登入视图也运行于 @hanzo/iam/views (单位:千美元)Login, (中文(简体) ),
SocialButton, (中文(简体) ), WalletButton, (中文(简体) ), EmailPasswordForm, (中文(简体) ), OTPStep, (中文(简体) ),
OnboardingFlow,以及5个登机阶原始人).
护照.js - @hanzo/iam/passport
import passport from "passport";
import { createIamPassportStrategy } from "@hanzo/iam/passport";
passport.use("iam", createIamPassportStrategy({
serverUrl: "https://hanzo.id",
clientId: "my-app",
clientSecret: process.env.IAM_CLIENT_SECRET!,
callbackUrl: "https://app.hanzo.ai/v1/sso/oidc/callback",
}));
鉴定 - @hanzo/iam/validation
import { isValidPhone, isValidEmail } from "@hanzo/iam/validation";
isValidPhone("6178888888", "+1"); // true — E.164 +16178888888
isValidEmail("[email protected]"); // true
子路径图
| 导入 | 表面 |
|---|---|
@hanzo/iam | IamClient, (中文(简体) ), IamApiError, (中文(简体) ), validateToken, (中文(简体) ), clearJwksCache, (中文(简体) ), IAM, (中文(简体) ), toIAMToken, (中文(简体) ), completePopupSignin, (中文(简体) ), POPUP_WINDOW_NAME, (中文(简体) ), generatePKCEChallenge, (中文(简体) ), generateState, (中文(简体) ), configureIam, (中文(简体) ), startLogin, (中文(简体) ), getLoginUrl, (中文(简体) ), handleCallback, (中文(简体) ), getSession, (中文(简体) ), getUser, (中文(简体) ), logout, (中文(简体) ), OIDC_PATHS, (中文(简体) ), IAM_PATHS, (中文(简体) ), BRAND_SERVER_URLS, (中文(简体) ), iamUrl, (中文(简体) ), serverUrlForBrand,所有类型 |
@hanzo/iam/paths | OIDC_PATHS, (中文(简体) ), IAM_PATHS, (中文(简体) ), BRAND_SERVER_URLS, (中文(简体) ), iamUrl, (中文(简体) ), trimServerUrl, (中文(简体) ), serverUrlForBrand |
@hanzo/iam/session | configureIam, (中文(简体) ), startLogin, (中文(简体) ), getLoginUrl, (中文(简体) ), handleCallback, (中文(简体) ), getSession, (中文(简体) ), getUser, (中文(简体) ), logout, (中文(简体) ), getIam |
@hanzo/iam/server | getServerSession, (中文(简体) ), withSession, (中文(简体) ), getBearerToken, (中文(简体) ), SESSION_COOKIE, (中文(简体) ), ServerSession |
@hanzo/iam/auth | validateToken, (中文(简体) ), clearJwksCache |
@hanzo/iam/browser | IAM (单位:千美元)signinPopup, (中文(简体) ), loginWithWallet, (中文(简体) ), signinRedirect, (中文(简体) ), handleCallback, (中文(简体) ), completePopupSignin, (中文(简体) ), POPUP_WINDOW_NAME, (中文(简体) ), toIAMToken, (中文(简体) ), IAMConfig, (中文(简体) ), IAMUser, (中文(简体) ), IAMToken, (中文(简体) ), Eip1193Provider |
@hanzo/iam/react | IamProvider, (中文(简体) ), useIam, (中文(简体) ), useOrganizations, (中文(简体) ), useIamToken, (中文(简体) ), OrgProjectSwitcher, (中文(简体) ), Login, (中文(简体) ), SocialButton, (中文(简体) ), WalletButton, (中文(简体) ), EmailPasswordForm, (中文(简体) ), OTPStep, (中文(简体) ), OnboardingFlow, (中文(简体) ), useAuthMethods, (中文(简体) ), completePopupSignin |
@hanzo/iam/views | Login, (中文(简体) ), SocialButton, (中文(简体) ), WalletButton, (中文(简体) ), EmailPasswordForm, (中文(简体) ), OTPStep, (中文(简体) ), OnboardingFlow, (中文(简体) ), IdentityStep, (中文(简体) ), DocumentsStep, (中文(简体) ), BiometricStep, (中文(简体) ), ScreenStep, (中文(简体) ), SubmitStep, (中文(简体) ), useAuthMethods |
@hanzo/iam/betterauth | iamProvider |
@hanzo/iam/nextauth | HanzoIamProvider, (中文(简体) ), IamProvider (别名), HanzoIamProfile |
@hanzo/iam/sveltekit | HanzoIam, (中文(简体) ), HanzoIamProvider, (中文(简体) ), IamProvider |
@hanzo/iam/remix | hanzoIamStrategyOptions, (中文(简体) ), requireSession, (中文(简体) ), getSession |
@hanzo/iam/express | requireAuth, (中文(简体) ), getSession, (中文(简体) ), getIamSession |
@hanzo/iam/hono | requireAuth, (中文(简体) ), getSession, (中文(简体) ), getIamSession |
@hanzo/iam/passport | createIamPassportStrategy |
@hanzo/iam/types | 所有类型 |
@hanzo/iam/validation | isValidPhone, (中文(简体) ), isValidEmail |
裸体 @hanzo/iam 解决浏览器在浏览器捆绑器下构建
和节点下通过软件包构建的节点 exports 条件.
配置
| 选项 | 需求 | 说明 |
|---|---|---|
serverUrl | 对 | IAM起源(例如:. https://hanzo.id(中文(简体) ) |
clientId | 对 | OAuth2 客户端标识 |
clientSecret | 没有 | 保密客户的秘密 |
orgName | 没有 | 键 IamClient API 呼叫——从未读过 validateToken |
appName | 没有 | 应用程序名称 |
issuer | 没有 | 获得接受 iss (字符串或品牌列表);默认 serverUrl |
audience | 没有 | 获得接受 aud 允许列表; 默认 clientId; 总是执行 |
jwksUri | 没有 | JWKS 端点, 跳过发现( 集群); 设置 issuer 还有 |
许可证
麻省理工学院 - 大赦国际