Authentik: 搭建属于自己的单点登录服务¶
建议
本文篇幅较长,请善用页内搜索 Ctrl+F 与右侧的文章目录
准备/环境条件¶
- 域名
- Ubuntu 24.04 LTS
- Authentik 2026.2.1
- Traefik (Nginx / Caddy 亦可)
- Docker & Docker Compose
安装¶
安装步骤基本依照 Docker Compose installation - authentik 完成。
首先,编写 docker-compose.yml,Authentik 由 PostgreSQL Server Worker 三部分构成。
services:
authentik_postgresql:
image: docker.io/library/postgres:16-alpine
container_name: authentik_postgresql
volumes:
- /path/to/authentik/database:/var/lib/postgresql/data
networks:
- authentik_network
environment:
POSTGRES_PASSWORD: ${PG_PASS:?database password required}
POSTGRES_USER: ${PG_USER:-authentik}
POSTGRES_DB: ${PG_DB:-authentik}
healthcheck:
interval: 30s
retries: 5
start_period: 20s
test:
- CMD-SHELL
- pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}
timeout: 5s
env_file:
- .env
restart: unless-stopped
authentik_server:
image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2026.2}
container_name: authentik_server
command: server
ports:
- "9000:9000" # For authentik embedded outpost
networks:
- basic_network
- authentik_network
volumes:
- /path/to/authentik/data:/data
- /path/to/authentik/custom-templates:/templates
environment:
AUTHENTIK_POSTGRESQL__HOST: authentik_postgresql
AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
env_file:
- .env
depends_on:
authentik_postgresql:
condition: service_healthy
restart: unless-stopped
shm_size: 512mb
labels:
- "traefik.enable=true"
- "traefik.docker.network=basic_network"
# HTTPS part:
- "traefik.http.routers.authentik-secure.entrypoints=web-secure"
- "traefik.http.routers.authentik-secure.tls=true"
- "traefik.http.routers.authentik-secure.tls.certresolver=letsencrypt"
- "traefik.http.routers.authentik-secure.rule=Host(`your.authentik.domain`)"
- "traefik.http.routers.authentik-secure.middlewares=default@file"
# Upstream part:
- "traefik.http.services.authentik.loadbalancer.server.scheme=http"
- "traefik.http.services.authentik.loadbalancer.server.port=9000" # Authentik default http port
authentik_worker:
image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2026.2}
container_name: authentik_worker
command: worker
networks:
- authentik_network
environment:
AUTHENTIK_POSTGRESQL__HOST: authentik_postgresql
AUTHENTIK_POSTGRESQL__USER: ${PG_USER:-authentik}
AUTHENTIK_POSTGRESQL__NAME: ${PG_DB:-authentik}
AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
user: root
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /path/to/authentik/data:/data
- /path/to/authentik/certs:/certs
- /path/to/authentik/custom-templates:/templates
env_file:
- .env
depends_on:
authentik_postgresql:
condition: service_healthy
restart: unless-stopped
networks:
basic_network:
name: basic_network
authentik_network:
name: authentik_network
然后,创建配置文件 .env,并生成数据库密码和 Authentik 密钥。
touch .env
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
接着,继续编辑配置文件 .env,添加邮件发送配置,以下以腾讯企业邮箱(即企业微信邮箱)为例。
PG_PASS=(Automatically generated from the previous step)
AUTHENTIK_SECRET_KEY=(Automatically generated from the previous step)
# SMTP Host Emails are sent to
AUTHENTIK_EMAIL__HOST=smtp.exmail.qq.com
AUTHENTIK_EMAIL__PORT=465
# Optionally authenticate (don't add quotation marks to your password)
AUTHENTIK_EMAIL__USERNAME=authentik@your.domain
AUTHENTIK_EMAIL__PASSWORD=(Tencent Enterprise Email SMTP password)
# Use StartTLS
AUTHENTIK_EMAIL__USE_TLS=false
# Use SSL
AUTHENTIK_EMAIL__USE_SSL=true
AUTHENTIK_EMAIL__TIMEOUT=10
# Email address authentik will send from, should have a correct @domain
AUTHENTIK_EMAIL__FROM=authentik@your.domain
最后,启动 Authentik 服务。
Authentik 正常启动后,请访问 https://your.authentik.domain/if/flow/initial-setup/ 完成初始化配置。
自定义¶
流程、阶段和输入¶
Authentik 前端实现由流程、阶段和输入三者构成:
- 流程是由一系列用于对用户进行身份验证、注册或恢复的阶段构成。
- 阶段是引导用户完成流程的单个步骤。
- 输入是可用于输入阶段的单个输入项。
自定义流程、阶段和输入有两种办法:
- 手动编辑
- 导入流程蓝图: 管理员界面 - 流程与阶段 - 流程 - 导入
验证码阶段: Cloudflare Turnstile (可选)¶
Cloudflare:
- (当前项目) - 应用程序安全 - Turnstile
- 小组件名称: (随意)
- 主机名管理: (按实际情况)
- 小组件模式: 托管
- 您是否要为此站点选择预先许可: 否
Authentik:
- 管理员界面 - 流程与阶段 - 阶段 - 创建
- 选择
Captcha Stage - Stage Name: (随意)
- 提供程序类型:
Cloudflare Turnstile - 公钥: (Cloudflare 提供的站点密钥)
- Secret Key: (Cloudflare 提供的密钥)
登录流程优化¶
- 管理员界面 - 流程与阶段 - 阶段 - (身份验证阶段) - 流程绑定 - 编辑流程
- default-authentication-identification:
- 密码流程
- 验证码流程
- WebAuthn 身份验证器验证流程
- 无密码流程
- 恢复流程
- default-authentication-mfa-validation:
- 设备类型:
静态令牌TOTP 身份验证器WebAuthn 身份验证器 - 未配置操作: 强制用户配置身份验证器
- 配置阶段:
- default-authenticator-webauthn-setup
- default-authenticator-totp-setup
- WebAuthn 用户验证: 如果可用,则首选用户验证,但不是必需的。
- 设备类型:
外观¶
- 转至 管理员界面 - 系统 - 品牌
- 域名:
authentik.your.domain- 品牌设置:
- 标题
- ...
- 默认流程:
- 恢复流程
- 删除账户流程
- ...
- 品牌设置:
对接支持 OAuth2/OpenID 的应用¶
进入 Authentik 管理员界面后,找到应用程序 - 应用程序 - 以提供程序创建。
第一步 应用程序:
- 应用名称: 任意字符
- Slug: 英文字符与数字
- 应用界面设置:
- 启动 URL: 对应应用的登录界面
第二步 选择提供程序: OAuth2/OpenID Provider
第三步 配置提供程序:
- 授权流程:
- default-provider-authorization-implicit-consent: 用户通过 Authentik 登录对应应用时不需要点击“授权”
- default-provider-authorization-explicit-consent: 用户通过 Authentik 登录对应应用时需要点击“授权”
- 协议设置:
- 客户端类型: 机密
- 客户端 ID: (自动生成,复制备用)
- 客户端 Secret: (自动生成,复制备用)
- 重定向 URL/Origin: (按照应用实际情况添加)
- 高级流程设置:
- 失效流程: default-provider-invalidation
第四步 配置绑定: (跳过,可后续按照实际情况设置)
第五步 检查与提交应用程序: (检查无误后,点击“提交”)
OpenList/AList¶
以下步骤基本参照 单点登录 - OpenList文档 完成。
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
注意
- 记得将
your.openlist.domain替换为你的 OpenList 对应的 FQDN. ?前的\是正则表达式中的转义字符,必须保留。
获取 JWT 证书:
- 转至 系统 - 证书
- 找到
authentik Self-signed Certificate,点击列表左侧的> - 点击
下载证书以获取 JWT 证书
OpenList/AList 配置¶
建议
建议默认管理员账户不绑定单点绑定服务,以避免可能的权限混乱。
转至 OpenList/AList 管理 - 设置 - 单点登录
- SSO 登录启用: 是
- SSO 登录平台:
OIDC - SSO 客户端 ID: (Authentik 中对应应用的提供程序的客户端 ID)
- SSO 客户端密钥: (Authentik 中对应应用的提供程序的客户端 Secret)
- OIDC 用户名键:
preferred_username - 组织名称:
user - SSO 应用名称:
user - SSO 端点名称: (Authentik 中对应应用的提供程序的OpenID 配置颁发者)
- SSO JWT 公钥: 打开先前下载的 JWT 证书,并将全部内容粘贴在输入框中。应以 -----BEGIN CERTIFICATE----- 开头。
- SSO 额外范围: (空)
- SSO 自动注册: (按需启用)
- SSO 默认根目录:
/(可根据实际情况调整) - SSO 默认权限:
- 默认为
0,后续可通过管理界面为用户手动赋权。 - 请参考SSO默认权限 - OpenList文档
- 默认为
- SSO 兼容模式: 否
Gitea¶
以下配置为个人整理,可能存在错误和缺漏,仅供参考。
Authentik 配置¶
配置属性映射:
- 转至 自定义 - 属性映射
- 点击 “创建”
- 选择类型:
Scope Mapping - 创建 Scope Mapping:
- 名称:
gitea - 作用域名称:
gitea - 表达式:
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
- 名称:
设立用户组与添加已有用户进入用户组:
请分别创建名为 gitadmin gituser gitrestricted 的用户组。
- 转至 目录 - 组
- 点击 “新建组”
- 组名:
gitadmingitusergitrestricted - 超级用户权限: 否
- 父级: (空)
- 角色: (空)
- 属性: (保持默认)
接下来,将已有的用户添加进入对应的用户组。
- 点击
gitadmingituser或gitrestricted用户组 - 点击 用户 - 添加已有用户
- 将用户添加进入
gitadmin用户组意味着将授予该用户 Gitea 管理员权限 - 将用户添加进入
gituser用户组意味着允许该用户正常使用 Gitea - 将用户添加进入
gitrestricted用户组意味着用户将不可使用 Gitea
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格https://gitea.your.domain/user/oauth2/[auth_name]/callback[auth_name]必须与 Gitea 配置中的认证名称保持一致,大小写敏感。
- 重定向 URL/Origin:
- 高级协议设置:
- 作用域:
- 已选作用域:
OpenID 'email'OpenID 'openid'OpenID 'profile'gitea
- 已选作用域:
- 作用域:
Gitea 配置¶
- 转至 管理后台 - 身份及认证 - 认证源 - 添加认证源
- 认证类型:
OAuth2 - 认证名称: (必须与 Authentik 配置中的
[auth_name]保持一致,大小写敏感) - OAuth2 提供程序:
OpenID Connect - 客户端 ID: (Authentik 中对应应用的提供程序的客户端 ID)
- 客户端密钥: (Authentik 中对应应用的提供程序的客户端 Secret)
- 图标URL: (按照实际情况填写)
- OpenID 连接自动发现 URL: (Authentik 中对应应用的提供程序的OpenID 配置 URL)
- 附加授权范围 (Scopes):
email profile gitea openid - 全名声明名称/SSH 公钥声明名称: (空)
- 必须填写 Claim 声明的名称:
gitea - 用于提供用户组名称的 Claim 声明名称:
gitea - 管理员用户组的 Claim 声明值:
admin - 受限用户组的 Claim 声明值:
restricted - 如果用户不属于相应的组,从已同步团队中移除用户/启用用户同步/该认证源已经启用: 是
Grafana¶
建议
在继续操作前,请确保您拥有另一个管理员账户。
如果将 Authentik 关联到 Grafana 上唯一的管理员账户,权限可能会被覆盖。
以下配置为个人整理,可能存在错误和缺漏,仅供参考。
Authentik 配置¶
配置属性映射:
- 转至 自定义 - 属性映射
- 点击 “创建”
- 选择类型:
Scope Mapping - 创建 Scope Mapping:
- 名称:
grafana - 作用域名称:
grafana - 表达式:
- 名称:
设立用户组与添加已有用户进入用户组:
请分别创建名为 Grafana Admins Grafana Editors 的用户组。
- 转至 目录 - 组
- 点击 “新建组”
- 组名:
Grafana AdminsGrafana Editors - 超级用户权限: 否
- 父级: (空)
- 角色: (空)
- 属性: (保持默认)
接下来,将已有的用户添加进入对应的用户组。
- 点击
Grafana AdminsGrafana Editors用户组 - 点击 用户 - 添加已有用户
- 将用户添加进入
Grafana Admins用户组意味着将授予该用户 Grafana 管理员权限 - 将用户添加进入
Grafana Editors用户组意味着允许该用户修改仪表盘数据 - 不属于上述用户组的用户仅可查看公开的仪表盘
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格https://grafana.your.domain/login/generic_oauth
- 重定向 URL/Origin:
- 高级协议设置:
- 作用域:
- 已选作用域:
OpenID 'email'OpenID 'openid'OpenID 'profile'grafana
- 已选作用域:
- 作用域:
Grafana 配置¶
- 转至 管理 - 身份验证 - Generic OAuth
- 一般设置:
- 显示名称: (随意)
- Client ID: (Authentik 中对应应用的提供程序的客户端 ID)
- Client secret: (Authentik 中对应应用的提供程序的客户端 Secret)
- 身份验证样式: (保持默认)
- Scopes:
emailprofileopenidgrafana - OpenID Connect Discovery URL: (Authentik 中对应应用的提供程序的OpenID 配置 URL)
- 允许注册/自动登录: (按照实际情况)
- 退出登录重定向网址: (Authentik 中对应应用的提供程序的注销 URL)
- 登录提示: (空)
- 用户映射:
- 角色属性路径:
grafana - 角色属性严格模式/允许分配 Grafana 管理员: 是
- 角色属性路径:
Jellyfin¶
以下内容综合自 jellyfin-plugin-sso/providers.md at main · 9p4/jellyfin-plugin-sso 与 Integrate with Jellyfin | authentik。
Authentik 配置¶
设立用户组与添加已有用户进入用户组:
请创建名为 jellyfin 的用户组。
- 转至 目录 - 组
- 点击 “新建组”
- 组名:
jellyfin - 超级用户权限: 否
- 父级: (空)
- 角色: (空)
- 属性: (保持默认)
接下来,将已有的用户添加进入对应的用户组。
- 点击
jellyfin用户组 - 点击 用户 - 添加已有用户
- 将用户添加进入
jellyfin用户组意味着用户可正常使用 Jellyfin
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格http://jellyfin.your.domain/sso/OID/redirect/[Name of OpenID Provider][Name of OpenID Provider]必须与 Jellyfin 配置中的Name of OpenID Provider保持一致,大小写敏感。
- 重定向 URL/Origin:
Jellyfin 配置¶
安装 SSO-Auth 插件:
- 转至 管理 - 控制台 - 插件
- 点击 “管理存储库” - “新建存储库”
- 存储库名称:
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)
- OpenID Client ID: (Authentik 中对应应用的提供程序的客户端 ID)
- OpenID client secret: (Authentik 中对应应用的提供程序的客户端 Secret)
- Enabled/Enable Authorization by Plugin/Enable All Folders: 是
- Roles:
jellyfin - Enable Live TV RBAC: 是
- Live TV Roles:
jellyfin - Role Claim:
groups - Request Additional Scopes:
["groups"]
恢复 Jellyfin 管理员权限 (错误配置 SSO-Auth 插件)¶
以下内容基于 Windows 11 & Jellyfin Server 10.11.6,仅供参考。
- 暂时移除 SSO 插件:
- 停止 Jellyfin 服务器
- 定位 Jellyfin 的
plugins文件夹:%LocalAppData%\Jellyfin\pluginsC:\ProgramData\Jellyfin\Server\plugins
- 找到名为 sso-auth (或类似名称)的文件夹,将其剪切并移动到桌面暂时备份
- 重新触发配置向导:
- 定位 Jellyfin 的
config文件夹:%LocalAppData%\Jellyfin\configC:\ProgramData\Jellyfin\Server\config
- 找到
system.xml文件,右键使用记事本打开 - 在文件中搜索
<IsStartupWizardCompleted>true</IsStartupWizardCompleted> - 将 true 改为 false:
<IsStartupWizardCompleted>false</IsStartupWizardCompleted> - 保存并关闭该文件
- 重新启动 Jellyfin
- 在浏览器中打开
http://localhost:8096,此时系统会弹出首次安装的设置向导 - 按照向导创建一个全新的管理员账户,添加媒体库的步骤可以跳过
- 设置完成后,使用新创建的管理员账户登录
- 定位 Jellyfin 的
Memos¶
Authentik 配置¶
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格https://memos.your.domain/auth/callback
- 重定向 URL/Origin:
- 高级协议设置:
- 已选作用域:
OpenID 'email'OpenID 'openid' - Subject 模式:
基于用户名
- 已选作用域:
Memos 配置¶
- 转至 设置 - 管理 - 单点登录 - 创建
- 类型:
OAUTH2 - 模板:
Custom - 名称: (随意)
- 标识符过滤器: (空)
- 客户端ID: (Authentik 中对应应用的提供程序的客户端 ID)
- 客户端密钥: (Authentik 中对应应用的提供程序的客户端 Secret)
- 授权端点: (Authentik 中对应应用的提供程序的授权 URL)
- 令牌端点: (Authentik 中对应应用的提供程序的令牌 URL)
- 用户端点: (Authentik 中对应应用的提供程序的用户信息 URL)
- 范围:
openidemail - 标识符:
sub - 显示名称:
sub - 邮箱:
email - Avatar URL: (空)
Proxmox¶
Authentik 配置¶
设立用户组与添加已有用户进入用户组:
请创建名为 proxmox-admins 的用户组。
- 转至 目录 - 组
- 点击 “新建组”
- 组名:
proxmox-admins - 超级用户权限: 否
- 父级: (空)
- 角色: (空)
- 属性: (保持默认)
接下来,将已有的用户添加进入对应的用户组。
- 点击
proxmox-admins用户组 - 点击 用户 - 添加已有用户
- 将用户添加进入
proxmox-admins用户组意味着用户将具有 Proxmox 面板与服务器的管理员权限
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格https://proxmox.your.domain
- 重定向 URL/Origin:
Proxmox 配置¶
配置单点登录:
- 转至 数据中心 - 权限 - 领域
- 点击 添加 - OpenID 连接服务器
- 发行人URL: (Authentik 中对应应用的提供程序的OpenID 配置颁发者)
- 领域: (指单点登录服务的名称,随意)
- 客户端 ID: (Authentik 中对应应用的提供程序的客户端 ID)
- 客户端秘钥: (Authentik 中对应应用的提供程序的客户端 Secret)
- 范围: (保持默认)
- 默认: (按照实际情况)
- 自动创建用户: 是
- 用户名声明:
username - Autocreate Groups: 否
- Groups Claim:
groups - Overwrite Groups: 否
- 提示: (保持默认)
- Query userinfo endpoint: 是
创建群组:
- 转至 数据中心 - 权限 - 群组
- 点击 创建
- 名称:
[Authentik 用户组名称]-[领域名称]- 若 Authentik 用户组名称为
proxmox-admins,领域名称为SSO,那么该群组的名称为proxmox-admins-SSO
- 若 Authentik 用户组名称为
预配置权限:
- 转至 数据中心 - 权限
- 点击 添加 - 群组权限
- 路径:
/ - 群组: (上一步创建的群组)
- 角色:
Administrator - 继承: 是
Vaultwarden¶
以下内容基本参照 Enabling SSO support using OpenId Connect · dani-garcia/vaultwarden Wiki 完成。
Authentik 配置¶
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格https://vaultwarden.your.domain/identity/connect/oidc-signin
- 重定向 URL/Origin:
- 高级协议设置:
- 已选作用域:
OpenID 'email'OpenID 'openid'OpenID 'profile'OpenID 'offline_access'
- 已选作用域:
Vaultwarden 配置¶
将以下内容添加进入 docker-compose.yml 文件 vaultwarden 服务的 environment 部分:
environment:
SIGNUPS_ALLOWED: false # 不允许注册
SSO_ENABLED: true # 启用 SSO
SSO_ONLY: false # 仅采用 SSO 登录,不允许密码登录
SSO_SIGNUPS_MATCH_EMAIL: true # SSO 登录需匹配已有账户的邮箱
SSO_AUTHORITY: "xxx" # Authentik 中对应应用的提供程序的 OpenID 配置颁发者
SSO_SCOPES: "openid profile email offline_access"
SSO_CLIENT_ID: "xxx" # Authentik 中对应应用的提供程序的客户端 ID
SSO_CLIENT_SECRET: "xxx" # Authentik 中对应应用的提供程序的客户端 Secret
Wallos¶
Authentik 配置¶
配置提供程序:
- 转至 应用程序 - 应用程序 - 以提供程序创建
- 协议设置:
- 重定向 URL/Origin:
严格https://wallos.your.domain
- 重定向 URL/Origin:
Wallos 配置¶
- 转至 管理员 - OIDC 设置
- Enable OIDC/OAuth: 是
- Provider Name: (随意)
- Client ID: (Authentik 中对应应用的提供程序的客户端 ID)
- Client Secret: (Authentik 中对应应用的提供程序的客户端 Secret)
- Auth URL: (Authentik 中对应应用的提供程序的授权 URL)
- Token URL: (Authentik 中对应应用的提供程序的令牌 URL)
- User Info URL: (Authentik 中对应应用的提供程序的用户信息 URL)
- Redirect URL:
https://wallos.your.domain - Logout URL: (Authentik 中对应应用的提供程序的注销 URL)
- User Identifier Field:
sub - Scopes:
openidemailprofile - 当使用 OIDC 登录时自动创建用户/禁用密码登录: (依照实际情况)
Immich¶
请参照 OAuth Authentication | Immich 完成。