Auth0

Panduan ini memandu Anda dalam mengonfigurasi Auth0 sebagai penyedia OpenID Connect untuk LibreChat.

Ikhtisar

Auth0 dapat digunakan sebagai penyedia OpenID Connect untuk LibreChat. Saat menggunakan Auth0 dengan penggunaan ulang token diaktifkan (OPENID_REUSE_TOKENS=true), Anda harus mengonfigurasi variabel lingkungan OPENID_AUDIENCE untuk mencegah masalah autentikasi.

Prasyarat

• Akun Auth0 dengan tenant yang aktif
• Akses admin untuk membuat aplikasi dan API di Auth0
• Instans LibreChat siap untuk dikonfigurasi

Langkah-langkah Konfigurasi

Langkah 1: Buat Aplikasi Auth0

1. Buka Auth0 Dashboard → Applications → Applications
2. Klik "Create Application"
3. Konfigurasikan aplikasi:
   • Nama: LibreChat (atau nama pilihan Anda)
   • Application Type: Pilih "Single Page Application"
4. Klik "Create"

Langkah 2: Konfigurasi Pengaturan Aplikasi

ngrok http 3080
# This will give you a URL like: https://abc123.ngrok.io

1. Di tab Settings aplikasi Anda:
2. Atur Allowed Callback URLs:

   https://your-domain.ngrok.io/oauth/openid/callback

   (Gunakan URL ngrok Anda untuk pengujian, atau URL HTTPS produksi Anda)
3. Atur Allowed Logout URLs (jika menggunakan end session):

   https://your-domain.ngrok.io

4. Atur Allowed Web Origins:

   https://your-domain.ngrok.io

5. Simpan perubahan

Langkah 3: Buat API Auth0 (Diperlukan untuk Penggunaan Ulang Token)

1. Buka Dashboard Auth0 → Applications → APIs
2. Klik "Create API"
3. Konfigurasi API:
   • Nama: LibreChat API (atau nama pilihan Anda)
   • Identifier: https://api.librechat.ai (atau identifier pilihan Anda)
     • Catatan: Ini hanyalah pengenal unik, bukan URL yang sebenarnya. Ini tidak perlu dapat diakses.
     • Pola umum: https://api.yourdomain.com, https://librechat.yourdomain.com, dll.
   • Algoritma Penandatanganan: RS256 (direkomendasikan)
4. Klik "Create"

Langkah 4: Konfigurasi Akses Offline

1. Buka Pengaturan API Anda → Pengaturan Akses
2. Aktifkan "Allow Offline Access"
3. Simpan perubahan

Langkah 5: Kumpulkan Nilai Konfigurasi

Di bagian Basic Information pada Aplikasi Auth0 Anda, Anda akan menemukan:

• Domain: Ditampilkan sebagai dev-example.us.auth0.com (Anda perlu menambahkan awalan https://)
• Client ID: String alfanumerik yang panjang
• Client Secret: Disembunyikan secara default (klik untuk menampilkan)

Langkah 6: Konfigurasi Variabel Lingkungan LibreChat

Tambahkan variabel lingkungan berikut ke file .env Anda:

# OpenID Connect Configuration
# Domain from Basic Information (add https:// prefix)
OPENID_ISSUER=https://dev-abc123.us.auth0.com

# Client ID from Basic Information
OPENID_CLIENT_ID=your_long_alphanumeric_client_id

# Client Secret from Basic Information (click to reveal)
OPENID_CLIENT_SECRET=your_client_secret_from_basic_information

# Callback URL (must match what's configured in Auth0)
OPENID_CALLBACK_URL=/oauth/openid/callback

# Token Configuration
OPENID_REUSE_TOKENS=true
OPENID_SCOPE=openid profile email offline_access

# IMPORTANT: Your Auth0 API identifier (from Step 3)
OPENID_AUDIENCE=https://api.librechat.ai

# Security Settings (recommended)
OPENID_USE_PKCE=true

# Session Configuration (generate a secure random string)
OPENID_SESSION_SECRET=your-secure-session-secret-32-chars-or-more

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

# Optional: Custom button appearance
OPENID_BUTTON_LABEL=Continue with Auth0
# OPENID_IMAGE_URL=https://path-to-auth0-logo.png

# If using ngrok for testing, also update:
# DOMAIN_CLIENT=https://your-domain.ngrok.io
# DOMAIN_SERVER=https://your-domain.ngrok.io

Memahami OPENID_AUDIENCE

Masalahnya

Saat menggunakan Auth0 dengan OPENID_REUSE_TOKENS=true:

• Auth0 secara default mengembalikan opaque access tokens (format JWE)
• LibreChat mengharapkan signed JWT tokens (format JWS) yang dapat divalidasi
• Tanpa konfigurasi yang tepat, ketidakcocokan ini menyebabkan kegagalan autentikasi dan perulangan penyegaran (refresh loop) tanpa henti.

Solusinya

Variabel lingkungan OPENID_AUDIENCE:

• Harus diatur ke identifier API Auth0 Anda (dibuat pada Langkah 3)
• Memaksa Auth0 untuk menerbitkan token akses JWT yang ditandatangani alih-alih token buram (opaque tokens)
• Memungkinkan LibreChat untuk memvalidasi token menggunakan endpoint JWKS milik Auth0
• Dapat berisi audiens yang dipisahkan koma untuk validasi JWT; permintaan otorisasi Auth0 menggunakan nilai non-kosong pertama

Cara Kerja

Ketika OPENID_AUDIENCE dikonfigurasi:

1. LibreChat menyertakan parameter audience dalam permintaan otorisasi, menggunakan nilai non-kosong pertama ketika beberapa audiens yang dipisahkan koma dikonfigurasi.
2. Auth0 mengenali audiens sebagai API yang terdaftar
3. Auth0 menerbitkan token akses JWT yang dapat divalidasi
4. LibreChat berhasil memvalidasi token dan autentikasi berfungsi dengan baik

Referensi Variabel Lingkungan

Pemecahan Masalah

Infinite Refresh Loop

Gejala: Halaman memuat ulang secara terus-menerus setelah mengeklik "Continue with OpenID"

Solusi:

1. Pastikan OPENID_AUDIENCE diatur ke pengidentifikasi API Auth0 Anda
2. Verifikasi bahwa API telah dibuat di Auth0 dan akses offline telah diaktifkan
3. Pastikan nilai audience cocok dengan tepat

Kesalahan Token Tidak Valid

Gejala: Autentikasi gagal dengan kesalahan validasi token

Solusi:

1. Aktifkan pencatatan debug: DEBUG_OPENID_REQUESTS=true
2. Verifikasi bahwa Auth0 mengembalikan token JWT (bukan token buram/opaque)
3. Periksa apakah endpoint JWKS dapat diakses

Token Refresh Hilang

Gejala: Tidak ada refresh token dalam respons autentikasi

Solusi:

1. Pastikan offline_access disertakan dalam OPENID_SCOPE
2. Pastikan "Allow Offline Access" diaktifkan di pengaturan API Auth0 Anda

Praktik Terbaik

1. Selalu gunakan HTTPS - Auth0 memerlukan HTTPS untuk semua URL callback
2. Menguji secara lokal - Gunakan ngrok atau layanan serupa untuk membuat tunnel HTTPS ke localhost
3. Amankan session secret Anda - Gunakan nilai acak yang kuat untuk OPENID_SESSION_SECRET
4. Aktifkan PKCE - Atur OPENID_USE_PKCE=true untuk keamanan yang ditingkatkan
5. Batasi URL callback - Hanya izinkan domain asli Anda di pengaturan Auth0
6. Monitor logs - Gunakan DEBUG_OPENID_REQUESTS=true selama pengaturan
7. API Identifier - Ingat bahwa ini hanyalah sebuah pengenal, bukan endpoint sebenarnya yang harus ada

Sumber Daya Tambahan

• Dokumentasi Auth0
• Token Akses Auth0
• Penggunaan Kembali Token OpenID LibreChat