注册你的网站
从 Znosin 应用目录安装 OAuth，打开“我的网站”并添加网站。每个账户最多拥有 20 个集成。组织应使用专门的所有者账户，设置密码并检查已登录设备。
有服务器的网站
机密客户端使用 client_secret_basic。将 Client Secret 保存在服务器端的密钥存储中：它只会显示一次。
浏览器应用
公开客户端使用认证方式 none，没有 Client Secret。不要将 PKCE verifier 或令牌放入 URL 或日志。
最多注册 10 个精确的回调 URL。必须使用 HTTPS；只有 localhost、127.0.0.1 或 [::1] 可以使用 HTTP。不接受通配符、片段或 URL 中的凭据。建议将开发和生产集成分开注册。
Client ID 是公开标识。轮换 Client Secret 会立即撤销旧密钥、授权码和访问令牌。修改回调 URL 或禁用客户端也会撤销现有授权。不要将密钥放入 Git、前端代码或截图。
配置 OIDC 库
| 设置 | 值 |
|---|---|
| Issuer | https://znosin.com |
| Discovery | https://znosin.com/.well-known/openid-configuration |
| 授权流程 | authorization_code · response_type=code · response_mode=query |
| 权限范围 | openid profile email |
| PKCE | S256，两种客户端均必须使用 |
| ID 令牌签名 | RS256；通过发现文档中的 jwks_uri 获取公钥 |
重定向前，分别生成独立且具有密码学随机性的 state、nonce 和 code_verifier。将其保存在访客的服务器会话中；公开客户端保存在浏览器会话中。State 和 nonce 为 16–512 个字符，使用至少 32 个随机字节。Verifier 为 43–128 个非保留 ASCII 字符。不要重复使用同一次登录流程。
GET https://znosin.com/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=EXACT_REGISTERED_URL&
response_type=code&scope=openid%20profile%20email&
state=RANDOM_STATE&nonce=RANDOM_NONCE&
code_challenge=BASE64URL_SHA256_VERIFIER&
code_challenge_method=S256对每个参数值进行 URL 编码。openid 为必填范围，可选 prompt=consent。不支持静默登录、通过 max_age 强制重新认证、Request Objects 或其他 Response Modes。
处理网站回调
- 保存的登录流程只能使用一次。验证原始
state、流程有效期，以及iss与 issuer 完全一致。收到error=access_denied时不要创建会话。不要把未经验证的回调参数作为重定向地址。 - 在 60 秒内通过 POST 表单数据向
/oauth/token交换授权码，发送grant_type、client_id、redirect_uri、code和code_verifier。授权码只能使用一次。机密客户端还必须使用 HTTP Basic：分别对 Client ID 和 Client Secret 进行表单编码，以冒号连接，再进行 Base64 编码。不接受请求体中的密钥。 - 使用 OIDC 库验证 ID 令牌的 RS256 签名、精确 issuer、audience、过期时间、签发时间和绑定会话的 nonce。如有
azp，也需验证。仅解码 JWT 并不等于验证。 - 根据
iss+sub查找或创建本地用户，然后重新生成本地会话 ID。昵称、显示名称和邮箱可能变化，不能作为身份键。
POST https://znosin.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64_FORM_ENCODED_ID_AND_SECRET
grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
redirect_uri=EXACT_REGISTERED_URL&
code=AUTHORIZATION_CODE&
code_verifier=ORIGINAL_VERIFIER示例使用占位符，不含真实凭据。公开客户端省略 Authorization 请求头。两种客户端都必须发送原始 PKCE verifier 和精确注册的回调 URL。请求体中的所有值均需进行表单编码。
个人资料与权限
响应包含有效期为 5 分钟的 ID 令牌和有效期为 1 小时的不透明访问令牌。使用 Authorization: Bearer ACCESS_TOKEN 请求 /oauth/userinfo。其 sub 必须与已验证的 ID 令牌一致。
| 权限范围 | 返回字段 |
|---|---|
openid | sub |
profile | name, preferred_username, picture (公开头像 URL) |
email | email, email_verified |
目前 email_verified 为 false。创建邮箱不等于验证地址所有权。不要自动将未经验证的邮箱关联到已有的密码账户或其他提供商账户。关联前应要求用户先登录已有账户。
不会共享密码、聊天、邮件内容、文件或智能体权限。用户可在个人资料的网站授权设置中撤销访问。这会阻止 UserInfo 和新的授权码交换，但不会结束你的网站会话，也无法撤销已经签发、可离线验证的 ID 令牌。会话和退出登录由你的网站管理。
运行与限制
公开客户端的 CORS 仅允许精确注册的回调来源。机密客户端在服务器之间交换授权码。不要将 Basic 请求头转发到 JWKS、UserInfo 或重定向地址。只保留必要权限，隐藏日志中的授权码和令牌，并限制回调请求频率。令牌端点按 IP 限流；遇到 HTTP 429 时遵循 Retry-After。
管理操作需要所有者已登录的 Znosin 浏览器会话并检查 Origin。智能体令牌不能注册网站或批准授权。自助注册通过 OAuth 应用完成，不是匿名动态客户端注册。网站名称由所有者提供，并非认证标志；授权页会显示实际回调来源。
当前实现的是有限的 OIDC 授权码流程配置，尚未通过 OpenID 一致性认证。暂未实现 Refresh Tokens、联合退出登录、PAR、DPoP 或 RSA 密钥自动轮换。现有公开客户端仍受支持。