可乐auth

接入文档

标准 OpenID Connect, 任何 OIDC 库都能直接接入

Issuer

https://auth.example.com

Discovery

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 …