Penggunaan Kembali Token OpenID Connect

LibreChat mendukung penggunaan kembali token akses dan refresh yang diterbitkan oleh penyedia OpenID Connect Anda (seperti Azure Entra ID atau Auth0) untuk mengelola status autentikasi pengguna. Saat fitur ini aktif, token refresh yang diberikan kepada pengguna sebagai cookie diterbitkan oleh penyedia OpenID Anda alih-alih LibreChat, yang memungkinkan server LibreChat untuk menyegarkannya dan meminta token akses dari penyedia Anda.

Prasyarat

• Penyedia OpenID Connect yang telah dikonfigurasi (seperti Azure Entra ID, Auth0, dll.)
• Pengaturan dasar OpenID Connect telah selesai

Langkah-langkah Konfigurasi

1. Atur OPENID_REUSE_TOKENS=true di dalam variabel lingkungan Anda.

Konfigurasi Spesifik Provider

Konfigurasi Auth0

Untuk Auth0, Anda perlu:

1. Buat API di Auth0 (diperlukan untuk token akses JWT):

   • Buka Auth0 Dashboard → Applications → APIs
   • Klik "Create API"
   • Tetapkan Identifier (contoh: https://api.librechat.com)
   • Aktifkan "Allow Offline Access" di pengaturan API

2. Atur variabel lingkungan yang diperlukan:

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

Untuk konfigurasi Auth0 yang mendetail, lihat: Auth0 OpenID Connect Configuration

Konfigurasi Azure Entra ID

2. Konfigurasikan penyedia OpenID Anda (menggunakan Azure Entra ID sebagai contoh):
   • Buka Azure Portal dan navigasikan ke pendaftaran aplikasi Anda
   • Klik "Expose API" di menu sebelah kiri
   • Klik "Add" di samping "Application ID URI"
   • Masukkan API URI Anda (contoh: "api://librechat") dan simpan

3. Buat cakupan API:
   • Di bagian "Expose API", klik "Add a scope"
   • Konfigurasikan cakupan dengan izin yang sesuai
   • Simpan konfigurasi cakupan

4. Konfigurasikan izin API:
   • Buka "API permissions" di menu sebelah kiri
   • Klik "Add a permission"
   • Di bawah "APIs my organization uses", cari aplikasi Anda
   • Pilih "Delegated permissions" dan pilih cakupan yang sesuai (contohnya, "access_user")

5. Atur scope yang diperlukan di lingkungan Anda:

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

   Catatan: Scope offline_access diperlukan untuk mendapatkan refresh token agar dapat digunakan kembali.

6. Berikan persetujuan admin:

   • Buka Enterprise Applications di Azure Portal
   • Temukan aplikasi LibreChat Anda
   • Navigasikan ke Security > Permissions
   • Klik "Grant admin consent"

7. Terima izin yang diminta di dalam popup

8. Bersihkan cache LibreChat dan mulai ulang layanan tersebut.

Environment Variables

# 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

Opsi Konfigurasi Tambahan

• OPENID_AUDIENCE: Nilai audience untuk validasi JWT dan permintaan otorisasi. Diperlukan untuk Auth0 agar menerima token akses JWT alih-alih token buram (opaque tokens). Nilai yang dipisahkan koma diterima untuk validasi JWT; permintaan otorisasi menggunakan nilai pertama yang tidak kosong.
• OPENID_REUSE_MAX_SESSION_AGE_MS: Usia maksimum token sesi OpenID yang digunakan kembali sebelum LibreChat memaksa penyegaran IdP (default: 900000 ms / 15 menit). Menerima ekspresi aritmatika seperti 60 * 60 * 24 * 1000. Tingkatkan nilainya mendekati masa pakai access-token IdP Anda jika penyedia Anda mencabut access token sebelumnya setiap kali dilakukan penyegaran.
• OPENID_JWKS_URL_CACHE_ENABLED: Mengaktifkan caching hasil verifikasi kunci penandatanganan untuk mencegah permintaan HTTP yang berlebihan ke endpoint JWKS
• OPENID_JWKS_URL_CACHE_TIME: Durasi cache dalam milidetik (default: 600000 ms / 10 menit)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Mengaktifkan alur on-behalf-of untuk info pengguna (khusus Azure)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: Scope untuk info pengguna dalam alur on-behalf-of (khusus Azure)
• OPENID_USE_END_SESSION_ENDPOINT: Mengaktifkan penggunaan endpoint end session untuk logout
• OPENID_MAX_LOGOUT_URL_LENGTH: Panjang URL maksimum sebelum menggunakan logout_hint alih-alih id_token_hint untuk mencegah kesalahan URI terlalu panjang (default: 2000)

Pertimbangan Keamanan

• Pastikan penyimpanan dan penanganan token dilakukan dengan benar
• Implementasikan mekanisme penyegaran token yang sesuai
• Pantau penggunaan token dan terapkan pembatasan laju (rate limiting) jika diperlukan
• Lakukan rotasi client secrets secara berkala
• Gunakan pengaturan cookie yang aman untuk penyimpanan token

Pemecahan Masalah

Jika Anda mengalami masalah dengan penggunaan ulang token:

1. Verifikasi semua scope yang diperlukan telah dikonfigurasi dengan benar
2. Pastikan persetujuan admin telah diberikan
3. Pastikan izin API telah diatur dengan benar
4. Verifikasi bahwa cache token berfungsi sebagaimana mestinya
5. Periksa log aplikasi untuk melihat apakah ada kesalahan autentikasi
6. Aktifkan pencatatan header permintaan OpenID secara mendetail dengan mengatur DEBUG_OPENID_REQUESTS=true di variabel lingkungan Anda untuk melihat header permintaan selain URL (dengan data sensitif yang disamarkan).