访问与登录¶
首次运行时需要选择用户如何登录。升级的实例会请你确认一次该选择;账户、缓存和预填充设置都会保留,除非选择无需身份验证,该模式会删除所有账户。之后可在 用户 → 登录 → 更改 中更改。
五种模式¶
| 模式 | 用户需输入 | 适用场景 |
|---|---|---|
| 用户名和密码 | 用户名和密码 | 大多数部署 |
| API 密钥、用户名和密码 | 先 API 密钥,后用户名和密码 | 在登录页增加一道检查 |
| API 密钥和单点登录 | 先 API 密钥,后单点登录账户 | 同上,配合外部服务商 |
| 单点登录 | 单点登录账户 | Google、GitHub、Microsoft、Apple 或 OpenID Connect |
| 免认证访问 | 无需输入 | 仅限受信任的局域网 |
- 免认证访问 会让任何能访问该应用的人使用其管理功能。
- 切换到免认证访问会删除所有账户。 应用会先请你确认,并显示将删除的账户数量。要重新开启登录,你需要创建一个新的管理员账户。
- 如果 OpenID Connect 服务商或 GitHub 接受
http://回调地址,单点登录可以通过纯 HTTP 使用。Google 和 Microsoft 除 localhost 外都需要 HTTPS,Apple 需要 HTTPS 域名。 - 密码和 API 密钥模式可以使用 HTTP。在不受信任的网络中请使用 HTTPS,以免密码和会话 Cookie 以明文传输。
通过环境变量设置模式¶
在 Compose 文件中设置 Security__SignInMode 即可固定模式。此时模式选择器为只读,首次运行设置的行为如下:
Security__SignInMode |
首次运行设置的访问步骤 |
|---|---|
Password 或 ApiKeyPassword |
跳过。数据库步骤和第一个账户步骤仍然会运行。 |
Unauthenticated |
跳过。每次启动都会删除所有账户,包括环境变量中的登录所允许的账户。不会创建第一个账户。如果在该登录的变量仍然设置的情况下重新开启登录,该用户下次登录时会重新创建该账户。 |
Oidc 或 ApiKeyOidc |
以只读方式显示。所有者在此处通过环境变量中的登录进行登录。 |
之后如果你删除这些变量,访问步骤会重新出现。如果删除 Security__SignInMode 时已保存的模式是 Unauthenticated 且仍有账户,不会删除任何账户;访问步骤会请你选择模式。取值和名称见通过环境变量设置登录。
选择之前的默认值¶
没有 Security__SignInMode 时,在保存模式之前,由 Security__EnableAuthentication 这个 compose 变量决定默认值:
| 取值 | 默认模式 |
|---|---|
true(内置默认) |
API 密钥、用户名和密码 |
false |
免认证访问 |
保存模式后,该变量不再改变它。
API 密钥始终有效
密钥属于主管理员,登录关闭时则属于运行此实例的人。在任何模式下它都可用于所有权确认和账户恢复。只有两种 API 密钥模式会在登录时要求输入它。
重新生成 API 密钥 会替换该密钥,旧密钥立即失效。
单点登录¶
这里没有中心登录服务。你需要在每个服务商处注册一个应用,并把它的信息填入本应用。可以同时连接多个服务商。
| 服务商 | 所需信息 |
|---|---|
| 客户端 ID 和客户端密钥 | |
| GitHub | 客户端 ID 和客户端密钥 |
| Microsoft | 应用程序(客户端)ID、客户端密钥和目录(租户)ID |
| Apple | Services ID、Team ID、Key ID 和 .p8 私钥 |
| 其他(OpenID Connect) | HTTP 或 HTTPS 颁发者 URL、客户端 ID 和客户端密钥 |
- Microsoft: 填写租户 GUID,个人账户填
consumers。common和organizations会被拒绝。 - Apple: 本应用会自动生成 Apple 的客户端密钥。Apple 要求 HTTPS 域名,不接受 localhost 和 IP 地址。
通过环境变量设置¶
把服务商的字段设为 Security__ 变量,而不是粘贴到应用中。由环境变量设置的字段优先于界面中保存的值,且不能在界面中编辑。没有有效登录的 Oidc 或 ApiKeyOidc 模式会回退到 API 密钥、用户名和密码,绝不会回退到免认证访问。完整列表(包括用于密钥的 *File 形式)见通过环境变量设置登录。
设置步骤¶
- 使用用户实际访问本应用的地址打开它。回调 URL 基于该地址生成。
- 把 登录回调 URL 和 测试回调 URL 复制到服务商的应用注册中。你无需自己打开它们。
- 点击 测试连接,它会执行一次真实登录。
- 通过后,用于登录的账户会关联到主管理员,设置随即生效。
- 失败则不改变任何内容,因此一次失败的尝试不会破坏已经可用的配置。
允许其他用户登录¶
通过服务商提供的账户 ID 授权其他用户,而不是电子邮件地址或显示名称。
| 服务商 | ID 格式 |
|---|---|
| GitHub | 数字账户 ID |
| Microsoft | 租户 GUID:对象 GUID |
回调地址¶
- 通过纯 HTTP 使用时,服务商必须接受
http://回调 URL。许多自托管的 OpenID Connect 服务商都接受。Google 和 Microsoft 只在 localhost 上接受,Apple 从不接受。 - 通过纯 HTTP 使用时,登录代码和服务商的密钥会以未加密方式经过你的网络。在不受信任的网络中请使用 HTTPS。
- 域名无需公开。只在局域网或 VPN 内可解析的名称就足够。
- 服务商使用自签名或私有证书时:把签发它的 CA 证书以 PEM 格式、
.crt文件名放入/data/certs/,然后重启容器。应用会把它加入受信任的根证书,公共根证书仍然受信任。 - 在终止 TLS 的反向代理之后运行时,请设置
Security__ForceSecureCookies=true,把代理加入Security__KnownProxyNetworks,并传递原始的Host请求头(nginx 中为proxy_set_header Host $host;)。回调 URL 基于该主机生成。
切换模式¶
- 切换到某个模式会结束该模式不再接受的会话:当单点登录成为唯一的登录方式时,结束主管理员以外账户的密码会话;关闭单点登录时,结束单点登录会话。主管理员的密码会话会保留,因为该账户始终可以用密码登录;设置了所有者的服务商账户 ID 时,主管理员的单点登录会话也会保留。保存此更改的会话保持登录。如果更改需要测试登录,这些会话会在测试登录成功后结束。此更新之前创建的会话会保留。要结束某个会话,请在用户列表中选中它并选择撤销。切换到无需身份验证会删除所有账户及其会话。
- 选择任何登录模式都会立即停止共享的免认证访问。
- 通过单点登录创建的账户还没有密码。切换到密码模式前请先设置密码。
因单点登录无法登录¶
如果环境变量中的登录已回退到 API 密钥、用户名和密码,而所有者没有本地密码,请按密码恢复中的编号步骤操作。
其他情况下,在宿主机上运行恢复脚本:
它会打开一个一小时的恢复窗口。在浏览器中输入 用户名、密码、确认密码 和 API 密钥。之后你会以主管理员身份登录,并可修复登录方式。完整步骤见密码恢复。