接入文档
标准 OpenID Connect, 任何 OIDC 库都能直接接入
Issuer
https://auth.example.comDiscovery
https://auth.example.com/.well-known/openid-configuration- · 授权码流程必须使用 PKCE (S256), 不支持 implicit 与 password 模式
- · 回调地址必须与登记的完全一致; 需要长期登录时申请 offline_access
- · 第三方应用拿到的 sub 是按应用生成的标识, 同一应用的所有端相同
- · 你的 API 校验 access token 时: 用 JWKS 验签, 检查 iss、exp, 以及 aud 等于你的应用 ID
让 AI 帮你接入
把提示词发给 Cursor、Claude Code、Copilot 等 AI 编程助手, 它会按规范生成接入代码
支持联网的 AI 可直接读取https://auth.example.com/llms.txt
官方 SDK
GitHub封装了 PKCE、令牌刷新、签名校验与 Webhook 校验; 也可以继续使用任意标准 OIDC 库
无需安装, 以 ES 模块直接引入 (类型声明见 /sdk/v1/auth.d.ts)。令牌默认只保存在内存, 不写入 localStorage。
auth.js
import { createAuthClient } from "https://auth.example.com/sdk/v1/auth.js";
export const auth = createAuthClient({
issuer: "https://auth.example.com",
clientId: "你的 client_id",
redirectUri: location.origin + "/callback",
scope: "openid profile email offline_access",
});
// 登录按钮
loginButton.onclick = () => auth.login({ state: location.pathname });
// 回调页 /callback
const { state } = await auth.handleCallback();
history.replaceState(null, "", state || "/");
// 之后
const user = await auth.getUser(); // { sub, name, email, ... }
const res = await auth.fetch("/api/notes"); // 自动带 Bearer 令牌, 过期自动刷新
await auth.logout(); // 吊销令牌并结束登录会话webhook.mjs (Node.js 18+ / Workers)
import { verifyWebhook } from "https://auth.example.com/sdk/v1/auth.js"; // Node.js 中可先下载到项目里
const event = await verifyWebhook(process.env.WEBHOOK_SECRET, req.headers, rawBody);
if (event.type === "user.deleted") await removeUser(event.data.sub);Webhook
用户授权、撤销、资料变更、注销等事件实时推送到你的服务端, 失败自动重试。在应用详情「Webhook」中添加。
在线客服
开启后用户可在账户中心联系你, 成员在应用详情「客服」中回复; 应用内可直接链接到发起页。
登录页定制
设置主题色与登录页标题, 用户从你的应用跳转登录时看到你的品牌。在应用详情「设置」中配置。
有后端的网站: 后端持有 client_secret, 完成授权码兑换后用自己的会话 Cookie 维持登录。以 Node.js openid-client 为例。
1. 初始化客户端
ts
import * as client from "openid-client";
const config = await client.discovery(
new URL("https://auth.example.com"),
process.env.KL_CLIENT_ID,
process.env.KL_CLIENT_SECRET,
);2. 跳转登录
ts
const verifier = client.randomPKCECodeVerifier();
const state = client.randomState();
// 把 verifier 与 state 存进服务端会话
const url = client.buildAuthorizationUrl(config, {
redirect_uri: "https://example.com/auth/callback",
scope: "openid profile email offline_access",
code_challenge: await client.calculatePKCECodeChallenge(verifier),
code_challenge_method: "S256",
state,
});
res.redirect(url.href);3. 回调中兑换令牌
ts
const tokens = await client.authorizationCodeGrant(config, new URL(req.url, "https://example.com"), {
pkceCodeVerifier: verifier,
expectedState: state,
});
const claims = tokens.claims(); // sub、name、email、roles …