Auth0

Bu kılavuz, LibreChat için Auth0'yu OpenID Connect sağlayıcısı olarak yapılandırma sürecinde size yol gösterir.

Genel Bakış

Auth0, LibreChat için bir OpenID Connect sağlayıcısı olarak kullanılabilir. Auth0'ı token yeniden kullanımı etkin (OPENID_REUSE_TOKENS=true) şekilde kullanırken, kimlik doğrulama sorunlarını önlemek için OPENID_AUDIENCE ortam değişkenini yapılandırmanız gerekir.

Ön Koşullar

• Aktif bir kiracıya (tenant) sahip bir Auth0 hesabı
• Auth0'da uygulamalar ve API'ler oluşturmak için yönetici erişimi
• LibreChat örneği yapılandırma için hazır

Yapılandırma Adımları

Adım 1: Bir Auth0 Uygulaması Oluşturun

1. Auth0 Dashboard → Applications → Applications kısmına gidin
2. "Create Application" öğesine tıklayın
3. Uygulamayı yapılandırın:
   • Ad: LibreChat (veya tercih ettiğiniz ad)
   • Uygulama Türü: "Single Page Application" seçeneğini seçin
4. "Create" düğmesine tıklayın

Adım 2: Uygulama Ayarlarını Yapılandırın

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

1. Uygulamanızın Settings sekmesinde:
2. İzin Verilen Geri Çağırma URL'lerini (Allowed Callback URLs) ayarlayın:

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

   (Test etmek için ngrok URL'nizi veya üretim HTTPS URL'nizi kullanın)
3. İzin Verilen Çıkış URL'lerini ayarlayın (oturum sonlandırma kullanılıyorsa):

   https://your-domain.ngrok.io

4. Allowed Web Origins ayarını yapın:

   https://your-domain.ngrok.io

5. Değişiklikleri kaydet

Adım 3: Bir Auth0 API Oluşturun (Token Yeniden Kullanımı İçin Gereklidir)

1. Auth0 Dashboard'a gidin → Applications → APIs
2. "API Oluştur"a tıklayın
3. API'yi yapılandırın:
   • Ad: LibreChat API (veya tercih ettiğiniz ad)
   • Tanımlayıcı: https://api.librechat.ai (veya tercih ettiğiniz tanımlayıcı)
     • Not: Bu sadece benzersiz bir tanımlayıcıdır, gerçek bir URL değildir. Erişilebilir olması gerekmez.
     • Yaygın modeller: https://api.yourdomain.com, https://librechat.yourdomain.com vb.
   • İmzalama Algoritması: RS256 (önerilen)
4. "Create" (Oluştur) düğmesine tıklayın

Adım 4: Çevrimdışı Erişimi Yapılandırın

1. API Ayarlarınıza gidin → Erişim Ayarları
2. "Çevrimdışı Erişime İzin Ver" seçeneğini etkinleştirin
3. Değişiklikleri kaydet

Adım 5: Yapılandırma Değerlerini Toplayın

Auth0 Uygulamanızın Basic Information bölümünde şunları bulacaksınız:

• Domain: dev-example.us.auth0.com olarak görünür (https:// ön ekini eklemeniz gerekecektir)
• Client ID: Uzun bir alfanümerik dize
• Client Secret: Varsayılan olarak gizlidir (göstermek için tıklayın)

Adım 6: LibreChat Ortam Değişkenlerini Yapılandırın

.env dosyanıza aşağıdaki ortam değişkenlerini ekleyin:

# 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

OPENID_AUDIENCE'ı Anlamak

Sorun

Auth0'yu OPENID_REUSE_TOKENS=true ile kullanırken:

• Auth0 varsayılan olarak opak erişim belirteçleri (JWE formatı) döndürür
• LibreChat, doğrulanabilir imzalı JWT token'ları (JWS formatında) bekler
• Uygun yapılandırma olmadan, bu uyumsuzluk kimlik doğrulama hatalarına ve sonsuz yenileme döngülerine neden olur

Çözüm

OPENID_AUDIENCE ortam değişkeni:

• Auth0 API tanımlayıcınız olarak ayarlanmalıdır (3. Adımda oluşturulmuştur)
• Auth0'nun opak belirteçler yerine imzalı JWT erişim belirteçleri vermesini zorunlu kılar
• LibreChat'in Auth0'nun JWKS endpoint'ini kullanarak token'ları doğrulamasına olanak tanır
• JWT doğrulaması için virgülle ayrılmış hedef kitleler içerebilir; Auth0 yetkilendirme istekleri boş olmayan ilk değeri kullanır

Nasıl Çalışır

OPENID_AUDIENCE yapılandırıldığında:

1. LibreChat, yetkilendirme isteklerine audience parametresini dahil eder ve virgülle ayrılmış birden fazla audience yapılandırıldığında boş olmayan ilk değeri kullanır.
2. Auth0, hedef kitleyi kayıtlı bir API olarak tanır
3. Auth0, doğrulanabilen JWT erişim belirteçleri (access tokens) yayınlar
4. LibreChat, belirteçleri (tokens) başarıyla doğrular ve kimlik doğrulama düzgün bir şekilde çalışır

Ortam Değişkeni Referansı

Sorun Giderme

Sonsuz Yenileme Döngüsü

Belirtiler: "Continue with OpenID" seçeneğine tıkladıktan sonra sayfa sürekli olarak yeniden yükleniyor

Çözüm:

1. OPENID_AUDIENCE değerinin Auth0 API tanımlayıcınıza ayarlandığından emin olun
2. API'nin Auth0 içinde oluşturulduğunu ve çevrimdışı erişimin (offline access) etkinleştirildiğini doğrulayın
3. audience değerinin tam olarak eşleştiğini kontrol edin

Geçersiz Belirteç (Token) Hataları

Belirtiler: Kimlik doğrulama, token doğrulama hatalarıyla başarısız oluyor

Çözüm:

1. Hata ayıklama günlüğünü etkinleştir: DEBUG_OPENID_REQUESTS=true
2. Auth0'nun (opak belirteçler değil) JWT belirteçleri döndürdüğünü doğrulayın
3. JWKS endpoint'inin erişilebilir olduğunu kontrol edin

Eksik Yenileme Belirteci (Refresh Token)

Belirtiler: Kimlik doğrulama yanıtında yenileme belirteci (refresh token) yok

Çözüm:

1. OPENID_SCOPE içinde offline_access ifadesinin bulunduğundan emin olun
2. Auth0 API ayarlarınızda "Allow Offline Access" seçeneğinin etkinleştirildiğini doğrulayın

En İyi Uygulamalar

1. Her zaman HTTPS kullanın - Auth0, tüm geri çağırma (callback) URL'leri için HTTPS gerektirir
2. Yerel olarak test etme - localhost'a HTTPS tünelleri oluşturmak için ngrok veya benzeri hizmetleri kullanın
3. Oturum gizli anahtarınızı güvenceye alın - OPENID_SESSION_SECRET için güçlü ve rastgele bir değer kullanın
4. PKCE'yi Etkinleştir - Gelişmiş güvenlik için OPENID_USE_PKCE=true olarak ayarlayın
5. Geri çağırma (callback) URL'lerini kısıtlayın - Auth0 ayarlarında yalnızca kendi gerçek alan adınıza izin verin
6. Günlükleri izle - Kurulum sırasında DEBUG_OPENID_REQUESTS=true kullanın
7. API Tanımlayıcısı - Bunun sadece bir tanımlayıcı olduğunu, var olması gereken gerçek bir endpoint olmadığını unutmayın

Ek Kaynaklar

• Auth0 Belgeleri
• Auth0 Erişim Jetonları
• LibreChat OpenID Belirteç Yeniden Kullanımı