在业务系统越来越多、内部工具越来越分散的背景下统一身份认证Single Sign-OnSSO几乎是每个技术团队都绕不开的基建需求。之前我在搭建内部平台时尝试过自己写登录认证模块也评估过不少开源方案最后选择了 authentik。它既能当身份提供方IdP也能对接现有的 LDAP / OAuth2 / SAML 体系部署方式足够轻量社区也比较活跃。这篇文章会把 authentik 从概念到部署再到接入应用的完整流程整理出来希望能帮你快速上手。1. authentik 是什么它能解决什么问题先聊一个实际场景。假设公司内部有 GitLab、Jenkins、Grafana、Wiki 等多个系统每个系统都有自己的账号体系。员工入职时要分别在各个平台创建账号离职时要逐个注销密码策略也各不相同。维护成本高不说还容易留下僵尸账号带来安全风险。authentik 要解决的就是这类问题。它是一个开源的身份认证与身份管理平台定位是Identity ProviderIdP同时支持SSO单点登录、MFA多因素认证、LDAP 目录服务、用户生命周期管理等功能。简单来说它把“账号认证”这件事从各个业务系统里抽离出来做成一个统一的基础服务其他系统只需要通过标准协议对接即可。从技术实现角度来看authentik 的核心组件由 Go 编写同时在流程编排部分使用了 Python具体版本会随官方发布变化数据库默认采用 PostgreSQL缓存使用 Redis。它对外提供 Web 管理界面也提供完整的 REST API适合以“基础设施”的方式嵌入到团队的技术栈中。它的几个核心价值可以概括为能力说明统一登录用户只需要记住一套账号密码登录一次即可访问多个系统标准协议原生支持 OAuth2 / OIDC / SAML / LDAP / Proxy 等多种接入方式灵活编排认证流程Flow和认证步骤Stage可以自由组合安全增强内置 MFA、密码策略、Session 管理等安全能力开源透明代码开源可自托管数据由自己掌控需要区分的是authentik 并不是一个“API 网关”它不负责转发业务请求也不做接口鉴权。它更专注于“你是谁”这个问题至于“你能访问什么”由业务系统根据认证返回的用户属性自行决定。理解这个边界对后续架构设计很重要。2. 环境准备与版本说明authentik 官方推荐使用 Docker Compose 方式部署这也是目前最简单、最稳定的方式。它会同时启动多个服务包括server主服务负责处理认证请求和 APIworker后台任务服务处理邮件发送、事件通知等异步任务postgresql主数据库redis缓存与临时数据存储如果你的服务器还没安装 Docker 和 Docker Compose可以先用下面命令确认环境docker --version docker compose version如果没有安装可以参考 Docker 官方文档安装本文不再赘述。需要提醒的是不同操作系统的 Docker 安装方式不同安装完成后需要确保当前用户有权限执行 Docker 命令。关于版本authentik 的版本更新节奏比较快不同版本之间的配置项可能会有细微差异。本文示例以官方文档推荐的 Docker Compose 部署方式为主重点演示配置思路。你在实际操作时建议使用官方最新的稳定版本号不要盲目使用 latest 标签。为了便于管理建议在服务器上创建独立目录例如/opt/authentik所有相关文件都放在这个目录下。后续升级、备份、迁移都会方便很多。sudo mkdir -p /opt/authentik cd /opt/authentik3. 核心概念与认证原理在动手部署之前有必要先理解 authentik 的几个核心概念。如果跳过这部分直接配置后面很容易被各种名词绕晕。3.1 Provider 与 Application在 authentik 中Provider提供方和Application应用是两个最容易混淆的概念。Provider 定义了“以什么协议对外提供服务”。例如你可以创建以下类型的 ProviderOAuth2 / OIDC Provider适合现代 Web 应用、移动端应用SAML Provider适合企业级应用、老牌系统LDAP Provider可以让 authentik 作为一个 LDAP 目录服务供支持 LDAP 认证的系统对接Proxy Provider适合需要反向代理认证的 Web 服务Application 则是“某个具体业务系统的注册信息”。一个 Application 可以关联一个 Provider也可以关联多个 Provider例如同一应用同时支持 OIDC 和 SAML 两种接入方式。理解这两者的关系可以类比为“接口定义”和“接口实现”。Provider 是协议模板Application 是实际接入方。3.2 Flow 与 StageFlow流程和 Stage阶段是 authentik 最灵活的编排机制。Stage 是认证过程中一个独立步骤比如用户名密码校验MFA 验证用户信息填写同意授权页面验证码验证Flow 则是由多个 Stage 按顺序组成的完整流程。例如“登录流程”可能包含“用户名密码验证”和“MFA 验证”两个阶段“注册流程”可能包含“填写基本信息”“验证邮箱”“设置密码”等阶段。authentik 预置了多种默认 Flow比如default-authentication-flow默认登录流程default-enrollment-flow默认注册流程default-password-change-flow密码修改流程default-recovery-flow密码找回流程你可以直接使用这些默认流程也可以复制后修改添加或删减 Stage。这种设计让 authentik 能适配各种个性化的认证需求。3.3 OAuth2 / OIDC 接入流程OIDCOpenID Connect是在 OAuth2 基础上扩展的身份认证协议目前是 authentik 集成应用时最常用的方式。它的核心流程如下用户访问第三方应用应用发现用户未登录应用将用户重定向到 authentik 的授权端点authentik 校验用户身份登录、MFAauthentik 将用户重定向回应用并携带授权码应用后端用授权码向 authentik 换取 ID Token 和 Access Token应用验证 Token获取用户信息完成登录从整体来看authentik 充当的是“集中认证中心”的角色。第三方应用不再关心用户密码如何校验、Session 如何管理只需要相信 authentik 返回的 Token 即可。4. 完整实战Docker Compose 部署 authentik这一节我们从零开始完成 authentik 的部署。4.1 准备 docker-compose.yml进入/opt/authentik目录创建docker-compose.yml文件version: 3.8 services: postgresql: image: docker.io/library/postgres:16-alpine restart: unless-stopped volumes: - database:/var/lib/postgresql/data environment: - POSTGRES_DB${PG_DB} - POSTGRES_USER${PG_USER} - POSTGRES_PASSWORD${PG_PASS} redis: image: docker.io/library/redis:7-alpine restart: unless-stopped command: --save 60 1 --loglevel warning volumes: - redis:/data server: image: ghcr.io/goauthentik/server:${AUTHENTIK_TAG} restart: unless-stopped command: server environment: - AUTHENTIK_REDIS__HOSTredis - AUTHENTIK_POSTGRESQL__HOSTpostgresql - AUTHENTIK_POSTGRESQL__USER${PG_USER} - AUTHENTIK_POSTGRESQL__NAME${PG_DB} - AUTHENTIK_POSTGRESQL__PASSWORD${PG_PASS} - AUTHENTIK_SECRET_KEY${AUTHENTIK_SECRET_KEY} - AUTHENTIK_ERROR_REPORTING__ENABLED${AUTHENTIK_ERROR_REPORTING__ENABLED} - AUTHENTIK_COOKIE_DOMAIN${AUTHENTIK_COOKIE_DOMAIN} volumes: - ./media:/media - ./custom-templates:/templates ports: - ${COMPOSE_PORT_HTTP:-9000}:9000 - ${COMPOSE_PORT_HTTPS:-9443}:9443 depends_on: - postgresql - redis worker: image: ghcr.io/goauthentik/server:${AUTHENTIK_TAG} restart: unless-stopped command: worker environment: - AUTHENTIK_REDIS__HOSTredis - AUTHENTIK_POSTGRESQL__HOSTpostgresql - AUTHENTIK_POSTGRESQL__USER${PG_USER} - AUTHENTIK_POSTGRESQL__NAME${PG_DB} - AUTHENTIK_POSTGRESQL__PASSWORD${PG_PASS} - AUTHENTIK_SECRET_KEY${AUTHENTIK_SECRET_KEY} - AUTHENTIK_ERROR_REPORTING__ENABLED${AUTHENTIK_ERROR_REPORTING__ENABLED} - AUTHENTIK_COOKIE_DOMAIN${AUTHENTIK_COOKIE_DOMAIN} volumes: - ./media:/media - ./custom-templates:/templates depends_on: - server volumes: database: redis:这个文件里需要注意几个点ghcr.io/goauthentik/server是官方镜像地址AUTHENTIK_TAG变量决定镜像版本postgresql和redis的数据通过 Docker Volume 持久化避免容器删除后数据丢失server同时映射 9000HTTP和 9443HTTPS端口worker与server使用相同的镜像和环境变量只是启动命令不同depends_on确保服务按顺序启动4.2 配置 .env 环境变量创建.env文件用于存放环境变量# authentik 镜像版本 AUTHENTIK_TAG2024.12.2 # PostgreSQL 配置 PG_DBauthentik PG_USERauthentik PG_PASS请替换为随机强密码 # authentik 核心密钥务必替换为随机字符串 AUTHENTIK_SECRET_KEY请替换为至少32位的随机字符串 # 错误上报开关建议关闭 AUTHENTIK_ERROR_REPORTING__ENABLEDfalse # Cookie 域名生产环境建议配置为你的域名 AUTHENTIK_COOKIE_DOMAINexample.com # 端口映射 COMPOSE_PORT_HTTP9000 COMPOSE_PORT_HTTPS9443这里有一个需要特别提醒的地方AUTHENTIK_SECRET_KEY是 authentik 用于加密 Session、Token 等敏感数据的密钥一旦部署完成并产生数据后续不要随意修改否则会导致已登录用户 Session 失效。生成密钥可以使用以下命令openssl rand -hex 32另外PG_PASS是 PostgreSQL 的密码也建议使用随机强密码。不要把生产环境的数据库密码设置成弱密码。AUTHENTIK_COOKIE_DOMAIN的含义是限定 authentik Session Cookie 生效的域名。如果你有多个子域系统接入 authentik可以配置为共同的父域名例如example.com这样server1.example.com和server2.example.com共享认证状态。如果是纯 IP 访问或单域名测试可以留空。4.3 启动服务确认文件就绪后在/opt/authentik目录下执行docker compose up -d首次启动会拉取多个镜像耗时取决于网络状况。等待一段时间后查看容器状态docker compose ps正常情况下所有服务的状态都应该是Up。如果某个服务反复重启可以查看日志定位问题docker compose logs -f server服务启动后authentik 需要执行一次数据库初始化并在数据库中创建初始用户。打开浏览器访问http://你的服务器IP:9000或者 HTTPS 方式https://你的服务器IP:9443由于默认使用的是自签名证书浏览器会提示证书不受信任本地测试可以点击“继续访问”。生产环境建议在 authentik 前面加一层 Nginx / Caddy配置正式证书后对外提供服务。4.4 初始化管理员账号首次访问时authentik 会进入初始化引导界面要求创建管理员账号。填写邮箱和用户名设置强密码即可完成初始化。这里特别强调初始管理员密码务必妥善保存。如果忘记密码后续需要通过命令行方式重置操作会比较麻烦。初始化完成后使用管理员账号登录就进入了 authentik 的管理后台。4.5 验证部署结果登录管理后台后可以看到左侧菜单包含 Dashboard、Applications、Flows、Directory、System 等模块。在 Dashboard 页面可以查看系统版本和资源状态这就说明 authentik 的核心服务已经正常运行了。5. 实战接入一个第三方应用OIDC 方式部署只是第一步。接下来我们以一个典型的内部 Web 应用为例演示如何通过 OIDC 协议接入 authentik。5.1 创建 Provider在 authentik 管理后台中依次进入Applications Providers点击Create。表单关键字段说明NameProvider 名称建议包含应用名和协议例如GitLab OIDC ProviderAuthorization flow选择授权流程通常使用default-provider-authorization-explicit-consent这里是授权时是否展示同意页面的控制Client TypeConfidential表示需要客户端密钥Client ID / Client Secret可以自己填写也可以留空让系统生成。推荐让系统自动生成Redirect URIs / Origins填写第三方应用的回调地址。例如 GitLab 的 OIDC 回调地址是https://gitlab.example.com/users/auth/openid_connect/callback创建完成后Provider 列表里会生成一条记录包含 Client ID 和 Client Secret。这部分信息需要填到第三方应用中。5.2 关联 Application在Applications Applications页面点击Create创建一个 ApplicationName例如GitLabSlug建议使用英文短横线格式例如gitlabProvider选择上一步创建的 Provider保存后第三方应用与 authentik 之间的绑定关系就建立起来了。5.3 在第三方应用中配置 OIDC这里以常见的通用 OIDC 客户端为例。无论使用哪个框架都需要配置以下信息# 认证端点 Authorization Endpoint: https://auth.example.com/application/o/authorize/ # Token 端点 Token Endpoint: https://auth.example.com/application/o/token/ # 用户信息端点 Userinfo Endpoint: https://auth.example.com/application/o/userinfo/ # 登出端点 End Session Endpoint: https://auth.example.com/application/o/{slug}/end-session/以 Python 的Authlib库为例客户端配置大致如下from authlib.integrations.requests_client import OAuth2Session client OAuth2Session( client_id你的ClientID, client_secret你的ClientSecret, redirect_urihttps://your-app.example.com/callback, scopeopenid profile email, ) # 生成跳转链接 authorization_url, state client.create_authorization_url( https://auth.example.com/application/o/authorize/ )回调地址处理逻辑# 回调后获取 Token token client.fetch_token( https://auth.example.com/application/o/token/, authorization_responserequest.url, grant_typeauthorization_code, ) # 获取用户信息 userinfo client.get(https://auth.example.com/application/o/userinfo/).json()不管是 Java 的 Spring Security、Node.js 的 Passport.js还是 Go 的 oidc 库原理都是相通的重定向到授权端点拿授权码换 Token再用 Token 获取用户信息。5.4 验证登录流程配置完成后访问第三方应用点击登录时会被重定向到 authentik 的登录页面。输入账号密码后如果 Provider 配置了授权确认页面还会看到一次授权确认确认后自动跳转回第三方应用。此时第三方应用已经拿到 authentik 返回的用户信息包括sub用户唯一标识、email、name等字段。业务系统可以用来创建本地会话、绑定内部账号、做权限映射。6. 常见问题与排查思路在实际部署和接入过程中我整理了几个高频问题按现象、原因、解决思路列出。问题现象常见原因解决思路容器启动后不断重启数据库连接失败或环境变量缺失检查.env中数据库密码与docker-compose.yml是否一致查看docker compose logs postgresql访问 9000 端口无响应防火墙未放行端口或容器未启动成功检查防火墙规则确认docker compose ps中 server 状态为 Up登录页面能打开但无法登录初始用户密码遗忘或 Session 密钥异常使用ak命令重置密码检查AUTHENTIK_SECRET_KEY是否稳定第三方应用回调报 redirect_uri 不匹配Provider 中配置的回调地址与实际不一致严格对比回调地址注意 HTTP/HTTPS、域名、端口、路径完全一致使用自签名证书时应用报证书错误第三方应用不信任 authentik 的自签证书生产环境配置可信证书测试环境可临时跳过证书校验登录成功但拿不到用户信息Scope 未包含openid profile email确认客户端请求 scope 包含所需字段修改了.env后配置不生效没有重置容器执行docker compose up -d重新创建容器必要时执行docker compose down docker compose up -d这里单独说一下重置管理员密码的方法。如果管理员密码遗忘可以进入server容器执行命令docker compose exec server ak create_recovery_key 管理员用户名 --token -o /dev/stdout执行后命令会输出一个一次性链接用浏览器访问该链接即可进入重置密码页面。需要注意的是这个链接有有效期限制生成后应尽快使用。7. 最佳实践与工程建议authentik 作为身份认证基础设施一旦投入生产环境它的稳定性和安全性直接影响所有接入系统。下面这些建议都是我在实际使用中觉得比较重要的点。7.1 版本管理与升级策略不要把镜像标签写成latest。生产环境应固定到具体版本号升级前先阅读官方 changelog确认是否有破坏性变更。升级操作建议在业务低峰期执行操作前备份数据库。# 备份数据库示例 docker compose exec postgresql pg_dump -U authentik authentik authentik_backup_$(date %Y%m%d).sql数据备份无小事尤其是身份认证系统的数据丢失后影响范围是非常大的。7.2 反向代理与 TLS 配置生产环境不建议直接把 authentik 的 9000 和 9443 端口暴露到公网。推荐前面加一层反向代理例如 Nginx由反向代理统一管理 HTTPS 证书。关键配置示例如下server { listen 80; server_name auth.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name auth.example.com; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; client_max_body_size 25M; location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }配置反向代理后AUTHENTIK_COOKIE_DOMAIN和外部访问地址要统一规划保证回调地址、Cookie 域、代理域名之间不冲突。7.3 用户目录与权限模型authentik 自带的用户体系适合中小团队但如果公司已经存在 AD / LDAP / 飞书 / 钉钉等身份源建议优先通过 authentik 的Source功能对接现有目录避免重复维护一套账号体系。在权限模型方面authentik 支持 Group 和 Role。建议按“业务角色”而非“个人”来分配权限例如dev-team、ops-team、admin等。这样后续人员变动时只需要调整用户所在组不需要逐个应用修改授权。7.4 租户与环境隔离如果公司有多个环境测试环境、预发环境、生产环境建议根据实际情况决定是否拆分 authentik 实例。测试环境和生产环境使用同一套 authentik 实例可以简化账号管理但要注意客户端 ID 和回调地址不要混淆。对于安全等级较高的生产环境更推荐单独部署独立的 authentik 实例实现完全隔离。7.5 安全加固清单从安全角度以下几个配置项值得优先关注强制 MFA在登录流程中添加 MFA Stage要求管理员账号必须开启 MFA。组织密码策略在 authentik 中配置最小密码长度、复杂度要求避免用户设置弱密码。登录限流配置失败尝试次数限制防止暴力破解。审计日志定期查看 authentik 的管理事件日志关注异常登录行为。最小化暴露authentik 管理后台不应对公网开放至少应限制 IP 访问范围。7.6 监控与告警作为基础设施authentik 的运行状态需要纳入监控体系。至少监控以下指标容器存活状态PostgreSQL 磁盘使用率Redis 内存使用率authentik 登录失败率异常升高如果公司已经有 Prometheus Grafana可以通过 exporter 采集相关指标。没有专业监控体系的小团队至少配置容器重启策略并定期检查日志。8. 总结与下一步学习方向本文从 authentik 的概念入手完整演示了 Docker Compose 部署过程以及通过 OIDC 协议接入第三方应用的流程最后整理了常见排错和最佳实践。掌握了这些内容你已经可以独立部署一个 authentik 实例并把它作为团队内部系统的统一登录入口。接下来可以按方向继续深入Flow / Stage 进阶自定义注册流程、邀请链接、组自动分配等场景对接 LDAP 源把现有 AD / LDAP 中的用户同步到 authentik实现账号统一SAML 协议接入学习如何对接支持 SAML 的旧系统API 二次开发通过 authentik REST API 实现用户批量管理、自动化运维脚本身份认证是所有系统的第一道门也是安全体系里最核心的一环。花些时间把 authentik 的原理和配置吃透后续搭建内部平台时会省下很多不必要的沟通和排错成本。希望这篇文章能帮你少走一些弯路。