OpenID Connect 令牌重用

LibreChat 支持重用由您的 OpenID Connect 提供商（如 Azure Entra ID 或 Auth0）颁发的访问令牌和刷新令牌，以管理用户身份验证状态。当此功能启用时，作为 Cookie 传递给用户的刷新令牌将由您的 OpenID 提供商而非 LibreChat 颁发，从而允许 LibreChat 服务器刷新该令牌并向您的提供商请求访问令牌。

先决条件

• 一个已配置的 OpenID Connect 提供商（如 Azure Entra ID、Auth0 等）
• 基础 OpenID Connect 设置已完成

配置步骤

1. 在你的环境变量中设置 OPENID_REUSE_TOKENS=true。

提供商特定配置

Auth0 配置

对于 Auth0，你需要：

1. 在 Auth0 中创建一个 API（JWT 访问令牌所必需）：

   • 前往 Auth0 Dashboard → Applications → APIs
   • 点击 "Create API"
   • 设置一个 Identifier（例如 https://api.librechat.com）
   • 在 API 设置中启用 "Allow Offline Access"

2. 设置所需的环境变量：

   # Required for Auth0
   OPENID_AUDIENCE=https://api.librechat.com  # Your API identifier from Auth0
   OPENID_SCOPE=openid profile email offline_access

有关 Auth0 配置的详细信息，请参阅：Auth0 OpenID Connect Configuration

Azure Entra ID 配置

2. 配置您的 OpenID 提供商（以 Azure Entra ID 为例）：
   • 前往 Azure Portal 并导航至您的应用注册 (app registration)
   • 点击左侧菜单中的 "Expose API"
   • 点击“Application ID URI”旁边的“Add”
   • 输入您的 API URI（例如 "api://librechat"）并保存

3. 创建 API 范围：
   • 在“Expose API”部分，点击“Add a scope”
   • 配置具有适当权限的范围
   • 保存范围配置

4. 配置 API 权限：
   • 前往左侧菜单中的 "API permissions"
   • 点击“Add a permission”
   • 在“APIs my organization uses”下，搜索您的应用
   • 选择“Delegated permissions”并选择适当的范围（例如，“access_user”）

5. 在您的环境中设置所需的 scope：

   OPENID_SCOPE=api://librechat/.default openid profile email offline_access

   注意：需要 offline_access 作用域才能获取用于重用的刷新令牌。

6. 授予管理员许可：

   • 前往 Azure Portal 中的 Enterprise Applications
   • 找到您的 LibreChat 应用程序
   • 导航至 Security > Permissions
   • 点击“Grant admin consent”

7. 在弹窗中接受请求的权限

8. 清除 LibreChat 缓存并重启服务。

环境变量

# OpenID Token Reuse Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=api://librechat/.default openid profile email offline_access
OPENID_REUSE_MAX_SESSION_AGE_MS=900000  # 15 minutes in milliseconds
 
# Required for Auth0 (use your API identifier)
# OPENID_AUDIENCE=https://api.librechat.com
 
# Caching Configuration
OPENID_JWKS_URL_CACHE_ENABLED=true
OPENID_JWKS_URL_CACHE_TIME=600000  # 10 minutes in milliseconds
 
# Azure-specific Configuration
OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED=true
OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE=user.read
 
# Logout Configuration
OPENID_USE_END_SESSION_ENDPOINT=true

其他配置选项

• OPENID_AUDIENCE: 用于 JWT 验证和授权请求的受众值。Auth0 必需，以便接收 JWT 访问令牌而非不透明令牌。JWT 验证支持逗号分隔的值；授权请求使用第一个非空值。
• OPENID_REUSE_MAX_SESSION_AGE_MS: 重用 OpenID 会话令牌在 LibreChat 强制执行 IdP 刷新之前可被提供的最长有效期（默认值：900000 毫秒 / 15 分钟）。接受诸如 60 * 60 * 24 * 1000 之类的算术表达式。如果您的提供商在刷新时会撤销之前的访问令牌，请将其增加至接近您 IdP 访问令牌的生命周期。
• OPENID_JWKS_URL_CACHE_ENABLED: 启用签名密钥验证结果的缓存，以防止向 JWKS endpoint 发送过多的 HTTP 请求
• OPENID_JWKS_URL_CACHE_TIME：缓存持续时间，单位为毫秒（默认：600000 毫秒 / 10 分钟）
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: 启用用于用户信息获取的代表（on-behalf-of）流程（Azure 专用）
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: 代表流（on-behalf-of flow）中用户信息的范围（Azure 专用）
• OPENID_USE_END_SESSION_ENDPOINT: 启用注销时使用的结束会话端点 (end session endpoint)

安全注意事项

• 确保正确的令牌存储和处理
• 实现适当的令牌刷新机制
• 监控令牌使用情况，并在必要时实施速率限制
• 定期轮换客户端密钥
• 使用安全的 cookie 设置来存储令牌

故障排除

如果您在令牌重用方面遇到问题：

1. 验证所有必需的 scopes 是否已正确配置
2. 检查是否已授予管理员许可
3. 确保已正确设置 API 权限
4. 验证令牌缓存是否按预期工作
5. 检查应用程序日志以查看是否有任何身份验证错误
6. 通过在环境变量中设置 DEBUG_OPENID_REQUESTS=true 来启用详细的 OpenID 请求头日志记录，以便在查看 URL 的同时查看请求头（敏感数据已被脱敏）。