每多一个注册表单，用户就要多记一个密码；而您存储的每一个密码，也都是一项需要保护的风险。“使用 Posty5 登录”让用户用已有的 Posty5 账户登录您的网站或应用，就像选择“使用 Google 登录”一样。

本文介绍用户会看到什么、作为开发者您能获得什么，以及接入的四个步骤。它是 Posty5 开发者平台的一部分，平台的整体介绍见API 密钥与 SDK 指南。

什么是“使用 Posty5 登录”

Posty5 现已成为 OAuth 2.0 和 OpenID Connect 提供方。您在 Posty5 Studio 中注册应用，将用户引导到 Posty5 登录，然后取回一个经过签名的 ID 令牌，由它告诉您的服务器用户是谁。您的网站永远看不到用户的 Posty5 密码。

由于遵循标准协议，它既可以配合 Posty5 的 Node.js 和 Angular 软件包使用，也可以配合任何经过认证的 OpenID Connect 库使用，例如 ASP.NET Core、Python、PHP 或 Java。在所有套餐中，注册应用和让用户登录都不消耗积分。

用户会看到什么

• 您登录页面上的“使用 Posty5 登录”或“通过 Posty5 继续”按钮。
• 如果用户尚未登录，会看到 Posty5 自己的登录页面——密码只在 posty5.com 上输入。
• 一个授权同意页面，显示您应用的名称、徽标、网站、隐私政策和服务条款，为您请求的每一项数据单独列出一行，并提供“允许”和“取消”按钮。
• 用户的选择会被记住：下次登录将直接通过。用户可随时在“账户”中的“已连接的应用”里移除您应用的访问权限。

从用户角度的完整说明见什么是“使用 Posty5 登录”？我的数据安全吗？，您可以在自己的登录页面上链接这篇文章。

作为开发者您能获得什么

• 标准 OpenID Connect：采用授权码流程，每次登录都强制要求 PKCE，并提供发现文档，大多数库可据此自动完成配置。
• 经过签名的 ID 令牌（RS256），包含用户的姓名、头像、电子邮箱以及该邮箱是否已验证——仅限用户允许的范围（scope）。
• 为您的应用分配的专属用户 ID。sub 在您的应用中保持不变，在其他开发者的应用中则各不相同，因此不同应用之间无法关联同一用户。
• 适用于 Node.js 后端的 @posty5/oauth，可生成无需会话存储的签名登录链接；以及 @posty5/oauth-angular，为 Angular 提供可自定义的“通过 Posty5 继续”按钮。
• 面向纯前端应用的浏览器登录——按应用单独开启，且只接受来自您所列网站源（origin）的请求。
• Posty5 Studio 中每个应用都有“用户”标签页；添加到该应用的 API 密钥还能让您的服务器读取同一份列表。

四步完成接入

1. 在 Posty5 Studio 中打开“开发者工具包”，进入“OAuth 应用”，选择“注册应用”。填写用户将看到的名称、徽标和链接，并将您的回调地址填为重定向 URI。
2. 将客户端 ID 和客户端密钥复制到服务器配置中。密钥只显示一次，之后可以轮换。
3. 安装 @posty5/oauth 并添加两个路由：一个用于创建登录链接并将用户送往 Posty5，另一个是您的回调路由，用于验证返回结果。
4. 在登录页面放置“使用 Posty5 登录”按钮，自己先登录一次，然后以收到的 sub 作为用户记录的键。

const link = await posty5.createLoginLink({ returnTo: "/account" });
res.cookie("p5_binding", link.binding, { httpOnly: true, secure: true, sameSite: "lax" });
res.redirect(link.url);

// on your redirect URI
const { claims, returnTo } = await posty5.handleLoginCallback(req.query, { binding: req.cookies.p5_binding });

登录链接会把 PKCE 验证码（verifier）、nonce 和您的返回地址封装在一个密封的 state 中，因此您的服务器在两次请求之间无需保存任何内容；同时一个 Cookie 会把链接绑定到发起请求的那个浏览器。

选择接入方式

• 带 Node.js 后端的网站——使用 @posty5/oauth。客户端密钥始终保存在您的服务器上。
• Angular 应用——使用 @posty5/oauth-angular 提供的按钮，由后端执行登录流程。参见如何在 Angular 中添加“通过 Posty5 继续”按钮。
• 没有后端的静态应用——为应用开启浏览器登录，列出网站的源，然后使用 Angular 软件包的 browser 模式，或任何支持 PKCE 的 OpenID Connect 客户端。
• 其他任何语言——将您的 OpenID Connect 库指向 https://api.posty5.com，并填入客户端 ID 和密钥。

开始前需要了解的限制

• 不提供刷新令牌。访问令牌的有效期为 1 小时，因此登录后请维护您自己的会话。
• 不支持静默登录（prompt=none）。您可以通过 prompt=login 或 max_age 强制用户重新登录。
• “使用 Posty5 登录”只共享身份信息——姓名、头像和电子邮箱，不会让您的应用访问用户在 Posty5 中的内容。
• 每个账户最多可注册 20 个 OAuth 应用，每个应用最多可配置 10 个精确匹配的重定向 URI。

常见问题