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

认证鉴权后端API网关【免费下载链接】tinyauthThe 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 编写前端为 ReactVite单页应用整个项目结构紧凑入口位于 cmd/tinyauth、核心逻辑位于 internal同时把数据库、OAuth、OIDC、LDAP、Tailscale、访问控制等能力都收敛在一个二进制中。它的典型用法有两种作为认证中间件通过反向代理Traefik / Nginx / Caddy的 forward-auth / auth_request 机制把未登录请求重定向到 Tinyauth 的登录页认证通过后再把用户信息以请求头形式回传给上游应用作为独立认证服务器直接对外提供登录、OIDC 授权码流程等能力。值得一提的是项目 README 明确声明截至 2026-06-25Tinyauth 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.insecuretrue --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_APPURLhttps://tinyauth.example.com - TINYAUTH_AUTH_USERSuser:$$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_ENVdocker时数据库、资源与 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/traefikTinyauth 内部通过该端点完成认证校验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.GenerateFromPasswordbcrypt.DefaultCost哈希输出会同时给出三种配置形式任选其一即可环境变量TINYAUTH_AUTH_USERSuser:hashCLI 标志--auth.usersuser:hashYAML 配置auth.users: [user:hash]若使用--docker标志或交互表单中选择 Docker 格式输出会自动把$转义为$$以便直接粘贴进 docker-compose 的 environment 中避免被 Compose 变量插值破坏。把生成的用户写回配置后重启 Tinyauth 即可生效。校验用户tinyauth user verify --user user:hash --username user --password passworduser 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.GenerateIssuer 为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标签提供方labelProviderauto自动探测 docker/kubernetes用于 ACL 的标签来源可选auto、docker、kubernetes、none数据库databasedriver: sqlitepath: ./tinyauth.dbDocker 下为/data/tinyauth.db驱动可选sqlite、postgres、memorypostgres 时path填连接 URL服务器serverport: 3000address: 0.0.0.0可选socketPath监听端口、地址与 Unix socket认证authusers、subdomainsEnabled: true、sessionExpiry: 864001 天、sessionMaxLifetime: 0禁用、loginTimeout: 3005 分钟、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 AuthACL 策略auth.aclspolicy: allowallow默认放行或deny默认拒绝OAuthoauthwhitelist、autoRedirect、providers含 clientId/clientSecret、scopes、redirectUrl、authUrl、tokenUrl、userinfoUrl、claims 映射等支持多 OAuth 提供商并可按域白名单secret 可改由文件提供clientSecretFileOIDCoidcprivateKeyPath/publicKeyPath默认./tinyauth_oidc_key[.pub]Docker 下为/data/oidc/key.pem、/data/oidc/key.pub、clients含 clientId、clientSecret、trustedRedirectUris、name用于签发与验证 ID Token支持多个 OIDC 客户端LDAPldapaddress、bindDn、bindPassword[File]、baseDn、insecure: false、searchFilter: (uid%s)、authCert/authKeymTLS、groupCacheTTL: 90015 分钟企业目录认证与组授权日志loglevel: info、json: false、streams.http/app/audit支持按 HTTP、应用、审计三类流分别开关与设置级别UIuititle: Tinyauth、forgotPasswordMessage、backgroundImage: /background.webp、warningsEnabled: true登录界面定制背景图等资源来自 frontend/public遥测analyticsenabled: true周期性收集版本信息资源resourcesenabled: truepath: ./resourcesDocker 下/data/resources资源服务器Tailscaletailscaleenabled、apiToken[File]、tailnet、cacheDuration默认 5 分钟与 Tailscale 设备/用户体系集成实验特性experimentaloauthBridgeEnabled、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的细粒度 ACLdomain指定受保护域名path.allow: /foo表示该路径正则匹配时免认证users.allow: user1表示仅允许指定用户访问。认证能力与访问控制ACLsTinyauth 的认证后端是可插拔的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 Tokeninternal/service/oidc_service.go客户端凭据通过tinyauth oidc create生成Tailscale与 Tailnet 设备/用户集成internal/service/tailscale_service.go。在访问控制层面除auth.acls.policyallow/deny 默认策略外apps配置提供了按应用的完整控制面用户黑白名单、OAuth 组、LDAP 组、IP 白名单/黑名单/旁路bypass、路径正则放行、自定义响应头甚至可以为单个应用叠加一层 Basic Authresponse.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-前缀的随机clientSecret61 位随机串并一次性输出三种配置方式环境变量TINYAUTH_OIDC_CLIENTS_NAME_CLIENTID/_CLIENTSECRET/_NAME、CLI 标志--oidc.clients.name.*、YAMLoidc.clients.name。由于凭据无法重新生成输出时必须妥善保存。运维与调试命令除了user、totp、oidc三个管理子命令外Tinyauth 还提供三个常用的运维命令源码均在 cmd/tinyauthtinyauth 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.gotinyauth version打印版本号、Commit Hash 与构建时间戳源码 cmd/tinyauth/version.go这些信息由构建期 ldflags 注入见 Makefile 中的-X参数。开发与构建Tinyauth 提供了完善的开发工作流详见 CONTRIBUTING.md 与 Makefilemake deps安装依赖前端pnpm ci Go modulesmake webui构建前端并拷贝产物到internal/assetsUI 源码位于 frontend本地化资源在 frontend/src/lib/i18n/locales支持数十种语言并通过 Crowdin 协作翻译make binary/binary-linux-amd64/binary-linux-arm64构建单二进制CGO_ENABLED0静态编译make dev基于 docker-compose.dev.yml 起全套开发环境Traefik whoami 前端热更新 后端热重载并挂载 Docker socket 以支持标签驱动的 ACL 与 forwardAuth 演示make test/make vet/make test-race测试、静态检查与竞态检测控制器、服务层、工具层均有对应测试文件如 internal/controller、internal/servicemake 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 提供了开箱即用的支持。由于项目仍处于活跃开发期、配置项可能随版本调整生产使用前请务必核对你所选用版本的发布说明并以官方文档与当前稳定版为准。赞分享认证鉴权后端API网关【免费下载链接】tinyauthThe tiniest OpenID Certified™ authorization and authentication server you have ever seen.项目地址https://gitcode.com/GitHub_Trending/ti/tinyauth点击查看免费下载相关推荐tinyauth为Docker应用添加简易登录认证tinyauth为Docker应用添加简易登录认证 项目介绍 在当今的互联网时代应用的安全性至关重要。tinyauth 是一款简洁的认证中间件旨在为所有基认证鉴权后端API网关Qwopus3.5-27B-v3推理效率优化BF16精度下如何平衡性能与显存占用Qwopus3.5 27B v3推理效率优化BF16精度下如何平衡性能与显存占用 Qwopus3.5 27B v3是基于Qwen3.5 27B开发的推理增强型Traefik Hub LDAP 认证中间件使用外部 LDAP 服务器保护你的应用Traefik Hub LDAP 认证中间件使用外部 LDAP 服务器保护你的应用 导读 本文讲解 Traefik Hub API Gateway 提供的 L后端API网关负载均衡微服务网络云原生上一篇ESPnet音频特征可视化波形图、频谱图与梅尔图下一篇SwiftGen Xcode集成终极指南构建阶段自动化与增量生成优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考