authentik¶

本页介绍如何通过单点登录（SSO）把 Specivo 接入 authentik。请先阅读 单点登录，了解相关概念以及 Specivo 各项设置的作用。以下步骤已在 authentik 2026.8 上验证：登录、首次登录时自动创建账户、组映射、在 authentik 处退出、后端通道注销以及会话检查均可正常工作。

示例值：Specivo 地址为 https://specivo.example.com（APP_URL），authentik 地址为 https://authentik.example.com，应用 slug 为 specivo，提供商 slug 为 authentik。

1. 在 authentik 中创建提供商和应用¶

在 authentik 管理界面，进入 Applications → Applications，点击 New Application。向导会同时创建应用及其提供商。也可以先在 Applications → Providers 下创建提供商，再创建一个使用它的应用。

Application（应用）

• Name（名称）：Specivo。Slug：specivo。slug 会成为颁发者的一部分。

Provider: OAuth2/OpenID Provider（提供商）

• Authorization Flow（授权流程）：default-provider-authorization-implicit-consent 会跳过同意页面。如果希望用户每次都确认，选择显式同意的流程。
• 在 Protocol settings（协议设置）下：
  • Client Type（客户端类型）：Confidential。
  • Client ID：填 specivo，或使用自动生成的值。Client Secret：复制生成的密钥。
  • Grant Types（授权类型）：只勾选 Authorization Code 和 Refresh token，其他全部不勾。表单默认几乎勾选了所有授权类型，而 Specivo 不需要其他任何一种。如果没有 Authorization Code（例如通过 API 或蓝图创建提供商时未指定 grant_types），authentik 会拒绝所有登录，用户会看到 sso_idp_error。如果没有 Refresh token，authentik 仍会发放刷新令牌，但之后会拒绝使用它，Specivo 就无法在 authentik 处检查会话（见 会话检查）；此时测试连接会提示提供商拒绝了刷新令牌。在 API 和蓝图中，对应的值是 authorization_code 和 refresh_token。
  • Redirect URIs/Origins（重定向 URI/来源）：添加 https://specivo.example.com/auth/oidc/authentik/callback/，匹配模式选 Strict，类型选 Authorization。再添加 https://specivo.example.com/login/?logged_out=1，匹配模式选 Strict，类型选 Post Logout（API 和蓝图中为 logout）：这是退出后 Specivo 返回的地址。不要使用正则表达式或通配符。
  • Signing Key（签名密钥）：选择一对证书密钥，例如内置的 authentik Self-signed Certificate。此项为必填。没有签名密钥时，authentik 会用客户端密钥签名令牌（HS256），Specivo 会拒绝这类令牌。选了密钥后令牌为 RS256。
• 在 Advanced flow settings（高级流程设置）下，把 Invalidation Flow（失效流程）设为 default-invalidation-flow（名为 Logout）。Specivo 把用户送到 authentik 退出时运行的就是这个流程（见 注销）。默认预选的 default-provider-invalidation-flow 只会告知用户已离开应用，authentik 会话仍保持打开。
• 在 Advanced protocol settings（高级协议设置）下：
  • Scopes（作用域）：保留 openid、email、profile 和 offline_access 的默认映射。profile 映射负责把 groups 声明（claim）放进令牌；offline_access 让 authentik 发放会话检查所用的刷新令牌。
  • Subject Mode（主体模式）：保留 Based on the User's hashed ID（默认值）。
  • Include claims in id_token：保持开启（默认值），这样用户组和邮箱会随 ID 令牌一起返回。
  • Issuer mode（颁发者模式）：保留 Each provider has a different issuer, based on the application slug（默认值）。

允许使用该应用的人员。在应用的 Policy Bindings（策略绑定）选项卡上，绑定允许打开 Specivo 的用户组或用户。这是 authentik 自己的访问控制，在 Specivo 看到任何用户之前就已生效。如需第二层防线，可以再用 Specivo 的 必需的组。

2. 用户组¶

当应用使用默认的 profile 作用域映射时，authentik 会在 groups 声明中以字符串列表的形式发送用户所属各组的名称，无需额外配置。在 Specivo 中，组声明 填 groups（默认值）。必需的组、管理员组 和 组映射 使用的组名必须与 authentik 中完全一致，例如 specivo-users 和 specivo-admins。

该声明列出用户的全部用户组，而不只是绑定到应用的那些。请为 Specivo 中要用到的组起明确的名字。不属于任何组的用户会得到一个空列表，因此 必需的组 会以 sso_not_in_required_group 拒绝他们。

3. 注销¶

在 authentik 处退出 在上述设置下即可工作。用户退出 Specivo 时，Specivo 把浏览器连同 ID 令牌和退出后地址一起送到提供商的会话结束端点（https://authentik.example.com/application/o/specivo/end-session/）。authentik 运行失效流程 default-invalidation-flow，不做任何询问直接结束 authentik 会话，然后把浏览器送回 https://specivo.example.com/login/?logged_out=1。退出后地址必须以 Post Logout 类型注册（见步骤 1），否则 authentik 不会把浏览器送回来。如果用的是 default-provider-invalidation-flow，用户虽然回到 Specivo，但在 authentik 处仍保持登录，下一次点 使用 authentik 登录 无需密码即可通过。

后端通道注销（可选）会在 authentik 会话结束时结束 Specivo 会话：用户在 authentik 处退出、管理员结束其会话、用户被停用或删除时都会触发。authentik 每个会话发送一次注销请求，偶尔会发两次；Specivo 能处理重复请求。在 Protocol settings 下，把 Logout URI 设为 https://specivo.example.com/auth/oidc/authentik/backchannel-logout/，Logout Method（注销方式）设为 Back-channel。这些请求由 authentik 的 worker 发出，所以 worker 必须能通过该地址访问 Specivo。在 Specivo 中勾选 接受来自提供商的后端通道注销。

4. 在 Specivo 中添加提供商¶

管理 → 单点登录 → + 新建提供商：

颁发者 以斜杠结尾，且包含应用 slug。请直接从 authentik 提供商页面上显示的 Issuer 复制，不要手动输入：少一个斜杠就会导致颁发者不一致，登录失败。

保存后点击 测试连接，勾选 已启用，再次保存。测试连接应报告找到会话结束端点并支持后端通道注销。首次登录之后，它还应显示会话会在提供商处检查；如果提示提供商未发送刷新令牌，说明 作用域 中或提供商的作用域映射中缺少 offline_access。账户、JIT 和用户组相关内容见 单点登录。

authentik 注意事项¶

• 邮箱验证。authentik 默认的 email 作用域映射始终发送 email_verified: false。在这种情况下，请让 此提供商确实会验证邮箱地址 保持关闭：开了也没有任何作用，因为 Specivo 永远收不到已验证的地址。实际影响是：用户在 Specivo 中的邮箱不会跟随 authentik 更新，自动关联永远不会触发，首次登录时创建的账户邮箱处于未验证状态，而 允许的邮箱域名 会拒绝所有人。请用 必需的组 或 authentik 的策略绑定来限制谁可以登录，并让用户在个人资料中自行关联已有账户。只有在 authentik 的数据源确实会验证邮箱的情况下，才把默认的 email 映射替换成你自己的、返回 email_verified: true 的映射，然后再开启 Specivo 的这项设置。
• 语言和时区。默认映射既不发送 locale 也不发送 zoneinfo。要让用户的语言跟随 authentik，添加一个返回 locale 声明的作用域映射，并在提供商上选中它。
• 测试用户。分别用一个属于已映射组的用户和一个不属于任何组的用户试一下；如果你设置了必需的组，确认第二个用户被拒绝（sso_not_in_required_group）。

离职处理¶

如果配置了 SCIM 用户同步，在 authentik 中停用或删除用户会立即停用其 Specivo 账户，API 密钥也一并失效。没有 SCIM 时，要收回某人的访问权限：

1. 在 authentik 中停用该用户（或删除）。authentik 会立即拒绝其刷新令牌，所以其 Specivo 会话会在下一次续期时结束（15 分钟之内）；如果开启了后端通道注销，则立即结束。
2. 如果使用了 API 密钥，可以在 当提供商结束会话时 一项选择 结束其所有会话并停用其 API 密钥（这样停用触发的后端通道注销会关闭没有 Specivo 密码的用户的密钥），或者同时在 Specivo 中停用该用户（管理 → 用户 → 停用账户），后者对设有密码的用户同样有效。

在 authentik 中仅结束某人的会话（用户的 Sessions（会话）选项卡）而不停用，只是退出登录，不算离职处理：其为 offline_access 发放的刷新令牌仍然有效，因此只有后端通道注销能结束 Specivo 会话，而且此人可以再次登录。

如果不能正常工作¶

完整列表见 错误表。