Tái sử dụng Token OpenID Connect

LibreChat hỗ trợ việc tái sử dụng access token và refresh token được cấp bởi nhà cung cấp OpenID Connect của bạn (như Azure Entra ID hoặc Auth0) để quản lý trạng thái xác thực người dùng. Khi tính năng này được kích hoạt, refresh token được chuyển đến người dùng dưới dạng cookie sẽ do nhà cung cấp OpenID của bạn cấp thay vì LibreChat, cho phép các máy chủ LibreChat làm mới token đó và yêu cầu access token từ nhà cung cấp của bạn.

Điều kiện tiên quyết

• Một nhà cung cấp OpenID Connect đã được cấu hình (như Azure Entra ID, Auth0, v.v.)
• Đã hoàn tất thiết lập OpenID Connect cơ bản

Các bước cấu hình

1. Đặt OPENID_REUSE_TOKENS=true trong các biến môi trường của bạn.

Cấu hình cụ thể cho từng Provider

Cấu hình Auth0

Đối với Auth0, bạn cần:

1. Tạo một API trong Auth0 (bắt buộc để có mã truy cập JWT):

   • Đi tới Auth0 Dashboard → Applications → APIs
   • Nhấp vào "Create API"
   • Thiết lập một Identifier (ví dụ: https://api.librechat.com)
   • Bật "Allow Offline Access" trong cài đặt API

2. Thiết lập các biến môi trường bắt buộc:

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

Để biết cấu hình Auth0 chi tiết, hãy xem: Auth0 OpenID Connect Configuration

Cấu hình Azure Entra ID

2. Cấu hình nhà cung cấp OpenID của bạn (sử dụng Azure Entra ID làm ví dụ):
   • Truy cập Azure Portal và điều hướng đến đăng ký ứng dụng của bạn
   • Nhấp vào "Expose API" trong menu bên trái
   • Nhấp vào "Add" bên cạnh "Application ID URI"
   • Nhập API URI của bạn (ví dụ: "api://librechat") và lưu lại

3. Tạo một API scope:
   • Trong phần "Expose API", nhấp vào "Add a scope"
   • Cấu hình phạm vi với các quyền thích hợp
   • Lưu cấu hình phạm vi

4. Cấu hình quyền API:
   • Đi tới "API permissions" trong menu bên trái
   • Nhấp vào "Add a permission"
   • Dưới mục "APIs my organization uses", hãy tìm kiếm ứng dụng của bạn
   • Chọn "Delegated permissions" và chọn phạm vi (scope) phù hợp (ví dụ: "access_user")

5. Thiết lập phạm vi (scope) bắt buộc trong môi trường của bạn:

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

   Lưu ý: Phạm vi offline_access là bắt buộc để lấy mã làm mới (refresh token) nhằm mục đích tái sử dụng.

6. Cấp quyền quản trị:

   • Đi tới Enterprise Applications trong Azure Portal
   • Tìm ứng dụng LibreChat của bạn
   • Điều hướng đến Security > Permissions
   • Nhấp vào "Grant admin consent"

7. Chấp nhận các quyền được yêu cầu trong cửa sổ bật lên

8. Xóa bộ nhớ đệm LibreChat và khởi động lại dịch vụ.

Các biến môi trường

# 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

# Maximum logout URL length before using logout_hint instead of id_token_hint (default: 2000)
# OPENID_MAX_LOGOUT_URL_LENGTH=2000

Các tùy chọn cấu hình bổ sung

• OPENID_AUDIENCE: Giá trị audience cho việc xác thực JWT và các yêu cầu ủy quyền. Bắt buộc đối với Auth0 để nhận JWT access token thay vì opaque token. Các giá trị được phân tách bằng dấu phẩy được chấp nhận cho việc xác thực JWT; các yêu cầu ủy quyền sẽ sử dụng giá trị khác rỗng đầu tiên.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Thời gian tối đa một token phiên OpenID được tái sử dụng trước khi LibreChat buộc làm mới IdP (mặc định: 900000 ms / 15 phút). Chấp nhận các biểu thức số học như 60 * 60 * 24 * 1000. Hãy tăng giá trị này hướng tới thời hạn access-token của IdP nếu nhà cung cấp của bạn thu hồi access-token trước đó mỗi khi nó được làm mới.
• OPENID_JWKS_URL_CACHE_ENABLED: Cho phép lưu bộ nhớ đệm các kết quả xác minh khóa ký để ngăn chặn các yêu cầu HTTP quá mức tới endpoint JWKS
• OPENID_JWKS_URL_CACHE_TIME: Thời gian lưu cache tính bằng mili giây (mặc định: 600000 ms / 10 phút)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Kích hoạt luồng on-behalf-of cho thông tin người dùng (dành riêng cho Azure)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Scope cho thông tin người dùng trong luồng on-behalf-of (dành riêng cho Azure)
• OPENID_USE_END_SESSION_ENDPOINT: Cho phép sử dụng endpoint kết thúc phiên (end session endpoint) để đăng xuất
• OPENID_MAX_LOGOUT_URL_LENGTH: Độ dài URL tối đa trước khi sử dụng logout_hint thay vì id_token_hint để ngăn lỗi URI quá dài (mặc định: 2000)

Các cân nhắc về bảo mật

• Đảm bảo việc lưu trữ và xử lý token đúng cách
• Triển khai các cơ chế làm mới token phù hợp
• Theo dõi mức sử dụng token và triển khai giới hạn tốc độ (rate limiting) nếu cần thiết
• Thường xuyên xoay vòng các client secrets
• Sử dụng các thiết lập cookie bảo mật để lưu trữ token

Khắc phục sự cố

Nếu bạn gặp sự cố với việc sử dụng lại token:

1. Xác minh tất cả các phạm vi (scopes) bắt buộc đã được cấu hình đúng cách
2. Kiểm tra xem đã cấp quyền quản trị viên hay chưa
3. Đảm bảo các quyền API đã được thiết lập chính xác
4. Xác minh bộ nhớ đệm token đang hoạt động như mong đợi
5. Kiểm tra nhật ký ứng dụng để tìm bất kỳ lỗi xác thực nào
6. Bật tính năng ghi nhật ký chi tiết tiêu đề yêu cầu OpenID bằng cách đặt DEBUG_OPENID_REQUESTS=true trong các biến môi trường của bạn để xem các tiêu đề yêu cầu bên cạnh các URL (với dữ liệu nhạy cảm được ẩn đi).