Tinyauth 实战解析：用最小的 OpenID Certified 认证服务器为你的应用加上登录保护-平芜编程栈

认证鉴权
后端
API网关

【免费下载链接】tinyauth

The tiniest OpenID Certified™ authorization and authentication server you have ever seen.

项目地址：https://gitcode.com/GitHub_Trending/ti/tinyauth

Tinyauth 是一个以“极小、极简”为核心理念的认证与授权服务器，既可作为接入 OAuth、LDAP 与访问控制（ACLs）的认证中间件挂在你的应用前面，也可作为独立的认证服务器运行，并原生支持 Traefik、Nginx、Caddy 等主流反向代理。阅读本文后，你将掌握 Tinyauth 的架构定位、基于 Docker Compose 与 Traefik 的快速接入方法、用户与 TOTP 双因素管理的完整 CLI 操作，以及从环境变量到 YAML 的全套配置体系与源码级实现细节。

Tinyauth 是什么

The tiniest OpenID Certified™ authorization and authentication server you have ever seen.

这是 Tinyauth 对自己的一句话定位——你见过的最小、最简单的授权与认证服务器。它由 Go 编写，前端为 React（Vite）单页应用，整个项目结构紧凑（入口位于 cmd/tinyauth、核心逻辑位于 internal），同时把数据库、OAuth、OIDC、LDAP、Tailscale、访问控制等能力都收敛在一个二进制中。

它的典型用法有两种：

作为认证中间件：通过反向代理（Traefik / Nginx / Caddy）的 forward-auth / auth_request 机制，把未登录请求重定向到 Tinyauth 的登录页，认证通过后再把用户信息以请求头形式回传给上游应用；
作为独立认证服务器：直接对外提供登录、OIDC 授权码流程等能力。

值得一提的是，项目 README 明确声明：截至 2026-06-25，Tinyauth v5.1.0 已通过OpenID Certified™ for Basic OP认证，即其作为 OpenID Provider 的基础实现通过了官方一致性测试套件，这在自托管类认证服务器中并不多见。

需要留意的是，README 同时给出两条重要提示：

Tinyauth 正处于活跃开发中，配置可能经常变化，升级前务必仔细阅读版本发布说明。

当前仓库分支是开发分支（main），如需最新稳定版，请参考官方文档或最新的稳定版 tag。

快速开始：Docker Compose + Traefik 一站式接入

官方推荐的入门路径是跟随官方文档的 Getting Started 指南，同时仓库根目录提供了可直接运行的 docker-compose.example.yml，它由 Traefik、Whoami 和 Tinyauth 三个服务组成，用于演示 Tinyauth 的完整能力。注意该文件位于开发分支，可能包含尚未发布的更新。

完整的示例配置如下：

services: traefik: image: traefik:v3.6 command: --api.insecure=true --providers.docker ports: - 80:80 volumes: - /var/run/docker.sock:/var/run/docker.sock whoami: image: traefik/whoami:latest labels: traefik.enable: true traefik.http.routers.whoami.rule: Host(`whoami.example.com`) traefik.http.routers.whoami.middlewares: tinyauth tinyauth: image: ghcr.io/tinyauthapp/tinyauth:v5 environment: - TINYAUTH_APPURL=https://tinyauth.example.com - TINYAUTH_AUTH_USERS=user:$$2a$$10$$UdLYoJ5lgPsC0RKqYH/jMua7zIn0g9kPqWmhYayJYLaZQ/FTmH2/u # user:password volumes: - ./data:/data labels: traefik.enable: true traefik.http.routers.tinyauth.rule: Host(`tinyauth.example.com`) traefik.http.middlewares.tinyauth.forwardauth.address: http://tinyauth:3000/api/auth/traefik

这段配置演示了三条核心信息：

Tinyauth 镜像：ghcr.io/tinyauthapp/tinyauth:v5，挂载./data:/data持久化数据。从 internal/model/config.go 的NewDefaultConfiguration可以看出，当检测到 Docker 运行时环境（RUNTIME_ENV=docker）时，数据库、资源与 OIDC 密钥路径会自动切换到/data下（/data/tinyauth.db、/data/resources、/data/oidc/key.pem、/data/oidc/key.pub）。
用户注入：TINYAUTH_AUTH_USERS接收username:bcrypt_hash格式的列表。注意示例中把$写成了$$——这是 Docker Compose 环境变量的转义写法，源码 cmd/tinyauth/create_user.go 中专门处理了这一点（见下文用户管理）。
Traefik forwardAuth 集成：traefik.http.middlewares.tinyauth.forwardauth.address指向http://tinyauth:3000/api/auth/traefik，Tinyauth 内部通过该端点完成认证校验；whoami路由挂上tinyauth中间件后即被登录保护。

在开发分支的 docker-compose.dev.yml 中还可以看到更完整的 Traefik 集成方式，其中包括forwardauth.authResponseHeaders: remote-user, remote-sub, remote-name, remote-email, remote-groups，即认证通过后 Traefik 会把用户信息以这些请求头透传给上游应用——这正是 Tinyauth 作为认证中间件向应用传递身份的机制。

如果你暂时不想部署，官方还提供了在线 Demo，默认用户名user、密码password，可以直接体验登录流程。

用户管理：从创建、校验到 TOTP 双因素

用户配置的底层格式为username:bcrypt_hash（可选追加:totp_secret组成三段式username:hash:totp）。为避免手写 bcrypt 哈希，Tinyauth 提供了完整的 CLI 子命令体系，全部挂在tinyauth主命令下（命令树定义见 cmd/tinyauth/tinyauth.go）。

创建用户

tinyauth user create --username <name> --password <password>

也可加--interactive进入交互式表单。源码 cmd/tinyauth/create_user.go 的实现要点：

用户名不能为空、不能包含:字符；
密码使用bcrypt.GenerateFromPassword（bcrypt.DefaultCost）哈希；
输出会同时给出三种配置形式，任选其一即可：
- 环境变量：TINYAUTH_AUTH_USERS=user:hash
- CLI 标志：--auth.users=user:hash
- YAML 配置：auth.users: [user:hash]
若使用--docker标志（或交互表单中选择 Docker 格式），输出会自动把$转义为$$，以便直接粘贴进 docker-compose 的 environment 中，避免被 Compose 变量插值破坏。

把生成的用户写回配置后重启 Tinyauth 即可生效。

校验用户

tinyauth user verify --user "user:hash" --username user --password password

user verify子命令（源码 cmd/tinyauth/verify_user.go）用于验证一个用户是否配置正确：它先用utils.ParseUser解析username:hash[:totp]三段式，再通过bcrypt.CompareHashAndPassword校验密码；如果用户带 TOTP secret，还会用totp.Validate校验一次性验证码。校验通过输出✓ User verified。该命令支持--interactive交互式输入，非常适合部署后快速自检。

为已有用户启用 TOTP 双因素

tinyauth totp generate --user "user:hash"

源码 cmd/tinyauth/generate_totp.go 会：

解析现有用户，若已绑定 TOTP secret 则拒绝重复生成；
调用totp.Generate（Issuer 为Tinyauth）生成新的 TOTP secret；
在终端直接打印二维码（基于qrterminal），可用 Google Authenticator、2fauth、Microsoft Authenticator 等扫码绑定；
输出最终三段式用户串username:hash:totp_secret，把它加回配置即可启用双因素登录。

同样的，若原用户哈希中含有$$（Docker 转义形式），生成时会自动重新转义，保证输出可直接用于 docker-compose。TOTP 校验失败会限制登录，与auth.loginMaxRetries配合可形成登录保护。

配置体系：环境变量、CLI 标志与 YAML 三通道合一

Tinyauth 的配置加载采用“多资源加载器”机制，在 cmd/tinyauth/tinyauth.go 中注册了三个加载器：

loaders := []cli.ResourceLoader{ &loaders.FileLoader{}, &loaders.FlagLoader{}, &loaders.EnvLoader{}, }

即YAML 配置文件、CLI 标志、环境变量三种方式均可配置同一套配置模型，环境变量命名规则为TINYAUTH_前缀 + 大写化的配置路径（如auth.users→TINYAUTH_AUTH_USERS）。全部配置项的完整定义与默认值位于 internal/model/config.go，核心模块如下：

配置模块	YAML 键	关键子项与默认值	说明
应用	`appUrl`	—	应用对外基础 URL
标签提供方	`labelProvider`	`auto`（自动探测 docker/kubernetes）	用于 ACL 的标签来源，可选`auto`、`docker`、`kubernetes`、`none`
数据库	`database`	`driver: sqlite`，`path: ./tinyauth.db`（Docker 下为`/data/tinyauth.db`）	驱动可选`sqlite`、`postgres`、`memory`；postgres 时`path`填连接 URL
服务器	`server`	`port: 3000`，`address: 0.0.0.0`，可选`socketPath`	监听端口、地址与 Unix socket
认证	`auth`	`users`、`subdomainsEnabled: true`、`sessionExpiry: 86400`（1 天）、`sessionMaxLifetime: 0`（禁用）、`loginTimeout: 300`（5 分钟）、`loginMaxRetries: 3`、`secureCookie`、`trustedProxies`、`ip.allow/block/bypass`	会话、登录限流、IP 白名单等核心安全参数；还支持`usersFile`与`userAttributes`（按用户定制 OIDC 属性，如 name、email、picture 等）
访问控制	`apps`	每个 app 含`config.domain`、`users.allow/block`、`oauth.whitelist/groups`、`ldap.groups`、`ip.allow/block/bypass`、`path.allow/block`（正则）、`response.headers`、`response.basicAuth`	按应用细粒度控制谁能访问、哪些路径放行、是否追加自定义响应头甚至叠加 Basic Auth
ACL 策略	`auth.acls`	`policy: allow`	`allow`（默认放行）或`deny`（默认拒绝）
OAuth	`oauth`	`whitelist`、`autoRedirect`、`providers`（含 clientId/clientSecret、scopes、redirectUrl、authUrl、tokenUrl、userinfoUrl、claims 映射等）	支持多 OAuth 提供商并可按域白名单；secret 可改由文件提供（`clientSecretFile`）
OIDC	`oidc`	`privateKeyPath`/`publicKeyPath`（默认`./tinyauth_oidc_key[.pub]`，Docker 下为`/data/oidc/key.pem`、`/data/oidc/key.pub`）、`clients`（含 clientId、clientSecret、trustedRedirectUris、name）	用于签发与验证 ID Token，支持多个 OIDC 客户端
LDAP	`ldap`	`address`、`bindDn`、`bindPassword[File]`、`baseDn`、`insecure: false`、`searchFilter: "(uid=%s)"`、`authCert/authKey`（mTLS）、`groupCacheTTL: 900`（15 分钟）	企业目录认证与组授权
日志	`log`	`level: info`、`json: false`、`streams.http/app/audit`	支持按 HTTP、应用、审计三类流分别开关与设置级别
UI	`ui`	`title: "Tinyauth"`、`forgotPasswordMessage`、`backgroundImage: "/background.webp"`、`warningsEnabled: true`	登录界面定制，背景图等资源来自 frontend/public
遥测	`analytics`	`enabled: true`	周期性收集版本信息
资源	`resources`	`enabled: true`，`path: ./resources`（Docker 下`/data/resources`）	资源服务器
Tailscale	`tailscale`	`enabled`、`apiToken[File]`、`tailnet`、`cacheDuration`（默认 5 分钟）	与 Tailscale 设备/用户体系集成
实验特性	`experimental`	`oauthBridgeEnabled`、`disableAuthModuleFallback`	实验性开关，启用时 CLI 会打印黄色警告

从源码结构看，config模型同时承载 YAML 序列化与配置描述（description 字段），官方还基于此生成了完整的配置文档与环境变量文档（生成器位于 gen/docs）。

一份真实的 YAML 配置示例

仓库 e2e 测试使用的 e2e/config.e2e.yaml 是一份非常典型的最小化配置，可作为参考：

appUrl: http://tinyauth.127.0.0.1.sslip.io log: level: debug auth: users: # user1:password,user2:password,user3:password:token - user1:$2a$10$h1laww4k5a4bJcG5KwE3nO45YKSC4mOKHxbcccgxr3Y7H9zHlQe8e - user2:$2a$10$h1laww4k5a4bJcG5KwE3nO45YKSC4mOKHxbcccgxr3Y7H9zHlQe8e - user3:$2a$10$h1laww4k5a4bJcG5KwE3nO45YKSC4mOKHxbcccgxr3Y7H9zHlQe8e:MVR4JQWNXYKNM6HHJEYEFP2O74QIIEJE # 关闭登录重试限制以便多 worker 并行测试 loginMaxRetries: 0 apps: whoami: config: domain: whoami.127.0.0.1.sslip.io path: allow: /foo users: allow: user1

注意user3的三段式格式（username:hash:totp）与apps.whoami的细粒度 ACL：domain指定受保护域名，path.allow: /foo表示该路径正则匹配时免认证，users.allow: user1表示仅允许指定用户访问。

认证能力与访问控制（ACLs）

Tinyauth 的认证后端是可插拔的，README 明确列出其支持范围：

本地用户 + TOTP：基于 bcrypt 密码哈希与 TOTP 双因素（见上文 CLI 管理）；
OAuth：支持多个提供商，配置集中在oauth.providers（对应 internal/service/oauth_service.go），并内置了常见提供商预设（internal/service/oauth_presets.go）与 claim 提取器（internal/service/oauth_extractors.go），可通过claims.username/email/name/groups将第三方用户映射成本地身份；
LDAP：企业目录认证与组授权（internal/service/ldap_service.go），支持搜索过滤器、mTLS 与组缓存；
OIDC：作为 OpenID Provider 对外签发 ID Token（internal/service/oidc_service.go），客户端凭据通过tinyauth oidc create生成；
Tailscale：与 Tailnet 设备/用户集成（internal/service/tailscale_service.go）。

在访问控制层面，除auth.acls.policy（allow/deny 默认策略）外，apps配置提供了按应用的完整控制面：用户黑白名单、OAuth 组、LDAP 组、IP 白名单/黑名单/旁路（bypass）、路径正则放行、自定义响应头，甚至可以为单个应用叠加一层 Basic Auth（response.basicAuth）。这些规则的解析与执行对应 internal/service/access_controls_service.go 与 internal/service/policy_engine.go，并配有完整的单元测试（internal/service/access_controls_rules_test.go、internal/service/policy_engine_test.go）。

创建 OIDC 客户端

tinyauth oidc create <client-name>

源码 cmd/tinyauth/create_oidc_client.go 规定客户端名称只能包含字母、数字与连字符，随后生成 UUID 形式的clientId与ta-前缀的随机clientSecret（61 位随机串），并一次性输出三种配置方式（环境变量TINYAUTH_OIDC_CLIENTS_<NAME>_CLIENTID/_CLIENTSECRET/_NAME、CLI 标志--oidc.clients.<name>.*、YAMLoidc.clients.<name>）。由于凭据无法重新生成，输出时必须妥善保存。

运维与调试命令

除了user、totp、oidc三个管理子命令外，Tinyauth 还提供三个常用的运维命令（源码均在 cmd/tinyauth）：

tinyauth healthcheck：对/api/healthz发起 GET 请求并校验 HTTP 200（源码 cmd/tinyauth/healthcheck.go）。默认读取TINYAUTH_SERVER_ADDRESS（默认127.0.0.1）与TINYAUTH_SERVER_PORT（默认3000）拼出地址，也支持直接传入 URL 作为参数，适合作为容器 HEALTHCHECK 指令；
tinyauth config：把当前生效配置（已合并文件、标志、环境变量）以 YAML 形式完整 dump 出来，用于排障核对（源码 cmd/tinyauth/config.go）；
tinyauth version：打印版本号、Commit Hash 与构建时间戳（源码 cmd/tinyauth/version.go），这些信息由构建期 ldflags 注入（见 Makefile 中的-X参数）。

开发与构建

Tinyauth 提供了完善的开发工作流，详见 CONTRIBUTING.md 与 Makefile：

make deps：安装依赖（前端pnpm ci+ Go modules）；
make webui：构建前端并拷贝产物到internal/assets（UI 源码位于 frontend，本地化资源在 frontend/src/lib/i18n/locales，支持数十种语言，并通过 Crowdin 协作翻译）；
make binary/binary-linux-amd64/binary-linux-arm64：构建单二进制，CGO_ENABLED=0静态编译；
make dev：基于 docker-compose.dev.yml 起全套开发环境（Traefik + whoami + 前端热更新 + 后端热重载，并挂载 Docker socket 以支持标签驱动的 ACL 与 forwardAuth 演示）；
make test/make vet/make test-race：测试、静态检查与竞态检测，控制器、服务层、工具层均有对应测试文件（如 internal/controller、internal/service）；
make docker/make docker-distroless：构建常规与 distroless 两种镜像（Dockerfile、Dockerfile.distroless）。

端到端测试则基于 Playwright 与 docker-compose 编排（e2e），覆盖认证流程与应用保护场景，可直接复现本文所述的真实部署形态。

许可与社区

Tinyauth 采用GNU Affero General Public License v3.0（详见 LICENSE）。该许可的要点包括：允许复制、分发与修改软件，但必须跟踪源文件的变更与日期；任何包含（经由编译器）AGPL 代码的修改或软件，都必须以 AGPL 形式随附构建与安装说明一并提供；如果你通过网络运行修改版，还必须向该服务的用户开放源代码。项目还提供 Discord 社区频道用于交流自托管与 Homelab 话题，并欢迎通过提交 issue 或新增功能参与贡献；如果你愿意，也可以在 Crowdin 上帮助把界面翻译成更多语言。

结语

从 README 的定位到源码的实现，Tinyauth 的核心价值在于把“认证中间件 + 独立认证服务器 + OpenID Provider”三种角色压缩进一个极小的二进制：配置上统一了环境变量、CLI 与 YAML 三通道，管理上提供了从用户创建、双因素绑定到 OIDC 客户端生成的完整命令行工具，代理集成上对 Traefik forwardAuth 提供了开箱即用的支持。由于项目仍处于活跃开发期、配置项可能随版本调整，生产使用前请务必核对你所选用版本的发布说明，并以官方文档与当前稳定版为准。