authentik 开源身份认证与 LiteLLM 集成：把 OAuth 回调与 Base URL 改到 TaoToken 的配置清单

1. 自建 AI 网关为什么总在登录回调上翻车如果你正在用 LiteLLM 搭一个团队内部的大模型统一入口大概率会遇到这样一个尴尬场面模型调用本身跑得挺顺但一旦把 authentik 这种开源身份认证平台接进来做 SSO登录跳转就开始出问题。点「使用 authentik 登录」之后浏览器要么停在 authentik 的授权页不动要么回调到 LiteLLM 时报redirect_uri mismatch再或者登录成功了但 LiteLLM 拿不到用户角色所有人都是普通用户管理后台进不去。这类问题的根源通常不在 authentik也不在 LiteLLM 本身而在于三处配置没有对齐OAuth 回调地址、LiteLLM 对外暴露的 Base URL、以及 authentik Provider 里签发的 Client ID / Secret 与 LiteLLM 侧填写的值是否一致。任何一处差一个字符整个链路就断。这篇内容面向的是自建 AI 网关的开发者场景很具体你已经有一套 authentik假设域名为authentik.company也部署了 LiteLLM假设域名为litellm.company现在要把两者接起来并且把 LiteLLM 的上游模型调用指向 TaoToken 的 API 端点。我会给出可复制的 authentik Provider/Application 配置、LiteLLM 的config.yaml片段以及用curl验证登录跳转和模型调用的具体命令。整套流程走完你应该能得到一个「用 authentik 登录 LiteLLM登录后能正常调用模型」的闭环。需要先明确一个概念LiteLLM 在这里扮演的是 AI 网关角色它对外提供兼容 OpenAI 的/v1/chat/completions接口对内可以路由到不同厂商的模型。而 authentik 负责的是「谁可以进这个网关」。两者通过 OAuth2/OIDC 协议对接LiteLLM 作为 OIDC 的 Clientauthentik 作为 Provider。理解这个角色分工后面配置时就不会把字段填错位置。2. TaoToken 作为 LiteLLM 上游的前置准备在讲 authentik 集成之前得先把 LiteLLM 的上游模型来源确定下来。LiteLLM 本身不生产模型它需要配置至少一个上游 provider。这里我们用 TaoToken 的 API 端点作为上游原因是它提供兼容 OpenAI 的接口LiteLLM 可以直接用openai/前缀来路由配置成本低。你需要先拿到一个 API Key。登录 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content进入控制台后创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时建议给 Key 起一个能识别用途的名字比如litellm-gateway方便后续在 LiteLLM 的日志里定位调用来源。拿到 Key 之后先别急着写进 LiteLLM 配置。我建议先用curl单独验证一下这个 Key 能不能正常调用模型把「上游是否通」和「网关配置是否正确」这两个问题分开排查。验证命令如下curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回里有choices字段和正常的content说明上游通了。如果返回 401检查 Key 是否复制完整、有没有多余空格如果返回模型不存在换一个模型 ID 再试。这一步过了再往下做 authentik 集成出问题时就能快速定位是网关层还是认证层。TaoToken 的 API 基础地址是https://taotoken.net/api注意这个地址不带任何查询参数LiteLLM 配置里填的就是它。模型 ID 的完整列表可以在模型对话页查看https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 选一个你确定可用的模型 ID 写进配置。3. authentik Provider 与 LiteLLM config.yaml 可复制配置这一节是核心给出两份可直接复制的配置authentik 侧的 Provider/Application 设置以及 LiteLLM 侧的config.yaml。3.1 authentik 侧创建 OAuth2/OIDC Provider以管理员登录 authentik 管理界面导航到「应用程序 应用程序」点击「使用提供程序创建」。填写时注意以下字段应用名称填LiteLLMSlug 会自动带出litellm这个 Slug 后面会出现在授权端点的 URL 里。提供者类型选OAuth2/OpenID Connect。在 Provider 配置里最关键的是重定向 URI。填http://litellm.company/sso/callback如果你用的是 HTTPS就换成https://litellm.company/sso/callback。这个地址必须和 LiteLLM 实际暴露的回调路径完全一致包括协议、域名、端口、路径一个字符都不能差。签名密钥选任意一个可用的加密保持禁用。保存后记下三个值Client ID、Client Secret、Slug。这三个值会填到 LiteLLM 的配置里。3.2 LiteLLM 侧config.yaml 片段LiteLLM 的 SSO 配置写在config.yaml的general_settings和litellm_settings里。下面是一份可复制的片段把占位符替换成你的实际值model_list: - model_name: gpt-4o-mini litellm_params: model: openai/gpt-4o-mini api_base: https://taotoken.net/api api_key: os.environ/TAOTOKEN_API_KEY general_settings: master_key: os.environ/LITELLM_MASTER_KEY database_url: os.environ/DATABASE_URL litellm_settings: drop_params: true # OIDC / SSO 配置 sso: enabled: true provider: generic client_id: 你的Client ID client_secret: 你的Client Secret authorization_endpoint: https://authentik.company/application/o/authorize/ token_endpoint: https://authentik.company/application/o/token/ userinfo_endpoint: https://authentik.company/application/o/userinfo/ redirect_uri: http://litellm.company/sso/callback scope: openid profile email litellm_role proxy_admin_email: adminlitellm.ai proxy_base_url: http://litellm.company几个容易填错的点authorization_endpoint末尾的斜杠要保留authentik 的端点对斜杠敏感scope里加上litellm_role这样 authentik 返回的 token 里会带角色声明LiteLLM 才能识别管理员proxy_base_url填 LiteLLM 对外的地址不要填localhost否则回调会失败。环境变量在启动 LiteLLM 前设置export TAOTOKEN_API_KEYsk-你的Key export LITELLM_MASTER_KEYsk-你的master-key export DATABASE_URLpostgresql://user:passlocalhost:5432/litellm启动命令litellm --config /path/to/config.yaml --port 40003.3 authentik 侧的角色声明映射为了让litellm_role这个 scope 真正返回角色需要在 authentik 里给 Provider 加一个 Scope Mapping。导航到「自定义 属性映射」创建一个新的 Scope Mapping名称填litellm_roleScope 名称填litellm_role表达式写return { litellm_role: proxy_admin if request.user.is_superuser else internal_user }然后在 Provider 的「高级协议设置」里把这个 Scope Mapping 加到选中的 Scopes 里。这样登录后LiteLLM 就能根据litellm_role判断用户是管理员还是普通用户。4. 用 curl 验证登录跳转与模型调用配置写完后不要直接开浏览器点登录先用curl验证两个关键环节授权跳转是否正常、模型调用是否通。4.1 验证授权跳转用curl请求 LiteLLM 的 SSO 登录入口看它是否正确重定向到 authentikcurl -I http://litellm.company/sso/key/generate如果配置正确你会看到302状态码Location头指向https://authentik.company/application/o/authorize/?client_id...redirect_uri...scope...。如果看到404说明 LiteLLM 的 SSO 路由没启用检查sso.enabled是否为true如果Location里的redirect_uri和你配置的不一致说明redirect_uri字段写错了。4.2 验证模型调用用 master key 直接调用 LiteLLM 的模型接口确认上游路由通curl -X POST http://litellm.company/v1/chat/completions \ -H Authorization: Bearer sk-你的master-key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: hello}], max_tokens: 20 }返回里有choices就说明 LiteLLM 到 TaoToken 的链路是通的。如果返回401检查 master key 是否和环境变量一致如果返回model not found检查model_name和请求里的model是否匹配。4.3 验证完整 SSO 流程浏览器打开http://litellm.company点击「使用 authentik 登录」应该跳转到 authentik 登录页。登录后回调回 LiteLLM如果一切正常你会进入 LiteLLM 的管理界面。此时在 LiteLLM 的日志里应该能看到用户信息和角色。如果回调时报invalid_client检查 Client ID 和 Secret 是否和 authentik 里的一致如果报redirect_uri mismatch回到 3.1 节核对重定向 URI。5. 集成过程中最常见的四类报错排查这一节把实际踩过的坑列出来对照报错信息定位。报错一401 Unauthorized出现在模型调用而非登录环节。这种通常是 TaoToken 的 API Key 没生效。检查config.yaml里api_key是否写成了os.environ/TAOTOKEN_API_KEY以及启动 LiteLLM 的 shell 里是否真的export了这个变量。可以用echo $TAOTOKEN_API_KEY确认。另外注意 Key 不要带引号写进环境变量否则会把引号当成 Key 的一部分。报错二local proxy failed或回调地址无法访问。这个报错说明 LiteLLM 的proxy_base_url填的是localhost或内网地址而 authentik 从浏览器侧发起回调时访问不到。把proxy_base_url改成浏览器能访问的域名比如http://litellm.company。如果 LiteLLM 跑在容器里确认端口映射正确。报错三reading choices相关错误返回体里没有choices字段。这通常是上游返回了非预期格式或者模型 ID 写错。先用第 2 节的curl直接打 TaoToken 的 API确认模型 ID 可用。如果直连正常但经过 LiteLLM 报错检查model字段是否写了openai/前缀LiteLLM 需要这个前缀来识别 provider 类型。报错四OAuth 回调后报invalid_client或OAuth相关错误。检查 authentik Provider 里的 Client ID / Secret 和 LiteLLMconfig.yaml里的client_id/client_secret是否完全一致。注意 Secret 只在创建时显示一次如果丢了就重新生成一个。另外确认 authentik 的 Provider 没有启用加密LiteLLM 的 generic provider 默认不处理加密的 token。如果用的是 Claude Code 这类工具接入配置三件套是 Base URL、Key、Model IDBase URL 填https://taotoken.net/apiKey 填你的 TaoToken API KeyModel ID 填你在模型对话页选定的模型。这三者缺一不可且 Model ID 要和 LiteLLM 里model_name对应。6. 把认证和调用拆开验证是自建网关最省时间的做法整套配置走下来最耗时间的往往不是写配置而是出问题时不知道是哪一层断了。我的做法是始终把「认证层」和「调用层」分开验证先用curl直连 TaoToken 确认上游通再用 master key 打 LiteLLM 确认网关路由通最后才走 SSO 登录流程。这样任何一步报错都能立刻缩小范围。如果你后续要长期跑这套网关建议把 LiteLLM 的配置纳入版本管理config.yaml里的敏感值全部走环境变量。authentik 侧的 Provider 配置可以导出成蓝图Blueprint文件方便迁移和重建。模型调用方面TaoToken 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例需要扩展客户端时可以直接参考。Coding Plan 适合需要长期编码和 Agent 场景的团队地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 模型对话页在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。把这几处配置对齐之后authentik 负责「谁能进」LiteLLM 负责「请求怎么路由」TaoToken 负责「模型从哪来」三层各司其职排查起来就不会互相甩锅。