1. 项目概述最近在折腾企业内部AI应用的安全接入发现很多团队在部署像LiteLLM这样的AI网关时身份认证这块是个头疼事。要么就是简单粗暴地用API Key管理起来一团乱麻要么就是自己从头写一套用户体系费时费力还容易出安全漏洞。我这边正好在深度使用authentik这个开源的身份平台就琢磨着能不能把它俩给打通了。authentik负责统一的人员认证和权限管理LiteLLM则专注做好大模型的路由和调用各司其职岂不美哉折腾了几天总算把集成流程跑通了整个过程比预想的要顺畅不少。这篇文章我就来详细拆解一下如何将LiteLLM无缝集成到authentik中实现一个既安全又便于管理的企业级AI服务入口。无论你是运维工程师、DevOps还是负责AI应用落地的开发者这套方案都能帮你省去大量重复造轮子的时间。简单来说这个集成的核心价值在于用一个统一的账号体系安全、可控地接入企业内部所有需要调用大模型的应用。员工不再需要记住一堆不同服务的密码或API Key管理员也能在一个界面里清晰地看到谁在什么时候、用什么权限访问了哪些AI模型。这对于满足企业安全审计、合规要求以及精细化成本控制来说是至关重要的一步。2. 集成方案的整体设计与核心思路在开始动手配置之前我们得先搞清楚这两个组件各自扮演什么角色以及它们之间是如何“对话”的。这决定了我们配置的每一步背后的逻辑而不仅仅是照搬步骤。2.1 组件角色定位与协议选择Authentik在这里它扮演的是身份提供商Identity Provider, IdP的角色。它的核心工作是“认人”。当用户试图访问LiteLLM时authentik会拦截这个请求要求用户登录。用户成功登录后authentik会生成一个包含用户身份信息比如用户名、邮箱、所属组的安全令牌通常是JWT格式然后把这个令牌交给LiteLLM。LiteLLM在这里它扮演的是服务提供商Service Provider, SP或依赖方Relying Party, RP的角色。它的核心工作是“信人”和“办事”。它收到来自authentik的令牌后会验证这个令牌的真实性比如签名是否正确、是否过期然后解析出里面的用户信息。根据这些信息LiteLLM可以决定是否允许该用户访问以及这个用户能调用哪些模型、有什么样的速率限制等。通信协议为了让IdP和SP能安全、标准地交换用户信息我们采用OAuth 2.0 / OpenID Connect (OIDC)协议。这是目前业界最主流的单点登录SSO标准协议。简单理解OAuth 2.0解决了授权允许某个应用访问你的资源的问题而OIDC在OAuth 2.0之上增加了一层身份认证明确告诉你“你是谁”的标准。我们这次集成主要利用OIDC的能力。2.2 核心交互流程拆解整个单点登录的流程可以类比成一次特殊的“访客入园”发起访问用户打开浏览器输入LiteLLM的地址比如http://litellm.internal.company.com。重定向至认证中心LiteLLMSP发现用户没有登录凭证于是立即将用户的浏览器重定向到authentikIdP的登录页面并附上自己的“名片”Client ID和想访问的“区域”Scope如openid, profile, email。用户认证用户在authentik的页面上输入用户名和密码或其他已配置的认证方式如LDAP、Social Login等进行登录。征询用户同意authentik会向用户展示“LiteLLM应用请求访问你的基本信息如用户名、邮箱你同意吗”用户点击同意。颁发通行证authentik验证通过后生成一个授权码Authorization Code通过浏览器重定向回LiteLLM事先登记好的一个“回调地址”Callback URL。兑换身份令牌LiteLLM的后台服务拿到这个授权码后不会直接使用它。它会带着这个授权码、自己的“名片”Client ID和“密码”Client Secret再次秘密地访问authentik的另一个特定接口Token Endpoint用授权码兑换一个真正的、包含用户信息的ID TokenJWT格式和一个访问令牌Access Token。验证并创建本地会话LiteLLM验证ID Token的签名确保是authentik颁发的、有效期等信息。验证通过后它从Token里解析出用户的身份信息如preferred_username,email,groups等并在LiteLLM内部为该用户创建一个登录会话Session。访问成功用户的浏览器被重定向回LiteLLM的主界面此时他已经处于登录状态可以开始使用AI服务了。这个流程的关键在于用户的密码始终只存在于authentik和用户之间LiteLLM从未接触过用户密码大大提升了安全性。同时用户只需要在authentik登录一次就可以访问所有接入了authentik的应用实现了单点登录。2.3 前置准备与环境假设为了后续说明清晰我们需要先定义几个占位符请你在实际操作中替换成自己的真实环境authentik.company: 这是你部署的authentik服务的完整域名FQDN。例如auth.your-company.com或192.168.1.100:9000如果直接用IP和端口访问。litellm.company: 这是你部署的LiteLLM服务的完整域名FQDN。例如ai-gateway.your-company.com或192.168.1.101:4000。注意在生产环境中强烈建议使用正式的域名和HTTPS。自签名证书或内部CA签发的证书需要在LiteLLM和用户浏览器中被信任否则会导致SSL错误集成失败。如果是在内网测试可以暂时使用HTTP但务必知晓其安全风险。此外你需要确保你已经拥有一个正常运行的authentik实例并且拥有管理员权限。你已经部署了LiteLLM并且其Web UI可以正常访问。网络互通运行LiteLLM的服务器能够访问到authentik的服务端点/application/o/authorize/,/application/o/token/等。3. Authentik端详细配置步骤现在我们进入实操环节。首先在身份提供商authentik这边进行配置为LiteLLM这个“新应用”颁发“接入许可”。3.1 创建OAuth2/OIDC提供者登录到authentik的管理员界面。导航至提供者在左侧导航栏找到“身份提供”下的“提供者”点击进入。然后点击右上角的“创建”按钮。选择提供者类型在创建页面我们需要为这个提供者起个名字例如LiteLLM OIDC Provider。在“类型”下拉框中选择“OAuth2/OpenID Connect”。这个选择至关重要它决定了authentik将以OIDC协议与LiteLLM通信。配置认证流程在“认证流程”字段你需要选择一个流程。通常我们可以使用authentik自带的默认流程“default-authentication-flow”。这个流程定义了用户登录时的界面和步骤如输入用户名密码、可能的多因素认证等。如果你有自定义的复杂登录流程比如结合了LDAP、短信验证码可以在这里选择你创建好的流程。配置关键参数这是核心部分需要仔细填写。客户端类型选择“机密”。这意味着LiteLLM客户端会持有一个密码Client Secret来向authentik证明自己安全性更高。与之相对的是“公开”类型适用于无法安全保存密码的场景如手机App、单页应用但我们的LiteLLM服务端部署可以安全保存密码所以选“机密”。重定向 URI这是整个配置中最容易出错的地方之一。你必须准确填写LiteLLM用于接收认证回调的地址。格式通常为http(s)://litellm.company/sso/callback。例如https://ai-gateway.internal.com/sso/callback。这里有几个关键点协议必须与LiteLLM实际访问的协议一致HTTP或HTTPS。主机名和端口必须与LiteLLM服务访问地址完全一致。路径/sso/callback是LiteLLM默认的OIDC回调端点。请务必查阅你的LiteLLM文档确认不同版本或部署方式可能有差异。严格匹配authentik会进行严格比对多一个斜杠或少一个端口号都会导致认证失败。建议先填写一个如果失败再结合LiteLLM的日志和authentik的错误提示进行排查。签署密钥与算法在“签署密钥”处选择一个已有的密钥对如authentik Self-signed Certificate。这个密钥用于对颁发的JWT ID Token进行签名LiteLLM会用对应的公钥来验证Token的真实性。“算法”保持默认的RS256非对称加密即可这是最安全通用的选择。高级设置重要启用加密务必保持禁用不勾选。除非你非常清楚JWT加密JWE的配置并且LiteLLM也支持解密否则开启加密会导致LiteLLM无法解析Token内容集成失败。作用域这里定义了LiteLLM可以请求获取用户的哪些信息。默认的openid是必须的。建议至少加上profile获取用户名等基本信息和email获取邮箱。你还可以根据LiteLLM的需要添加自定义作用域比如后面会用到的litellm_role。属性映射这是将authentik中的用户属性如用户名、邮箱、所属组映射到JWT Token声明Claims中的关键步骤。我们稍后在创建应用后一起配置会更方便。保存提供者检查所有配置无误后点击“提交”按钮。创建成功后系统会生成两个关键信息“客户端ID”和“客户端密钥”。请立即妥善保存这两个值最好复制到本地文本编辑器或密码管理器中因为在LiteLLM配置时需要用到。客户端密钥只显示一次忘记后只能重新生成。3.2 创建对应的应用程序提供者定义了“如何认证”应用程序则定义了“谁可以访问这个应用”以及“应用本身的信息”。导航至应用程序在左侧导航栏找到“应用”下的“应用程序”点击进入。然后点击“使用提供者创建”按钮。这个按钮可以一次性创建应用并关联提供者比较方便。配置应用基本信息名称填写一个易于识别的名称如LiteLLM AI Gateway。这个名称会显示在用户的“我的应用”门户中。Slug系统会根据名称自动生成一个URL友好的标识符如litellm-ai-gateway可以手动修改。它在一些内部URL中会用到保持默认即可。提供者在下拉框中选择我们上一步刚刚创建的LiteLLM OIDC Provider。策略引擎模式选择“任何”表示只要满足任意一条关联的访问策略用户即可访问。选择“全部”则表示必须满足所有关联策略。初期为了测试可以先选择“任何”并暂时不绑定任何策略这样所有能登录authentik的用户都能访问LiteLLM。生产环境中务必根据实际情况配置严格的策略。配置UI设置可选但推荐你可以上传一个图标并填写应用描述这样在用户门户中看起来更美观专业。配置属性映射这是将用户信息传递给LiteLLM的核心。在创建应用的页面或编辑已创建应用的页面找到“属性映射”部分点击“创建”。名称例如LiteLLM User Claims。表达式这里使用authentik的模板语言。我们需要映射几个关键信息到JWT的声明里。假设我们想把用户的邮箱作为JWT中的email声明把用户名作为preferred_username可以这样写这是一个示例你可以根据需要调整# 映射邮箱 return { email: user.email, preferred_username: user.username, # 映射用户所在的组名列表这对LiteLLM做权限控制非常有用 groups: [group.name for group in ak_user_groups], # 可以添加自定义声明例如一个角色字段 litellm_role: ai_user if user.is_superuser else ai_guest }SAML/其他名称保持默认或留空因为我们用的是OIDC。OIDC 声明这里必须填写。它告诉authentik上面表达式返回的字典中的哪些键应该被放到ID Token里。填写你希望在Token中出现的声明名用空格分隔。例如email preferred_username groups litellm_role。保存应用程序点击提交完成应用的创建。3.3 配置访问策略生产环境必备为了让集成真正可用我们必须配置谁可以访问这个LiteLLM应用。authentik强大的策略引擎可以让你实现非常精细的控制。创建策略在“策略/权限”-“策略”中可以创建各种类型的策略。例如表达式策略通过编写返回True或False的表达式来控制。例如只允许邮箱以ai-team.com结尾的用户访问return user.email.endswith(ai-team.com)。组策略只允许属于特定组的用户访问。例如创建一个“AI平台用户”组将相关用户加入该组然后创建策略绑定这个组。绑定策略到应用在刚刚创建的LiteLLM应用程序的编辑页面找到“策略绑定”选项卡。点击“创建”选择你创建好的策略并设置一个合适的名称和顺序。策略会按照顺序执行。测试策略你可以用一个不符合策略条件的测试账号尝试访问LiteLLM应该会被authentik拒绝并看到“拒绝访问”之类的提示。至此authentik端的配置就全部完成了。我们已经创建了一个OIDC提供者、一个应用程序并定义了如何将用户信息传递给LiteLLM以及谁可以访问。接下来我们去LiteLLM那边进行配置。4. LiteLLM端详细配置与验证LiteLLM的配置主要集中在它的配置文件或环境变量中。我们需要告诉LiteLLM“当有用户需要登录时请去找authentikIdP这是它的地址和你的凭证。”4.1 定位与理解LiteLLM配置LiteLLM的配置方式取决于你的部署方式Docker部署通常通过环境变量或挂载的config.yaml文件配置。源码/Pip安装通过环境变量或启动命令参数配置。LiteLLM Proxy我们主要针对其Proxy的Web UI的SSO功能进行配置。关键的配置项都围绕OIDC展开。你需要准备以下从authentik获取的信息GENERIC_CLIENT_ID: 即authentik中创建的OIDC提供者的“客户端ID”。GENERIC_CLIENT_SECRET: 对应的“客户端密钥”。GENERIC_AUTHORIZATION_ENDPOINT: authentik的授权端点格式为https://authentik.company/application/o/authorize/。GENERIC_TOKEN_ENDPOINT: authentik的令牌端点格式为https://authentik.company/application/o/token/。GENERIC_USERINFO_ENDPOINT: authentik的用户信息端点格式为https://authentik.company/application/o/userinfo/。LiteLLM可能会用这个端点来获取更详细的用户信息。PROXY_ADMIN_EMAIL: 指定一个管理员邮箱用于接收系统通知可选但建议设置。PROXY_BASE_URL: LiteLLM Proxy服务对外的基础URL格式为http(s)://litellm.company。这个必须与authentik中配置的重定向URI的域名部分完全一致。GROUP_CLAIM: 这个参数告诉LiteLLM在JWT Token的哪个声明Claim里可以找到用户的组信息。根据我们在authentik属性映射中设置的groups声明这里应该填写groups。如果你映射的声明名是ak_groups这里就填ak_groups。4.2 具体配置方法示例方法一通过环境变量配置推荐用于Docker/K8s如果你使用Docker运行LiteLLM Proxy可以在docker run命令或docker-compose.yml中设置环境变量# docker-compose.yml 示例片段 version: 3.8 services: litellm-proxy: image: ghcr.io/berriai/litellm:main-latest container_name: litellm-proxy ports: - 4000:4000 environment: - GENERIC_CLIENT_IDyour_client_id_from_authentik - GENERIC_CLIENT_SECRETyour_client_secret_from_authentik - GENERIC_AUTHORIZATION_ENDPOINThttps://auth.your-company.com/application/o/authorize/ - GENERIC_TOKEN_ENDPOINThttps://auth.your-company.com/application/o/token/ - GENERIC_USERINFO_ENDPOINThttps://auth.your-company.com/application/o/userinfo/ - PROXY_ADMIN_EMAILadminyour-company.com - PROXY_BASE_URLhttps://ai-gateway.your-company.com - GROUP_CLAIMgroups # 其他LiteLLM配置如模型列表、密钥等 - LITELLM_MODEL_LIST[...] command: --port 4000 --config /path/to/config.yaml方法二通过config.yaml配置文件你也可以在LiteLLM的配置文件中指定这些参数。配置文件的结构可能因版本而异但OIDC配置通常在一个独立的SSO部分。# config.yaml 示例片段 model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo api_key: ${OPENAI_API_KEY} litellm_settings: drop_params: true general_settings: admin_email: adminyour-company.com proxy_base_url: https://ai-gateway.your-company.com sso_settings: enabled: true provider: generic generic_client_id: your_client_id_from_authentik generic_client_secret: your_client_secret_from_authentik generic_authorization_endpoint: https://auth.your-company.com/application/o/authorize/ generic_token_endpoint: https://auth.your-company.com/application/o/token/ generic_userinfo_endpoint: https://auth.your-company.com/application/o/userinfo/ group_claim: groups实操心得我个人更倾向于使用环境变量来管理敏感信息如CLIENT_SECRET和可能因环境而变的配置如各个Endpoint的URL。这样可以将配置与代码/镜像分离更符合十二要素应用原则也便于在CI/CD流水线或K8s中管理。配置文件则用来存放相对固定的模型定义等设置。4.3 启动服务与验证配置配置完成后重启LiteLLM Proxy服务以使配置生效。访问LiteLLM UI打开浏览器访问你的LiteLLM地址如https://ai-gateway.your-company.com。触发SSO登录你应该会看到一个登录界面上面很可能有一个显著的按钮例如“使用SSO登录”、“使用OIDC登录”或直接是“使用Authentik登录”如果LiteLLM UI根据配置自动生成了按钮文字。点击这个按钮。观察重定向点击后浏览器应立即被重定向到你的authentik登录页面https://auth.your-company.com/...。这是一个关键的成功信号说明LiteLLM端的重定向配置基本正确。完成认证在authentik页面输入你有权访问LiteLLM应用的账号密码进行登录。同意授权登录后authentik会显示一个授权页面询问你是否允许“LiteLLM AI Gateway”访问你的信息。点击“允许”或“同意”。回调与登录成功浏览器会被重定向回LiteLLM地址栏URL会变回LiteLLM的域名并带有一串很长的code参数。如果一切顺利页面加载完成后你将成功登录到LiteLLM的管理界面而不再看到登录按钮。验证成功的关键标志成功跳转到authentik并返回。成功以authentik中的用户身份登录LiteLLM UI。在LiteLLM UI上可能能看到当前登录的用户名或邮箱这些信息正是从authentik传递过来的。5. 高级配置与权限集成实战基础的SSO登录完成后集成工作只完成了一半。更强大的能力在于如何利用从authentik传递过来的用户信息在LiteLLM内部实现精细化的权限和成本控制。5.1 基于用户组的模型访问控制在企业管理中我们通常不希望所有员工都能调用最昂贵的GPT-4模型。我们可以通过authentik的用户组和LiteLLM的配置来实现。在Authentik中创建并管理用户组在authentik管理界面创建如ai_user_basic、ai_user_premium、ai_administrator等组并将用户分配到相应的组。在Authentik属性映射中传递组信息确保之前的属性映射表达式正确地将用户所属的组名列表传递到JWT Token的groups声明中。表达式类似return {groups: [group.name for group in ak_user_groups]}在LiteLLM中配置基于组的模型权限LiteLLM支持在config.yaml中为模型设置allowed_user_roles或通过动态配置来实现。一种常见做法是在LiteLLM的配置中将“组”映射为“角色”。model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo model_info: # 允许基础组和高级组用户访问 allowed_roles: [ai_user_basic, ai_user_premium, ai_administrator] - model_name: gpt-4 litellm_params: model: gpt-4 model_info: # 只允许高级组和管理员访问 allowed_roles: [ai_user_premium, ai_administrator]然后你需要编写一个简单的回调函数或中间件在LiteLLM收到请求时从JWT Token的groups声明中读取用户的组并将其与模型的allowed_roles进行比对决定是否允许调用。LiteLLM的acl_callback或custom_auth功能可以用于实现此逻辑。5.2 传递自定义声明与用户标识除了组信息我们可能还需要传递更多信息给LiteLLM用于审计、计费或个性化设置。员工编号/用户ID在authentik属性映射中可以添加employee_id: user.attributes.get(employee_number)。确保在“OIDC声明”字段中加入employee_id。部门信息类似地可以传递部门信息department: user.attributes.get(department)。在LiteLLM中使用这些信息这些自定义声明会出现在JWT Token中。LiteLLM在验证Token后可以解析出这些声明。你可以用于日志记录将employee_id和department记录到每一条API调用日志中便于后续审计和成本分摊。用于速率限制可以根据用户或部门设置不同的每秒请求数RPS限制。用于预算控制可以开发一个外部计费服务根据employee_id或department来累计使用量并检查预算。5.3 实现真正的“单点登出”标准的OIDC流程实现了单点登录SSO但单点登出SLO需要额外配置。理想情况下用户在LiteLLM点击退出应该同时退出authentik的会话。Authentik端配置确保你的authentik提供者配置中结束会话端点是正确可用的。通常是https://authentik.company/application/o/provider-slug/end-session/。你可以在authentik提供的元数据端点https://authentik.company/application/o/provider-slug/.well-known/openid-configuration中找到end_session_endpoint。LiteLLM端配置LiteLLM需要知道这个登出端点。查看LiteLLM文档看是否支持配置GENERIC_LOGOUT_ENDPOINT或类似的参数。如果支持将其配置为上述authentik的结束会话端点。登出流程当用户在LiteLLM点击退出时LiteLLM应清除自身的本地会话。将用户浏览器重定向到authentik的end_session_endpoint并附上必要的参数如id_token_hint和post_logout_redirect_uri。authentic收到请求后销毁全局会话并将用户重定向回LiteLLM指定的登出后页面。注意事项单点登出的实现依赖于客户端LiteLLM和身份提供商authentik双方对该协议的支持。有些简易的OIDC客户端可能未实现此功能。如果LiteLLM不支持你可能需要手动引导用户去authentik的“我的应用”页面或单独的身份门户进行登出。6. 故障排查与常见问题实录集成过程中难免会遇到问题。下面是我在多次集成中踩过的坑和总结的排查思路希望能帮你快速定位问题。6.1 问题排查通用流程当SSO登录失败时请遵循以下步骤像侦探一样查看线索检查浏览器开发者工具F12这是最重要的第一步。打开“网络”Network选项卡勾选“保留日志”Preserve log然后重现登录过程。重点关注状态码为302重定向、4xx客户端错误、5xx服务器错误的请求。重定向循环Redirect Loop如果看到浏览器在LiteLLM和authentik之间来回跳转多次最后失败。这通常意味着回调地址Redirect URI不匹配。请逐字符核对authentik中配置的重定向URI和LiteLLM的PROXY_BASE_URL以及它实际处理回调的路径。400 Bad Request查看这个错误请求的URL和参数。通常是发送给authentik的请求参数有误比如scope格式不对、response_type错误等。对照OIDC标准检查LiteLLM发出的初始认证请求。查看服务端日志Authentik日志在authentik管理员界面查看系统日志或者在部署authentik的服务器上查看容器/进程日志。搜索错误信息通常会有比较详细的描述如“无效的重定向URI”、“客户端认证失败”等。LiteLLM日志同样查看LiteLLM容器的日志输出。LiteLLM在OIDC流程失败时可能会打印出错误原因例如“无法验证Token签名”、“无法从端点获取用户信息”等。验证Token内容高级如果登录流程走到了回调一步但LiteLLM报错可能是Token解析有问题。你可以暂时修改LiteLLM的代码或配置让它打印出收到的ID Token注意Token是敏感信息仅在测试环境操作。然后使用像 jwt.io 这样的网站解码Token不要泄露secret检查其中的声明iss签发者、aud受众、exp过期时间、以及你自定义的groups、email等是否符合预期。6.2 常见问题速查表下表汇总了典型问题、可能原因和解决方案问题现象可能原因排查与解决方案点击登录后直接显示“无效请求”或“认证失败”。1. Authentik中的客户端ID或客户端密钥在LiteLLM中配置错误。2. Authentik的重定向URI与LiteLLM的实际回调地址不匹配。1. 重新核对并复制粘贴GENERIC_CLIENT_ID和GENERIC_CLIENT_SECRET注意有无多余空格。2.逐字符核对重定向URI。确保协议、主机名、端口、路径完全一致。LiteLLM的PROXY_BASE_URL是基础部分回调路径是附加的。成功跳转到authentik登录页输入密码后又跳回登录页或提示“同意失败”。1. 该用户在authentik中没有访问LiteLLM应用程序的权限策略阻止。2. 属性映射配置错误导致生成Token时出错。1. 检查authentik中LiteLLM应用的“策略绑定”确保测试用户满足至少一条策略。2. 检查authentik中OIDC提供者的“属性映射”表达式是否有语法错误。尝试一个最简单的映射如只返回{sub: user.pk}测试。在authentik登录并同意后浏览器跳转回LiteLLM但LiteLLM显示“Token验证失败”或空白错误页。1.时钟不同步LiteLLM服务器和authentik服务器的系统时间相差太大导致Token的exp过期时间或iat签发时间验证失败。2.签名密钥不匹配LiteLLM用于验证Token的JWKS公钥集获取失败或不对。3. Token中的aud受众声明与LiteLLM期待的客户端ID不匹配。1. 使用date命令检查两台服务器的时间确保使用NTP服务同步时间。2. 检查LiteLLM能否正常访问authentik的JWKS端点通常为https://authentik.company/application/o/provider-slug/.well-known/jwks.json。网络是否通畅3. 解码ID Token检查aud声明是否等于你在LiteLLM中配置的GENERIC_CLIENT_ID。登录成功但LiteLLM中显示的用户名/邮箱/组信息不对或为空。1. Authentik的属性映射没有正确配置或保存。2. 映射的OIDC声明名称与LiteLLM中GROUP_CLAIM等配置的期望名称不匹配。3. 用户在某些字段上没有值。1. 在authentik中编辑OIDC提供者或应用的属性映射检查表达式和“OIDC声明”字段。2. 解码ID Token查看实际传递的声明名是什么然后调整LiteLLM的GROUP_CLAIM等配置与之匹配。3. 在属性映射表达式中添加默认值逻辑例如department: user.attributes.get(department, 未分配)。本地开发环境HTTP集成正常部署到生产环境HTTPS后失败。1. 生产环境使用了自签名或内部CA证书而LiteLLM容器内不信任该CA。2. 配置中的URL没有从http://更新为https://。1. 将CA证书添加到LiteLLM运行容器的信任链中或者为生产环境申请受信任的SSL证书如Let‘s Encrypt。2. 全面检查所有配置项中的URLPROXY_BASE_URL、各个ENDPOINT以及authentik中的重定向URI确保全部使用https://。6.3 调试技巧与心得分阶段测试不要试图一次性配置完所有东西。先确保最基本的OIDC登录流程能走通不传递任何自定义属性然后再逐步添加组映射、自定义声明等高级功能。善用元数据端点authentik的OIDC提供者提供了一个标准的发现端点https://authentik.company/application/o/provider-slug/.well-known/openid-configuration。在浏览器中打开这个URL你会得到一个JSON里面包含了authorization_endpoint、token_endpoint、jwks_uri、end_session_endpoint等所有标准端点的准确URL。直接用这里面的值去配置LiteLLM可以避免手动拼接出错。理解OIDC Flow花点时间理解授权码模式Authorization Code Flow的步骤。知道了/authorize、/token、/userinfo这几个端点各自在流程中扮演的角色出了问题你就能更快地定位到是哪个环节的配置不对。日志级别在排查问题时临时将LiteLLM和authentik的日志级别调到DEBUG或INFO能获得更详细的过程信息对定位模糊错误非常有帮助。经过以上步骤的配置和排查你应该能够成功地将LiteLLM与authentik集成构建出一个统一、安全、可审计的企业AI服务访问入口。这套组合不仅解决了身份管理问题更为后续的精细化运营、成本控制和合规审计打下了坚实的基础。
1. 项目概述最近在折腾企业内部AI应用的安全接入发现很多团队在部署像LiteLLM这样的AI网关时身份认证这块是个头疼事。要么就是简单粗暴地用API Key管理起来一团乱麻要么就是自己从头写一套用户体系费时费力还容易出安全漏洞。我这边正好在深度使用authentik这个开源的身份平台就琢磨着能不能把它俩给打通了。authentik负责统一的人员认证和权限管理LiteLLM则专注做好大模型的路由和调用各司其职岂不美哉折腾了几天总算把集成流程跑通了整个过程比预想的要顺畅不少。这篇文章我就来详细拆解一下如何将LiteLLM无缝集成到authentik中实现一个既安全又便于管理的企业级AI服务入口。无论你是运维工程师、DevOps还是负责AI应用落地的开发者这套方案都能帮你省去大量重复造轮子的时间。简单来说这个集成的核心价值在于用一个统一的账号体系安全、可控地接入企业内部所有需要调用大模型的应用。员工不再需要记住一堆不同服务的密码或API Key管理员也能在一个界面里清晰地看到谁在什么时候、用什么权限访问了哪些AI模型。这对于满足企业安全审计、合规要求以及精细化成本控制来说是至关重要的一步。2. 集成方案的整体设计与核心思路在开始动手配置之前我们得先搞清楚这两个组件各自扮演什么角色以及它们之间是如何“对话”的。这决定了我们配置的每一步背后的逻辑而不仅仅是照搬步骤。2.1 组件角色定位与协议选择Authentik在这里它扮演的是身份提供商Identity Provider, IdP的角色。它的核心工作是“认人”。当用户试图访问LiteLLM时authentik会拦截这个请求要求用户登录。用户成功登录后authentik会生成一个包含用户身份信息比如用户名、邮箱、所属组的安全令牌通常是JWT格式然后把这个令牌交给LiteLLM。LiteLLM在这里它扮演的是服务提供商Service Provider, SP或依赖方Relying Party, RP的角色。它的核心工作是“信人”和“办事”。它收到来自authentik的令牌后会验证这个令牌的真实性比如签名是否正确、是否过期然后解析出里面的用户信息。根据这些信息LiteLLM可以决定是否允许该用户访问以及这个用户能调用哪些模型、有什么样的速率限制等。通信协议为了让IdP和SP能安全、标准地交换用户信息我们采用OAuth 2.0 / OpenID Connect (OIDC)协议。这是目前业界最主流的单点登录SSO标准协议。简单理解OAuth 2.0解决了授权允许某个应用访问你的资源的问题而OIDC在OAuth 2.0之上增加了一层身份认证明确告诉你“你是谁”的标准。我们这次集成主要利用OIDC的能力。2.2 核心交互流程拆解整个单点登录的流程可以类比成一次特殊的“访客入园”发起访问用户打开浏览器输入LiteLLM的地址比如http://litellm.internal.company.com。重定向至认证中心LiteLLMSP发现用户没有登录凭证于是立即将用户的浏览器重定向到authentikIdP的登录页面并附上自己的“名片”Client ID和想访问的“区域”Scope如openid, profile, email。用户认证用户在authentik的页面上输入用户名和密码或其他已配置的认证方式如LDAP、Social Login等进行登录。征询用户同意authentik会向用户展示“LiteLLM应用请求访问你的基本信息如用户名、邮箱你同意吗”用户点击同意。颁发通行证authentik验证通过后生成一个授权码Authorization Code通过浏览器重定向回LiteLLM事先登记好的一个“回调地址”Callback URL。兑换身份令牌LiteLLM的后台服务拿到这个授权码后不会直接使用它。它会带着这个授权码、自己的“名片”Client ID和“密码”Client Secret再次秘密地访问authentik的另一个特定接口Token Endpoint用授权码兑换一个真正的、包含用户信息的ID TokenJWT格式和一个访问令牌Access Token。验证并创建本地会话LiteLLM验证ID Token的签名确保是authentik颁发的、有效期等信息。验证通过后它从Token里解析出用户的身份信息如preferred_username,email,groups等并在LiteLLM内部为该用户创建一个登录会话Session。访问成功用户的浏览器被重定向回LiteLLM的主界面此时他已经处于登录状态可以开始使用AI服务了。这个流程的关键在于用户的密码始终只存在于authentik和用户之间LiteLLM从未接触过用户密码大大提升了安全性。同时用户只需要在authentik登录一次就可以访问所有接入了authentik的应用实现了单点登录。2.3 前置准备与环境假设为了后续说明清晰我们需要先定义几个占位符请你在实际操作中替换成自己的真实环境authentik.company: 这是你部署的authentik服务的完整域名FQDN。例如auth.your-company.com或192.168.1.100:9000如果直接用IP和端口访问。litellm.company: 这是你部署的LiteLLM服务的完整域名FQDN。例如ai-gateway.your-company.com或192.168.1.101:4000。注意在生产环境中强烈建议使用正式的域名和HTTPS。自签名证书或内部CA签发的证书需要在LiteLLM和用户浏览器中被信任否则会导致SSL错误集成失败。如果是在内网测试可以暂时使用HTTP但务必知晓其安全风险。此外你需要确保你已经拥有一个正常运行的authentik实例并且拥有管理员权限。你已经部署了LiteLLM并且其Web UI可以正常访问。网络互通运行LiteLLM的服务器能够访问到authentik的服务端点/application/o/authorize/,/application/o/token/等。3. Authentik端详细配置步骤现在我们进入实操环节。首先在身份提供商authentik这边进行配置为LiteLLM这个“新应用”颁发“接入许可”。3.1 创建OAuth2/OIDC提供者登录到authentik的管理员界面。导航至提供者在左侧导航栏找到“身份提供”下的“提供者”点击进入。然后点击右上角的“创建”按钮。选择提供者类型在创建页面我们需要为这个提供者起个名字例如LiteLLM OIDC Provider。在“类型”下拉框中选择“OAuth2/OpenID Connect”。这个选择至关重要它决定了authentik将以OIDC协议与LiteLLM通信。配置认证流程在“认证流程”字段你需要选择一个流程。通常我们可以使用authentik自带的默认流程“default-authentication-flow”。这个流程定义了用户登录时的界面和步骤如输入用户名密码、可能的多因素认证等。如果你有自定义的复杂登录流程比如结合了LDAP、短信验证码可以在这里选择你创建好的流程。配置关键参数这是核心部分需要仔细填写。客户端类型选择“机密”。这意味着LiteLLM客户端会持有一个密码Client Secret来向authentik证明自己安全性更高。与之相对的是“公开”类型适用于无法安全保存密码的场景如手机App、单页应用但我们的LiteLLM服务端部署可以安全保存密码所以选“机密”。重定向 URI这是整个配置中最容易出错的地方之一。你必须准确填写LiteLLM用于接收认证回调的地址。格式通常为http(s)://litellm.company/sso/callback。例如https://ai-gateway.internal.com/sso/callback。这里有几个关键点协议必须与LiteLLM实际访问的协议一致HTTP或HTTPS。主机名和端口必须与LiteLLM服务访问地址完全一致。路径/sso/callback是LiteLLM默认的OIDC回调端点。请务必查阅你的LiteLLM文档确认不同版本或部署方式可能有差异。严格匹配authentik会进行严格比对多一个斜杠或少一个端口号都会导致认证失败。建议先填写一个如果失败再结合LiteLLM的日志和authentik的错误提示进行排查。签署密钥与算法在“签署密钥”处选择一个已有的密钥对如authentik Self-signed Certificate。这个密钥用于对颁发的JWT ID Token进行签名LiteLLM会用对应的公钥来验证Token的真实性。“算法”保持默认的RS256非对称加密即可这是最安全通用的选择。高级设置重要启用加密务必保持禁用不勾选。除非你非常清楚JWT加密JWE的配置并且LiteLLM也支持解密否则开启加密会导致LiteLLM无法解析Token内容集成失败。作用域这里定义了LiteLLM可以请求获取用户的哪些信息。默认的openid是必须的。建议至少加上profile获取用户名等基本信息和email获取邮箱。你还可以根据LiteLLM的需要添加自定义作用域比如后面会用到的litellm_role。属性映射这是将authentik中的用户属性如用户名、邮箱、所属组映射到JWT Token声明Claims中的关键步骤。我们稍后在创建应用后一起配置会更方便。保存提供者检查所有配置无误后点击“提交”按钮。创建成功后系统会生成两个关键信息“客户端ID”和“客户端密钥”。请立即妥善保存这两个值最好复制到本地文本编辑器或密码管理器中因为在LiteLLM配置时需要用到。客户端密钥只显示一次忘记后只能重新生成。3.2 创建对应的应用程序提供者定义了“如何认证”应用程序则定义了“谁可以访问这个应用”以及“应用本身的信息”。导航至应用程序在左侧导航栏找到“应用”下的“应用程序”点击进入。然后点击“使用提供者创建”按钮。这个按钮可以一次性创建应用并关联提供者比较方便。配置应用基本信息名称填写一个易于识别的名称如LiteLLM AI Gateway。这个名称会显示在用户的“我的应用”门户中。Slug系统会根据名称自动生成一个URL友好的标识符如litellm-ai-gateway可以手动修改。它在一些内部URL中会用到保持默认即可。提供者在下拉框中选择我们上一步刚刚创建的LiteLLM OIDC Provider。策略引擎模式选择“任何”表示只要满足任意一条关联的访问策略用户即可访问。选择“全部”则表示必须满足所有关联策略。初期为了测试可以先选择“任何”并暂时不绑定任何策略这样所有能登录authentik的用户都能访问LiteLLM。生产环境中务必根据实际情况配置严格的策略。配置UI设置可选但推荐你可以上传一个图标并填写应用描述这样在用户门户中看起来更美观专业。配置属性映射这是将用户信息传递给LiteLLM的核心。在创建应用的页面或编辑已创建应用的页面找到“属性映射”部分点击“创建”。名称例如LiteLLM User Claims。表达式这里使用authentik的模板语言。我们需要映射几个关键信息到JWT的声明里。假设我们想把用户的邮箱作为JWT中的email声明把用户名作为preferred_username可以这样写这是一个示例你可以根据需要调整# 映射邮箱 return { email: user.email, preferred_username: user.username, # 映射用户所在的组名列表这对LiteLLM做权限控制非常有用 groups: [group.name for group in ak_user_groups], # 可以添加自定义声明例如一个角色字段 litellm_role: ai_user if user.is_superuser else ai_guest }SAML/其他名称保持默认或留空因为我们用的是OIDC。OIDC 声明这里必须填写。它告诉authentik上面表达式返回的字典中的哪些键应该被放到ID Token里。填写你希望在Token中出现的声明名用空格分隔。例如email preferred_username groups litellm_role。保存应用程序点击提交完成应用的创建。3.3 配置访问策略生产环境必备为了让集成真正可用我们必须配置谁可以访问这个LiteLLM应用。authentik强大的策略引擎可以让你实现非常精细的控制。创建策略在“策略/权限”-“策略”中可以创建各种类型的策略。例如表达式策略通过编写返回True或False的表达式来控制。例如只允许邮箱以ai-team.com结尾的用户访问return user.email.endswith(ai-team.com)。组策略只允许属于特定组的用户访问。例如创建一个“AI平台用户”组将相关用户加入该组然后创建策略绑定这个组。绑定策略到应用在刚刚创建的LiteLLM应用程序的编辑页面找到“策略绑定”选项卡。点击“创建”选择你创建好的策略并设置一个合适的名称和顺序。策略会按照顺序执行。测试策略你可以用一个不符合策略条件的测试账号尝试访问LiteLLM应该会被authentik拒绝并看到“拒绝访问”之类的提示。至此authentik端的配置就全部完成了。我们已经创建了一个OIDC提供者、一个应用程序并定义了如何将用户信息传递给LiteLLM以及谁可以访问。接下来我们去LiteLLM那边进行配置。4. LiteLLM端详细配置与验证LiteLLM的配置主要集中在它的配置文件或环境变量中。我们需要告诉LiteLLM“当有用户需要登录时请去找authentikIdP这是它的地址和你的凭证。”4.1 定位与理解LiteLLM配置LiteLLM的配置方式取决于你的部署方式Docker部署通常通过环境变量或挂载的config.yaml文件配置。源码/Pip安装通过环境变量或启动命令参数配置。LiteLLM Proxy我们主要针对其Proxy的Web UI的SSO功能进行配置。关键的配置项都围绕OIDC展开。你需要准备以下从authentik获取的信息GENERIC_CLIENT_ID: 即authentik中创建的OIDC提供者的“客户端ID”。GENERIC_CLIENT_SECRET: 对应的“客户端密钥”。GENERIC_AUTHORIZATION_ENDPOINT: authentik的授权端点格式为https://authentik.company/application/o/authorize/。GENERIC_TOKEN_ENDPOINT: authentik的令牌端点格式为https://authentik.company/application/o/token/。GENERIC_USERINFO_ENDPOINT: authentik的用户信息端点格式为https://authentik.company/application/o/userinfo/。LiteLLM可能会用这个端点来获取更详细的用户信息。PROXY_ADMIN_EMAIL: 指定一个管理员邮箱用于接收系统通知可选但建议设置。PROXY_BASE_URL: LiteLLM Proxy服务对外的基础URL格式为http(s)://litellm.company。这个必须与authentik中配置的重定向URI的域名部分完全一致。GROUP_CLAIM: 这个参数告诉LiteLLM在JWT Token的哪个声明Claim里可以找到用户的组信息。根据我们在authentik属性映射中设置的groups声明这里应该填写groups。如果你映射的声明名是ak_groups这里就填ak_groups。4.2 具体配置方法示例方法一通过环境变量配置推荐用于Docker/K8s如果你使用Docker运行LiteLLM Proxy可以在docker run命令或docker-compose.yml中设置环境变量# docker-compose.yml 示例片段 version: 3.8 services: litellm-proxy: image: ghcr.io/berriai/litellm:main-latest container_name: litellm-proxy ports: - 4000:4000 environment: - GENERIC_CLIENT_IDyour_client_id_from_authentik - GENERIC_CLIENT_SECRETyour_client_secret_from_authentik - GENERIC_AUTHORIZATION_ENDPOINThttps://auth.your-company.com/application/o/authorize/ - GENERIC_TOKEN_ENDPOINThttps://auth.your-company.com/application/o/token/ - GENERIC_USERINFO_ENDPOINThttps://auth.your-company.com/application/o/userinfo/ - PROXY_ADMIN_EMAILadminyour-company.com - PROXY_BASE_URLhttps://ai-gateway.your-company.com - GROUP_CLAIMgroups # 其他LiteLLM配置如模型列表、密钥等 - LITELLM_MODEL_LIST[...] command: --port 4000 --config /path/to/config.yaml方法二通过config.yaml配置文件你也可以在LiteLLM的配置文件中指定这些参数。配置文件的结构可能因版本而异但OIDC配置通常在一个独立的SSO部分。# config.yaml 示例片段 model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo api_key: ${OPENAI_API_KEY} litellm_settings: drop_params: true general_settings: admin_email: adminyour-company.com proxy_base_url: https://ai-gateway.your-company.com sso_settings: enabled: true provider: generic generic_client_id: your_client_id_from_authentik generic_client_secret: your_client_secret_from_authentik generic_authorization_endpoint: https://auth.your-company.com/application/o/authorize/ generic_token_endpoint: https://auth.your-company.com/application/o/token/ generic_userinfo_endpoint: https://auth.your-company.com/application/o/userinfo/ group_claim: groups实操心得我个人更倾向于使用环境变量来管理敏感信息如CLIENT_SECRET和可能因环境而变的配置如各个Endpoint的URL。这样可以将配置与代码/镜像分离更符合十二要素应用原则也便于在CI/CD流水线或K8s中管理。配置文件则用来存放相对固定的模型定义等设置。4.3 启动服务与验证配置配置完成后重启LiteLLM Proxy服务以使配置生效。访问LiteLLM UI打开浏览器访问你的LiteLLM地址如https://ai-gateway.your-company.com。触发SSO登录你应该会看到一个登录界面上面很可能有一个显著的按钮例如“使用SSO登录”、“使用OIDC登录”或直接是“使用Authentik登录”如果LiteLLM UI根据配置自动生成了按钮文字。点击这个按钮。观察重定向点击后浏览器应立即被重定向到你的authentik登录页面https://auth.your-company.com/...。这是一个关键的成功信号说明LiteLLM端的重定向配置基本正确。完成认证在authentik页面输入你有权访问LiteLLM应用的账号密码进行登录。同意授权登录后authentik会显示一个授权页面询问你是否允许“LiteLLM AI Gateway”访问你的信息。点击“允许”或“同意”。回调与登录成功浏览器会被重定向回LiteLLM地址栏URL会变回LiteLLM的域名并带有一串很长的code参数。如果一切顺利页面加载完成后你将成功登录到LiteLLM的管理界面而不再看到登录按钮。验证成功的关键标志成功跳转到authentik并返回。成功以authentik中的用户身份登录LiteLLM UI。在LiteLLM UI上可能能看到当前登录的用户名或邮箱这些信息正是从authentik传递过来的。5. 高级配置与权限集成实战基础的SSO登录完成后集成工作只完成了一半。更强大的能力在于如何利用从authentik传递过来的用户信息在LiteLLM内部实现精细化的权限和成本控制。5.1 基于用户组的模型访问控制在企业管理中我们通常不希望所有员工都能调用最昂贵的GPT-4模型。我们可以通过authentik的用户组和LiteLLM的配置来实现。在Authentik中创建并管理用户组在authentik管理界面创建如ai_user_basic、ai_user_premium、ai_administrator等组并将用户分配到相应的组。在Authentik属性映射中传递组信息确保之前的属性映射表达式正确地将用户所属的组名列表传递到JWT Token的groups声明中。表达式类似return {groups: [group.name for group in ak_user_groups]}在LiteLLM中配置基于组的模型权限LiteLLM支持在config.yaml中为模型设置allowed_user_roles或通过动态配置来实现。一种常见做法是在LiteLLM的配置中将“组”映射为“角色”。model_list: - model_name: gpt-3.5-turbo litellm_params: model: gpt-3.5-turbo model_info: # 允许基础组和高级组用户访问 allowed_roles: [ai_user_basic, ai_user_premium, ai_administrator] - model_name: gpt-4 litellm_params: model: gpt-4 model_info: # 只允许高级组和管理员访问 allowed_roles: [ai_user_premium, ai_administrator]然后你需要编写一个简单的回调函数或中间件在LiteLLM收到请求时从JWT Token的groups声明中读取用户的组并将其与模型的allowed_roles进行比对决定是否允许调用。LiteLLM的acl_callback或custom_auth功能可以用于实现此逻辑。5.2 传递自定义声明与用户标识除了组信息我们可能还需要传递更多信息给LiteLLM用于审计、计费或个性化设置。员工编号/用户ID在authentik属性映射中可以添加employee_id: user.attributes.get(employee_number)。确保在“OIDC声明”字段中加入employee_id。部门信息类似地可以传递部门信息department: user.attributes.get(department)。在LiteLLM中使用这些信息这些自定义声明会出现在JWT Token中。LiteLLM在验证Token后可以解析出这些声明。你可以用于日志记录将employee_id和department记录到每一条API调用日志中便于后续审计和成本分摊。用于速率限制可以根据用户或部门设置不同的每秒请求数RPS限制。用于预算控制可以开发一个外部计费服务根据employee_id或department来累计使用量并检查预算。5.3 实现真正的“单点登出”标准的OIDC流程实现了单点登录SSO但单点登出SLO需要额外配置。理想情况下用户在LiteLLM点击退出应该同时退出authentik的会话。Authentik端配置确保你的authentik提供者配置中结束会话端点是正确可用的。通常是https://authentik.company/application/o/provider-slug/end-session/。你可以在authentik提供的元数据端点https://authentik.company/application/o/provider-slug/.well-known/openid-configuration中找到end_session_endpoint。LiteLLM端配置LiteLLM需要知道这个登出端点。查看LiteLLM文档看是否支持配置GENERIC_LOGOUT_ENDPOINT或类似的参数。如果支持将其配置为上述authentik的结束会话端点。登出流程当用户在LiteLLM点击退出时LiteLLM应清除自身的本地会话。将用户浏览器重定向到authentik的end_session_endpoint并附上必要的参数如id_token_hint和post_logout_redirect_uri。authentic收到请求后销毁全局会话并将用户重定向回LiteLLM指定的登出后页面。注意事项单点登出的实现依赖于客户端LiteLLM和身份提供商authentik双方对该协议的支持。有些简易的OIDC客户端可能未实现此功能。如果LiteLLM不支持你可能需要手动引导用户去authentik的“我的应用”页面或单独的身份门户进行登出。6. 故障排查与常见问题实录集成过程中难免会遇到问题。下面是我在多次集成中踩过的坑和总结的排查思路希望能帮你快速定位问题。6.1 问题排查通用流程当SSO登录失败时请遵循以下步骤像侦探一样查看线索检查浏览器开发者工具F12这是最重要的第一步。打开“网络”Network选项卡勾选“保留日志”Preserve log然后重现登录过程。重点关注状态码为302重定向、4xx客户端错误、5xx服务器错误的请求。重定向循环Redirect Loop如果看到浏览器在LiteLLM和authentik之间来回跳转多次最后失败。这通常意味着回调地址Redirect URI不匹配。请逐字符核对authentik中配置的重定向URI和LiteLLM的PROXY_BASE_URL以及它实际处理回调的路径。400 Bad Request查看这个错误请求的URL和参数。通常是发送给authentik的请求参数有误比如scope格式不对、response_type错误等。对照OIDC标准检查LiteLLM发出的初始认证请求。查看服务端日志Authentik日志在authentik管理员界面查看系统日志或者在部署authentik的服务器上查看容器/进程日志。搜索错误信息通常会有比较详细的描述如“无效的重定向URI”、“客户端认证失败”等。LiteLLM日志同样查看LiteLLM容器的日志输出。LiteLLM在OIDC流程失败时可能会打印出错误原因例如“无法验证Token签名”、“无法从端点获取用户信息”等。验证Token内容高级如果登录流程走到了回调一步但LiteLLM报错可能是Token解析有问题。你可以暂时修改LiteLLM的代码或配置让它打印出收到的ID Token注意Token是敏感信息仅在测试环境操作。然后使用像 jwt.io 这样的网站解码Token不要泄露secret检查其中的声明iss签发者、aud受众、exp过期时间、以及你自定义的groups、email等是否符合预期。6.2 常见问题速查表下表汇总了典型问题、可能原因和解决方案问题现象可能原因排查与解决方案点击登录后直接显示“无效请求”或“认证失败”。1. Authentik中的客户端ID或客户端密钥在LiteLLM中配置错误。2. Authentik的重定向URI与LiteLLM的实际回调地址不匹配。1. 重新核对并复制粘贴GENERIC_CLIENT_ID和GENERIC_CLIENT_SECRET注意有无多余空格。2.逐字符核对重定向URI。确保协议、主机名、端口、路径完全一致。LiteLLM的PROXY_BASE_URL是基础部分回调路径是附加的。成功跳转到authentik登录页输入密码后又跳回登录页或提示“同意失败”。1. 该用户在authentik中没有访问LiteLLM应用程序的权限策略阻止。2. 属性映射配置错误导致生成Token时出错。1. 检查authentik中LiteLLM应用的“策略绑定”确保测试用户满足至少一条策略。2. 检查authentik中OIDC提供者的“属性映射”表达式是否有语法错误。尝试一个最简单的映射如只返回{sub: user.pk}测试。在authentik登录并同意后浏览器跳转回LiteLLM但LiteLLM显示“Token验证失败”或空白错误页。1.时钟不同步LiteLLM服务器和authentik服务器的系统时间相差太大导致Token的exp过期时间或iat签发时间验证失败。2.签名密钥不匹配LiteLLM用于验证Token的JWKS公钥集获取失败或不对。3. Token中的aud受众声明与LiteLLM期待的客户端ID不匹配。1. 使用date命令检查两台服务器的时间确保使用NTP服务同步时间。2. 检查LiteLLM能否正常访问authentik的JWKS端点通常为https://authentik.company/application/o/provider-slug/.well-known/jwks.json。网络是否通畅3. 解码ID Token检查aud声明是否等于你在LiteLLM中配置的GENERIC_CLIENT_ID。登录成功但LiteLLM中显示的用户名/邮箱/组信息不对或为空。1. Authentik的属性映射没有正确配置或保存。2. 映射的OIDC声明名称与LiteLLM中GROUP_CLAIM等配置的期望名称不匹配。3. 用户在某些字段上没有值。1. 在authentik中编辑OIDC提供者或应用的属性映射检查表达式和“OIDC声明”字段。2. 解码ID Token查看实际传递的声明名是什么然后调整LiteLLM的GROUP_CLAIM等配置与之匹配。3. 在属性映射表达式中添加默认值逻辑例如department: user.attributes.get(department, 未分配)。本地开发环境HTTP集成正常部署到生产环境HTTPS后失败。1. 生产环境使用了自签名或内部CA证书而LiteLLM容器内不信任该CA。2. 配置中的URL没有从http://更新为https://。1. 将CA证书添加到LiteLLM运行容器的信任链中或者为生产环境申请受信任的SSL证书如Let‘s Encrypt。2. 全面检查所有配置项中的URLPROXY_BASE_URL、各个ENDPOINT以及authentik中的重定向URI确保全部使用https://。6.3 调试技巧与心得分阶段测试不要试图一次性配置完所有东西。先确保最基本的OIDC登录流程能走通不传递任何自定义属性然后再逐步添加组映射、自定义声明等高级功能。善用元数据端点authentik的OIDC提供者提供了一个标准的发现端点https://authentik.company/application/o/provider-slug/.well-known/openid-configuration。在浏览器中打开这个URL你会得到一个JSON里面包含了authorization_endpoint、token_endpoint、jwks_uri、end_session_endpoint等所有标准端点的准确URL。直接用这里面的值去配置LiteLLM可以避免手动拼接出错。理解OIDC Flow花点时间理解授权码模式Authorization Code Flow的步骤。知道了/authorize、/token、/userinfo这几个端点各自在流程中扮演的角色出了问题你就能更快地定位到是哪个环节的配置不对。日志级别在排查问题时临时将LiteLLM和authentik的日志级别调到DEBUG或INFO能获得更详细的过程信息对定位模糊错误非常有帮助。经过以上步骤的配置和排查你应该能够成功地将LiteLLM与authentik集成构建出一个统一、安全、可审计的企业AI服务访问入口。这套组合不仅解决了身份管理问题更为后续的精细化运营、成本控制和合规审计打下了坚实的基础。
)
