统一认证实践(11)Authentik 接入 code-server 与 Caddy 前哨认证
创建于 2026-11-16
更新于 2026-11-18
科技
Debian
code-server
Caddy
docker
authentik
3902 字 · 约 14 分钟

前言

code-server 已通过 Caddy 提供 HTTPS,日常可以在浏览器中使用编辑器和终端。接入 DoraTiger Auth 后,希望复用现有登录与 MFA,不再重复输入 code-server 自己的密码。

这个入口可以执行开发机上的命令,因此只向专用管理员组开放。本次沿用已有 Debian 原生 code-server 服务,在同机增加 Authentik Proxy Outpost 2026.8.5,由 Caddy 完成 Forward Auth。

一、认证与运行身份

基础安装和 HTTPS 配置见 Homelab 搭建手记(7)部署 code-server 并配置 HTTPS 访问。本文在已有服务上增加认证:

text
1
2
3
4
5
浏览器 → Caddy :443 → code-server 127.0.0.1:30080 ↕ Outpost 127.0.0.1:30092 ↕ 云端 Authentik

code-server 不处理 OIDC,也不按 Authentik 用户创建 Linux 账号。通过认证的人进入的是同一个 code-server 进程、同一个系统用户的文件和终端。需要多人独立开发环境时,应分别部署实例或选择具备工作空间隔离的平台。

二、Authentik 应用配置

2.1 专用管理员组

进入“目录 → 组”,创建 debian-code-server-admins,不启用 Authentik 超级用户权限,保存后仅加入可信的开发机管理员。

2.2 Proxy Provider 与应用

在“应用程序 → 提供者 → 创建”选择 Proxy Provider:

字段 配置
Name doratiger-debian-code-server
Authentication flow doratiger-authentication
Authorization flow doratiger-provider-authorization-implicit-consent
Invalidation flow doratiger-provider-invalidation
Mode Forward auth (single application)
External host https://code.example.com
Unauthenticated paths 留空
HTTP Basic 转发 关闭

保存后在应用列表选择 with existing provider,名称填 Debian · code-server,Slug 填 debian-code-server,选择刚创建的 Provider,Launch URL 填 HTTPS 入口。

进入应用的策略/组/用户绑定,添加 debian-code-server-admins,Order 为 0,启用,Negate 关闭。保存后再配置前哨。

三、本机 Proxy Outpost

3.1 云端对象

在“应用程序 → 前哨”创建 Proxy Outpost,名称 doratiger-debian-proxy,选择 code-server 应用。这里手工运行 Docker 容器,不需要让云端服务直接控制开发机 Docker。

保存后从部署说明取得该前哨的 Token。Token 只用于前哨连接身份中心,不是给浏览器使用的 API Key。

3.2 Docker Compose

在 Debian 宿主机准备目录,以下 /opt/authentik-outpost 是示例路径:

bash
1
2
3
sudo install -d -m 700 -o "$(id -u)" -g "$(id -g)" /opt/authentik-outpost /opt/authentik-outpost/secrets cd /opt/authentik-outpost umask 077

创建 compose.yaml:

yaml
1
2
3
4
5
6
7
services: proxy: image: ghcr.io/goauthentik/proxy:2026.8.5 restart: unless-stopped env_file: secrets/outpost.env ports: - "127.0.0.1:30092:9000"

创建 secrets/outpost.env,由管理员通过编辑器填写真实 Token,文件权限设为 600:

dotenv
1
2
3
AUTHENTIK_HOST=https://auth.example.com AUTHENTIK_INSECURE=false AUTHENTIK_TOKEN=REPLACE_WITH_OUTPOST_TOKEN
bash
1
2
3
4
sudo chmod 600 secrets/outpost.env sudo docker compose config --quiet sudo docker compose up -d sudo docker compose ps

使用 --quiet 验证 Compose,不把解析后的 Token 打印出来。前哨只监听宿主机回环;本机原生 Caddy 可以访问,局域网其他机器不能直接使用这个端口。

前哨需要出站访问云端 Authentik。若 Caddy 本身在另一个容器中,127.0.0.1 的含义不同,不能原样复制这份网络配置。

四、Caddy Forward Auth

4.1 站点配置

保留原站点的 TLS、DNS-01 和其他必要配置,将认证检查放在业务反代之前。下面是站点路由的最小示例;使用 DNS Challenge 的实例保留已有 tls 块,不用本示例覆盖证书配置:

caddyfile
1
2
3
4
5
6
7
8
9
10
11
12
code.example.com { route { reverse_proxy /outpost.goauthentik.io/* 127.0.0.1:30092 forward_auth 127.0.0.1:30092 { uri /outpost.goauthentik.io/auth/caddy copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email } reverse_proxy 127.0.0.1:30080 } }

route 保证这些指令按书写顺序执行。前哨路径先交给前哨,其余请求先认证,再到 code-server。Header 名称沿用官方大小写。Caddy 接入文档

原站点有 /proxy/*、扩展 WebView 或 PDF 预览专用路由时,把它们放在同一认证检查之后。本次保留了原路由,不为解决页面问题创建匿名绕过路径。

4.2 验证与重载

bash
1
2
3
sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile sudo systemctl reload caddy curl -I https://code.example.com/

未登录请求应进入认证跳转。再检查常用子路径,没有 Authentik 会话时不能直接打开编辑器或代理内容。

本次还验证了随请求伪造身份头不能绕过认证。Caddy 必须实际向前哨验证请求,不能只判断浏览器是否带有 X-Authentik-Username。

五、code-server 本地认证

5.1 配置切换

先确认前置认证生效,再修改 code-server 运行用户的 ~/.config/code-server/config.yaml。保留其他设置,只调整相关字段:

yaml
1
2
3
bind-addr: 127.0.0.1:30080 auth: none cert: false

auth: none 由外部认证保护这一前提决定。code-server 仍只能监听回环,不能在关闭密码后暴露 0.0.0.0。外部认证说明

重启实际管理该服务的 systemd 单元。先用 systemctl --user status 或系统级 systemctl status 确认服务归属,不同时启用两份实例。本文原实例由既有 systemd 服务恢复运行,没有新增第二套进程管理。

5.2 功能检查

用无痕窗口访问,完成 DoraTiger Auth 登录后应直接进入编辑器。本次已确认编辑器与终端可用。进一步检查打开项目、终端命令、扩展面板、WebSocket 和常用预览路径;登录页能打开不足以验证开发功能。

六、维护与回退

备份 Caddyfile、code-server 原配置和前哨部署文件。Token 文件保存在受限目录,不进入公开仓库。

撤除前置认证前,先把 code-server 恢复为密码认证并验证,再移除 Caddy 的认证路由。不能先去掉前哨检查、留下 auth: none 的编辑器入口。

增加组成员就相当于允许对方使用这个开发环境,不能把它当成只读网站访问权限。移出组后还要处理现有会话与终端,不能假设正在运行的命令会自动结束。

七、配置问题与解答

7.1 为什么单独运行本机前哨

Q:已有 NAS 前哨,是否必须复用?

不必须。本机前哨让 Caddy 通过回环完成认证检查,不需要额外开放 NAS 前哨端口。它仍连接同一个云端 IdP,登录身份和流程没有分裂成两套。

7.2 是否产生多个 code-server 用户

Q:不同 Authentik 用户能否得到各自的 home 目录?

此方案不会。Forward Auth 只控制入口,后端仍使用原系统用户。不要以为创建多个访问组成员就获得了操作系统隔离。

7.3 子路径是否可以跳过认证

Q:扩展预览失败,能否直接放行 /proxy/*?

不应把可访问本机服务的代理路径整体匿名开放。应检查 WebSocket、路径转发和 HTTPS 安全上下文,保持它与主编辑器同样经过认证。

参考

手机扫码阅读
本文作者: 有次元袋的 tiger
本文链接: https://www.superheaoz.top/2026/11/62511/
版权声明: 本站点所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 我的个人天地!