Sudomimus 是一个 OpenID Connect 身份提供方，也是应用认证与会话平台。它验证用户身份，判断用户能否进入应用，并管理应用可以获得的身份信息。你的应用根据这些身份信息执行自己的业务权限检查。
以任务管理应用为例，它需要识别再次登录的用户、维持会话，并决定谁可以编辑每个项目。Sudomimus 负责身份认证和平台签发的应用会话。任务应用负责项目、团队角色和编辑权限。两套系统各自承担明确的职责。
跟随用户完成登录并打开项目
假设一个服务端渲染的任务应用提供了「登录」按钮：
- 应用通过 OIDC 或 Connect 发起登录，将浏览器跳转到 Sudomimus。
- 用户使用应用允许的方式完成认证，例如通行密钥或邮箱验证码。Sudomimus 随后检查用户是否可以进入该应用。
- 如果应用请求真实身份信息，Sudomimus 会检查用户的共享决定。必需的信息需要齐备，登录才能完成。
- 应用通过 OIDC 库或 Sudomimus SDK 处理回调，验证结果，并将外部用户标识关联到本地用户记录。
- 用户打开项目时，任务应用的后端检查该用户的项目成员资格和操作权限。
登录成功说明谁完成了认证，以及 Sudomimus 是否允许该用户进入应用。项目权限检查则决定这个用户能否编辑具体项目。你的后端必须对每次受保护的操作执行权限检查。
划分平台与应用的职责
| 职责 | Sudomimus | 你的应用 |
|---|---|---|
| 身份认证 | 按配置的登录方式验证用户提供的凭据。 | 发起登录并验证返回结果。 |
| 应用准入 | 执行应用的认证规则、身份准入规则和返回规则。 | 为目标用户配置适当的规则。 |
| 会话 | 签发、刷新、检查和撤销 Sudomimus 应用会话。 | 保护凭据，管理应用自行创建的本地会话。 |
| 身份信息 | 检查当前共享策略和用户授权。 | 请求需要的字段，处理缺失字段或合成值。 |
| 业务权限 | 提供已认证的身份和会话信息。 | 管理角色、资源、订阅和权限检查。 |
Sudomimus 应用访问令牌是面向指定应用的会话凭据。它不会直接赋予用户编辑项目、读取发票或调用其他 API 的权限。这些决定仍由你的应用负责。
为网页登录选择 OIDC 或 Connect
如果应用已经支持 OIDC 身份提供方，或者需要标准 OIDC 集成，可以选择 OpenID Connect。OIDC 库负责处理协议。接入方可以验证 ID Token，再建立自己的本地会话。
如果你希望使用 Sudomimus 的接入流程，且应用适合使用官方框架 SDK，可以选择 Connect。SDK 可以在服务端处理签名登录请求、回调兑换和应用会话操作。
两种方式都使用托管认证页面。你的应用无需收集用户的通行密钥或邮箱验证码。OIDC 和 Connect 是两种可选的接入方式，使用 OIDC 无需先实现 Connect。
OIDC 与 Connect 选择指南说明了具体配置。CLI 或原生应用可以先阅读接入方式选择指南，其中还介绍了 Device 和 Native 流程。
分别处理登录和会话生命周期
回调让应用取得认证结果。此后，应用还需要处理会话过期、刷新和退出登录。
检查 JWT 的签名、受众和有效期，只能确认已签发凭据是否通过这些检查，不会查询 Sudomimus 会话的当前状态。如果某项操作需要确认当前会话仍然有效，后端可以调用 Session 会话检查接口。具体说明见令牌与验证。
如果应用另行创建了本地会话，就需要管理这个会话的有效期，并明确退出登录或 Sudomimus 会话状态变化时如何处理。上游会话结束，不会自动让本地仍然有效的 Cookie 失效。
按需请求身份信息
任务应用可能只需要用户标识，并不需要真实邮箱。Sudomimus 使用扇区主体（sector subject）作为 sub，内部账户 UUID 始终留在平台内。相关应用可以明确配置为共享一个扇区；位于不同扇区的应用会收到同一账户的不同主体标识。
邮箱、姓名和账户头像分别受共享规则控制。开发者为每个应用配置声明策略，用户决定是否授权共享真实信息。OIDC 还要求会话包含对应的作用域。可选字段可能缺失，合成值策略则可能返回占位信息。
在授权码流程中，Sudomimus 通过 UserInfo 提供个人资料，不会将这些资料放进授权码兑换返回的 ID Token。因此，登录成功并不保证 ID Token 中包含邮箱，也不保证应用可以获取用户的真实邮箱地址。
OIDC 用户标识设计：sub、邮箱与跨应用隐私进一步解释了标识符设计。如果你已完成接入，但没有收到邮箱字段，可以使用邮箱声明排查指南。
从一个应用的完整流程开始
在 With 门户中，为你的组织创建并配置应用。先确定登录方式、准入规则、精确的回调地址和身份信息共享策略，再激活应用。
随后按接入方式选择指南：
- 使用 OIDC 库的应用：OIDC 授权码接入。
- 使用 Connect 的 Next.js 应用：Next.js App Router 登录指南。
- 使用 Connect 的 React Router 应用：React Router Framework Mode 登录指南。
测试用户再次登录、准入被拒绝、凭据过期、退出登录，以及可选资料未被共享的情况。对于任务应用，还要验证已登录用户在缺少项目权限时无法编辑项目。