diff --git a/docs/tech/Build-Your-Own-SSO.md b/docs/tech/Build-Your-Own-SSO.md index 32a3385..b6e3926 100644 --- a/docs/tech/Build-Your-Own-SSO.md +++ b/docs/tech/Build-Your-Own-SSO.md @@ -2,7 +2,7 @@ !!! tip "建议" - 本文篇幅较长,请善于页内搜索 ++ctrl+f++ 与右侧的文章目录 + 本文篇幅较长,请善用页内搜索 ++ctrl+f++ 与右侧的文章目录 ## 准备/环境条件 @@ -166,10 +166,10 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 手动编辑 - 导入**流程蓝图**: 管理员界面 - 流程与阶段 - 流程 - 导入 - - [恢复流程(需邮箱验证)](https://static.cattom.site/authentik-blueprints/forget-password.yaml) - - [删除账户流程](https://static.cattom.site/authentik-blueprints/unenrollment.yaml) - - [无密码登录流程(WebAuthn)](https://static.cattom.site/authentik-blueprints/passwordless-login.yaml) - - [邀请注册流程](https://static.cattom.site/authentik-blueprints/enrollment.yaml) + - [恢复流程(需邮箱验证)](https://static.cattom.site/authentik-blueprints/forget-password.yaml) + - [删除账户流程](https://static.cattom.site/authentik-blueprints/unenrollment.yaml) + - [无密码登录流程(WebAuthn)](https://static.cattom.site/authentik-blueprints/passwordless-login.yaml) + - [邀请注册流程](https://static.cattom.site/authentik-blueprints/enrollment.yaml) ### 验证码阶段: Cloudflare Turnstile (可选) @@ -194,30 +194,30 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 管理员界面 - 流程与阶段 - 阶段 - (身份验证阶段) - 流程绑定 - 编辑流程 - default-authentication-identification: - - 密码流程 - - 验证码流程 - - WebAuthn 身份验证器验证流程 - - 无密码流程 - - 恢复流程 + - 密码流程 + - 验证码流程 + - WebAuthn 身份验证器验证流程 + - 无密码流程 + - 恢复流程 - default-authentication-mfa-validation: - - 设备类型: `静态令牌` `TOTP 身份验证器` `WebAuthn 身份验证器` - - 未配置操作: 强制用户配置身份验证器 - - 配置阶段: - - default-authenticator-webauthn-setup - - default-authenticator-totp-setup - - WebAuthn 用户验证: 如果可用,则首选用户验证,但不是必需的。 + - 设备类型: `静态令牌` `TOTP 身份验证器` `WebAuthn 身份验证器` + - 未配置操作: 强制用户配置身份验证器 + - 配置阶段: + - default-authenticator-webauthn-setup + - default-authenticator-totp-setup + - WebAuthn 用户验证: 如果可用,则首选用户验证,但不是必需的。 ### 外观 - 转至 管理员界面 - 系统 - 品牌 - 域名: `authentik.your.domain` - - 品牌设置: - - 标题 - - ... - - 默认流程: - - 恢复流程 - - 删除账户流程 - - ... + - 品牌设置: + - 标题 + - ... + - 默认流程: + - 恢复流程 + - 删除账户流程 + - ... ## 对接支持 OAuth2/OpenID 的应用 @@ -228,22 +228,22 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 应用名称: 任意字符 - Slug: 英文字符与数字 - 应用界面设置: - - 启动 URL: 对应应用的登录界面 + - 启动 URL: 对应应用的登录界面 **第二步 选择提供程序**: OAuth2/OpenID Provider **第三步 配置提供程序**: - 授权流程: - - default-provider-authorization-**implicit**-consent: 用户通过 Authentik 登录对应应用时不需要点击“授权” - - default-provider-authorization-**explicit**-consent: 用户通过 Authentik 登录对应应用时需要点击“授权” + - default-provider-authorization-**implicit**-consent: 用户通过 Authentik 登录对应应用时不需要点击“授权” + - default-provider-authorization-**explicit**-consent: 用户通过 Authentik 登录对应应用时需要点击“授权” - 协议设置: - - 客户端类型: 机密 - - 客户端 ID: (自动生成,复制备用) - - 客户端 Secret: (自动生成,复制备用) - - 重定向 URL/Origin: (按照应用实际情况添加) + - 客户端类型: 机密 + - 客户端 ID: (自动生成,复制备用) + - 客户端 Secret: (自动生成,复制备用) + - 重定向 URL/Origin: (按照应用实际情况添加) - 高级流程设置: - - 失效流程: default-provider-invalidation + - 失效流程: default-provider-invalidation **第四步 配置绑定**: (跳过,可后续按照实际情况设置) @@ -258,8 +258,13 @@ Authentik 前端实现由流程、阶段和输入三者构成: **配置提供程序**: - 重定向 URL/Origin: - - `正则表达式` `https://your.openlist.domain/api/auth/sso_callback\?method=get_sso_id` - - `正则表达式` `https://your.openlist.domain/api/auth/sso_callback\?method=sso_get_token` + - `正则表达式` `https://your.openlist.domain/api/auth/sso_callback\?method=get_sso_id` + - `正则表达式` `https://your.openlist.domain/api/auth/sso_callback\?method=sso_get_token` + +!!! warning "注意" + + - 记得将 `your.openlist.domain` 替换为你的 OpenList 对应的 FQDN. + - `?` 前的 `\` 是正则表达式中的转义字符,必须保留。 **获取 JWT 证书**: @@ -267,11 +272,6 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 找到 `authentik Self-signed Certificate`,点击列表左侧的 `>` - 点击 `下载证书` 以获取 JWT 证书 -!!! warning "注意" - - - 记得将 `your.openlist.domain` 替换为你的 OpenList 对应的 FQDN. - - `?` 前的 `\` 是正则表达式中的转义字符,必须保留。 - #### OpenList/AList 配置 !!! tip "建议" @@ -293,16 +293,12 @@ Authentik 前端实现由流程、阶段和输入三者构成: - SSO 自动注册: (按需启用) - SSO 默认根目录: `/` (可根据实际情况调整) - SSO 默认权限: - - 默认为 `0`,后续可通过管理界面为用户手动赋权。 - - 请参考[SSO默认权限 - OpenList文档](https://doc.oplist.org/guide/advanced/sso#_4-4-sso%E9%BB%98%E8%AE%A4%E6%9D%83%E9%99%90) + - 默认为 `0`,后续可通过管理界面为用户手动赋权。 + - 请参考[SSO默认权限 - OpenList文档](https://doc.oplist.org/guide/advanced/sso#_4-4-sso%E9%BB%98%E8%AE%A4%E6%9D%83%E9%99%90) - SSO 兼容模式: 否 ### Gitea -!!! tip "建议" - - 在继续操作前,请确保您拥有另一个管理员账户。如果将 Authentik 关联到 Grafana 上唯一的管理员账户,权限可能会被覆盖。 - 以下配置为个人整理,可能存在错误和缺漏,仅供参考。 #### Authentik 配置 @@ -313,21 +309,21 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 点击 “创建” - 选择类型: `Scope Mapping` - 创建 Scope Mapping: - - 名称: `gitea` - - 作用域名称: `gitea` - - 表达式: - ``` python - gitea_claims = {} - - if request.user.groups.filter(name="gituser").exists(): - gitea_claims["gitea"]= "user" - if request.user.groups.filter(name="gitadmin").exists(): - gitea_claims["gitea"]= "admin" - if request.user.groups.filter(name="gitrestricted").exists(): - gitea_claims["gitea"]= "restricted" - - return gitea_claims - ``` + - 名称: `gitea` + - 作用域名称: `gitea` + - 表达式: + ``` python + gitea_claims = {} + + if request.user.groups.filter(name="gituser").exists(): + gitea_claims["gitea"]= "user" + if request.user.groups.filter(name="gitadmin").exists(): + gitea_claims["gitea"]= "admin" + if request.user.groups.filter(name="gitrestricted").exists(): + gitea_claims["gitea"]= "restricted" + + return gitea_claims + ``` **设立用户组与添加已有用户进入用户组**: @@ -353,12 +349,12 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `https://gitea.your.domain/user/oauth2/[auth_name]/callback` - - `[auth_name]` 必须与 Gitea 配置中的 `认证名称` 保持一致,大小写敏感。 + - 重定向 URL/Origin: + - `严格` `https://gitea.your.domain/user/oauth2/[auth_name]/callback` + - `[auth_name]` 必须与 Gitea 配置中的 `认证名称` 保持一致,大小写敏感。 - 高级协议设置: - - 作用域: - - 已选作用域: `OpenID 'email'` `OpenID 'openid'` `OpenID 'profile'` `gitea` + - 作用域: + - 已选作用域: `OpenID 'email'` `OpenID 'openid'` `OpenID 'profile'` `gitea` #### Gitea 配置 @@ -380,6 +376,14 @@ Authentik 前端实现由流程、阶段和输入三者构成: ### Grafana +!!! tip "建议" + + 在继续操作前,请确保您拥有另一个管理员账户。 + + 如果将 Authentik 关联到 Grafana 上唯一的管理员账户,权限可能会被覆盖。 + +以下配置为个人整理,可能存在错误和缺漏,仅供参考。 + #### Authentik 配置 **配置属性映射**: @@ -388,21 +392,21 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 点击 “创建” - 选择类型: `Scope Mapping` - 创建 Scope Mapping: - - 名称: `grafana` - - 作用域名称: `grafana` - - 表达式: - ``` python - grafana_claims = {} + - 名称: `grafana` + - 作用域名称: `grafana` + - 表达式: + ``` python + grafana_claims = {} - if request.user.groups.filter(name="Grafana Admins").exists(): - grafana_claims["grafana"]= "GrafanaAdmin" - elif request.user.groups.filter(name="Grafana Editors").exists(): - grafana_claims["grafana"]= "editor" - else: - grafana_claims["grafana"]= "viewer" + if request.user.groups.filter(name="Grafana Admins").exists(): + grafana_claims["grafana"]= "GrafanaAdmin" + elif request.user.groups.filter(name="Grafana Editors").exists(): + grafana_claims["grafana"]= "editor" + else: + grafana_claims["grafana"]= "viewer" - return grafana_claims - ``` + return grafana_claims + ``` **设立用户组与添加已有用户进入用户组**: @@ -428,38 +432,36 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `https://grafana.your.domain/login/generic_oauth` + - 重定向 URL/Origin: + - `严格` `https://grafana.your.domain/login/generic_oauth` - 高级协议设置: - - 作用域: - - 已选作用域: `OpenID 'email'` `OpenID 'openid'` `OpenID 'profile'` `grafana` + - 作用域: + - 已选作用域: `OpenID 'email'` `OpenID 'openid'` `OpenID 'profile'` `grafana` #### Grafana 配置 - 转至 管理 - 身份验证 - Generic OAuth - 一般设置: - - 显示名称: (随意) - - Client ID: (Authentik 中对应应用的提供程序的客户端 ID) - - Client secret: (Authentik 中对应应用的提供程序的客户端 Secret) - - 身份验证样式: (保持默认) - - Scopes: `email` `profile` `openid` `grafana` - - OpenID Connect Discovery URL: (Authentik 中对应应用的提供程序的**OpenID 配置 URL**) - - 允许注册/自动登录: (按照实际情况) - - 退出登录重定向网址: (Authentik 中对应应用的提供程序的**注销 URL**) - - 登录提示: (空) + - 显示名称: (随意) + - Client ID: (Authentik 中对应应用的提供程序的客户端 ID) + - Client secret: (Authentik 中对应应用的提供程序的客户端 Secret) + - 身份验证样式: (保持默认) + - Scopes: `email` `profile` `openid` `grafana` + - OpenID Connect Discovery URL: (Authentik 中对应应用的提供程序的**OpenID 配置 URL**) + - 允许注册/自动登录: (按照实际情况) + - 退出登录重定向网址: (Authentik 中对应应用的提供程序的**注销 URL**) + - 登录提示: (空) - 用户映射: - - 角色属性路径: `grafana` - - 角色属性严格模式/允许分配 Grafana 管理员: 是 - -### Immich - -请参照 [OAuth Authentication | Immich](https://docs.immich.app/administration/oauth) 完成。 + - 角色属性路径: `grafana` + - 角色属性严格模式/允许分配 Grafana 管理员: 是 ### Jellyfin !!! tip "建议" - 在继续操作前,请确保您拥有另一个管理员账户。如果将 Authentik 关联到 Jellyfin 上唯一的管理员账户,[权限可能会被覆盖](https://github.com/9p4/jellyfin-plugin-sso/issues/212)。 + 在继续操作前,请确保您拥有另一个管理员账户。 + + 如果将 Authentik 关联到 Jellyfin 上唯一的管理员账户,[权限可能会被覆盖](https://github.com/9p4/jellyfin-plugin-sso/issues/212)。 以下内容综合自 [jellyfin-plugin-sso/providers.md at main · 9p4/jellyfin-plugin-sso](https://github.com/9p4/jellyfin-plugin-sso/blob/main/providers.md#authentik) 与 [Integrate with Jellyfin | authentik](https://integrations.goauthentik.io/media/jellyfin/)。 @@ -487,18 +489,23 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `http://jellyfin.your.domain/sso/OID/redirect/[Name of OpenID Provider]` - - `[Name of OpenID Provider]` 必须与 Jellyfin 配置中的 `Name of OpenID Provider` 保持一致,大小写敏感。 + - 重定向 URL/Origin: + - `严格` `http://jellyfin.your.domain/sso/OID/redirect/[Name of OpenID Provider]` + - `[Name of OpenID Provider]` 必须与 Jellyfin 配置中的 `Name of OpenID Provider` 保持一致,大小写敏感。 #### Jellyfin 配置 +**安装 SSO-Auth 插件**: + - 转至 管理 - 控制台 - 插件 - 点击 “管理存储库” - “新建存储库” - - 存储库名称: `jellyfin plugin sso` - - 存储库 URL: `https://raw.githubusercontent.com/9p4/jellyfin-plugin-sso/manifest-release/manifest.json` + - 存储库名称: `jellyfin plugin sso` + - 存储库 URL: `https://raw.githubusercontent.com/9p4/jellyfin-plugin-sso/manifest-release/manifest.json` - 返回上一级 - “可用” - 找到“SSO-Auth” - 安装 - 重启 Jellyfin + +**配置 SSO-Auth 插件**: + - 管理 - 控制台 - 插件 - SSO-Auth - 设置 - Name of OpenID Provider: (必须与 Authentik 配置中的 `[Name of OpenID Provider]`保持一致,大小写敏感) - OpenID Endpoint: (Authentik 中对应应用的提供程序的**OpenID 配置 URL**) @@ -516,23 +523,23 @@ Authentik 前端实现由流程、阶段和输入三者构成: **以下内容基于 Windows 11 & Jellyfin Server 10.11.6,仅供参考。** - 暂时移除 SSO 插件: - - 停止 Jellyfin 服务器 - - 定位 Jellyfin 的 `plugins` 文件夹: - - `%LocalAppData%\Jellyfin\plugins` - - `C:\ProgramData\Jellyfin\Server\plugins` - - 找到名为 sso-auth (或类似名称)的文件夹,将其剪切并移动到桌面暂时备份 + - 停止 Jellyfin 服务器 + - 定位 Jellyfin 的 `plugins` 文件夹: + - `%LocalAppData%\Jellyfin\plugins` + - `C:\ProgramData\Jellyfin\Server\plugins` + - 找到名为 sso-auth (或类似名称)的文件夹,将其剪切并移动到桌面暂时备份 - 重新触发配置向导: - - 定位 Jellyfin 的 `config` 文件夹: - - `%LocalAppData%\Jellyfin\config` - - `C:\ProgramData\Jellyfin\Server\config` - - 找到 `system.xml` 文件,右键使用记事本打开 - - 在文件中搜索 `true` - - 将 true 改为 false: `false` - - 保存并关闭该文件 - - 重新启动 Jellyfin - - 在浏览器中打开 `http://localhost:8096`,此时系统会弹出首次安装的设置向导 - - 按照向导创建一个全新的管理员账户,添加媒体库的步骤可以跳过 - - 设置完成后,使用新创建的管理员账户登录 + - 定位 Jellyfin 的 `config` 文件夹: + - `%LocalAppData%\Jellyfin\config` + - `C:\ProgramData\Jellyfin\Server\config` + - 找到 `system.xml` 文件,右键使用记事本打开 + - 在文件中搜索 `true` + - 将 true 改为 false: `false` + - 保存并关闭该文件 + - 重新启动 Jellyfin + - 在浏览器中打开 `http://localhost:8096`,此时系统会弹出首次安装的设置向导 + - 按照向导创建一个全新的管理员账户,添加媒体库的步骤可以跳过 + - 设置完成后,使用新创建的管理员账户登录 ### Memos @@ -542,11 +549,11 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `https://memos.your.domain/auth/callback` + - 重定向 URL/Origin: + - `严格` `https://memos.your.domain/auth/callback` - 高级协议设置: - - 已选作用域: `OpenID 'email'` `OpenID 'openid'` - - Subject 模式: `基于用户名` + - 已选作用域: `OpenID 'email'` `OpenID 'openid'` + - Subject 模式: `基于用户名` #### Memos 配置 @@ -592,8 +599,8 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `https://proxmox.your.domain` + - 重定向 URL/Origin: + - `严格` `https://proxmox.your.domain` #### Proxmox 配置 @@ -620,7 +627,7 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 数据中心 - 权限 - 群组 - 点击 创建 - 名称: `[Authentik 用户组名称]-[领域名称]` - - 若 Authentik 用户组名称为 `proxmox-admins`,领域名称为 `SSO`,那么该群组的名称为 `proxmox-admins-SSO` + - 若 Authentik 用户组名称为 `proxmox-admins`,领域名称为 `SSO`,那么该群组的名称为 `proxmox-admins-SSO` **预配置权限**: @@ -641,10 +648,10 @@ Authentik 前端实现由流程、阶段和输入三者构成: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `https://vaultwarden.your.domain/identity/connect/oidc-signin` + - 重定向 URL/Origin: + - `严格` `https://vaultwarden.your.domain/identity/connect/oidc-signin` - 高级协议设置: - - 已选作用域: `OpenID 'email'` `OpenID 'openid'` `OpenID 'profile'` `OpenID 'offline_access'` + - 已选作用域: `OpenID 'email'` `OpenID 'openid'` `OpenID 'profile'` `OpenID 'offline_access'` #### Vaultwarden 配置 @@ -670,8 +677,8 @@ environment: - 转至 应用程序 - 应用程序 - 以提供程序创建 - 协议设置: - - 重定向 URL/Origin: - - `严格` `https://wallos.your.domain` + - 重定向 URL/Origin: + - `严格` `https://wallos.your.domain` #### Wallos 配置 @@ -689,6 +696,10 @@ environment: - Scopes: `openid` `email` `profile` - 当使用 OIDC 登录时自动创建用户/禁用密码登录: (依照实际情况) +### Immich + +请参照 [OAuth Authentication | Immich](https://docs.immich.app/administration/oauth) 完成。 + ## 参考/进一步阅读 - [Memos 对接 Authentik | 某科学的贝壳](https://blog.ning.moe/posts/authentik-OAuth2-memos/)