OpenID Connect Belirteç Yeniden Kullanımı

LibreChat, kullanıcı kimlik doğrulama durumunu yönetmek için OpenID Connect sağlayıcınız (Azure Entra ID veya Auth0 gibi) tarafından verilen erişim ve yenileme belirteçlerinin (access and refresh tokens) yeniden kullanılmasını destekler. Bu özellik etkinleştirildiğinde, kullanıcıya çerez olarak iletilen yenileme belirteci, LibreChat yerine OpenID sağlayıcınız tarafından verilir; bu da LibreChat sunucularının bunu yenilemesine ve sağlayıcınızdan erişim belirteçleri talep etmesine olanak tanır.

Ön Koşullar

• Yapılandırılmış bir OpenID Connect sağlayıcısı (Azure Entra ID, Auth0 vb. gibi)
• Temel OpenID Connect kurulumu tamamlandı

Yapılandırma Adımları

1. OPENID_REUSE_TOKENS=true değerini ortam değişkenlerinize (environment variables) ekleyin.

Sağlayıcıya Özel Yapılandırma

Auth0 Yapılandırması

Auth0 için şunları yapmanız gerekir:

1. Auth0'da bir API oluşturun (JWT erişim belirteçleri için gereklidir):

   • Auth0 Dashboard → Applications → APIs kısmına gidin
   • "Create API" öğesine tıklayın
   • Bir Identifier (örneğin https://api.librechat.com) ayarlayın
   • API ayarlarında "Allow Offline Access" seçeneğini etkinleştirin

2. Gerekli ortam değişkenlerini ayarlayın:

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

Ayrıntılı Auth0 yapılandırması için bkz: Auth0 OpenID Connect Configuration

Azure Entra ID Yapılandırması

2. OpenID sağlayıcınızı yapılandırın (örnek olarak Azure Entra ID kullanarak):
   • Azure Portal'a gidin ve uygulama kaydınıza (app registration) gidin
   • Sol menüdeki "Expose API" seçeneğine tıklayın
   • "Application ID URI" ifadesinin yanındaki "Add" düğmesine tıklayın
   • API URI adresinizi girin (örneğin, "api://librechat") ve kaydedin

3. Bir API kapsamı oluşturun:
   • "Expose API" bölümünde, "Add a scope" seçeneğine tıklayın
   • Kapsamı uygun izinlerle yapılandırın
   • Kapsam yapılandırmasını kaydet

4. API izinlerini yapılandırın:
   • Sol menüdeki "API permissions" kısmına gidin
   • "Add a permission" öğesine tıklayın
   • "APIs my organization uses" altında uygulamanızı arayın
   • "Delegated permissions" seçeneğini belirleyin ve uygun kapsamı (örneğin, "access_user") seçin

5. Ortamınızda gerekli kapsamı (scope) ayarlayın:

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

   Not: Yeniden kullanım için bir yenileme belirteci (refresh token) elde etmek amacıyla offline_access kapsamı gereklidir.

6. Yönetici onayı verin:

   • Azure Portal'da Enterprise Applications (Kurumsal Uygulamalar) kısmına gidin
   • LibreChat uygulamanızı bulun
   • Güvenlik (Security) > İzinler (Permissions) kısmına gidin
   • "Grant admin consent" düğmesine tıklayın

7. Açılır pencerede istenen izinleri kabul edin

8. LibreChat önbelleğini temizleyin ve servisi yeniden başlatın.

Ortam Değişkenleri

# 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

Ek Yapılandırma Seçenekleri

• OPENID_AUDIENCE: JWT doğrulama ve yetkilendirme istekleri için hedef kitle (audience) değeri. Opak belirteçler (opaque tokens) yerine JWT erişim belirteçleri almak için Auth0 için gereklidir. JWT doğrulaması için virgülle ayrılmış değerler kabul edilir; yetkilendirme istekleri boş olmayan ilk değeri kullanır.
• OPENID_REUSE_MAX_SESSION_AGE_MS: LibreChat'in bir IdP yenilemesini zorunlu kılmasından önce yeniden kullanılan bir OpenID oturum belirtecinin sunulabileceği maksimum süre (varsayılan: 900000 ms / 15 dakika). 60 * 60 * 24 * 1000 gibi aritmetik ifadeleri kabul eder. Sağlayıcınız her yenilemede önceki erişim belirtecini iptal ediyorsa, bu değeri IdP erişim belirteci ömrünüze doğru artırın.
• OPENID_JWKS_URL_CACHE_ENABLED: JWKS endpoint'ine aşırı HTTP isteği gönderilmesini önlemek için imza anahtarı doğrulama sonuçlarının önbelleğe alınmasını sağlar
• OPENID_JWKS_URL_CACHE_TIME: Milisaniye cinsinden önbellek süresi (varsayılan: 600000 ms / 10 dakika)
• OPENID_ON_BEHALF_FLOW_FOR_USERINFO_REQUIRED: Kullanıcı bilgileri için on-behalf-of akışını etkinleştirir (Azure'a özeldir)
• OPENID_ON_BEHALF_FLOW_USERINFO_SCOPE: On-behalf-of akışında kullanıcı bilgisi için kapsam (Azure'a özel)
• OPENID_USE_END_SESSION_ENDPOINT: Çıkış yapmak için end session endpoint kullanımını etkinleştirir
• OPENID_MAX_LOGOUT_URL_LENGTH: URI çok uzun hatalarını önlemek için id_token_hint yerine logout_hint kullanılmadan önceki maksimum URL uzunluğu (varsayılan: 2000)

Güvenlik Hususları

• Düzgün token depolama ve işleme sağladığınızdan emin olun
• Uygun token yenileme mekanizmalarını uygulayın
• Token kullanımını izleyin ve gerekirse hız sınırlaması (rate limiting) uygulayın
• İstemci sırlarını düzenli olarak değiştirin
• Token depolaması için güvenli çerez ayarlarını kullanın

Sorun Giderme

Token yeniden kullanımıyla ilgili sorunlarla karşılaşırsanız:

1. Gerekli tüm kapsamların düzgün bir şekilde yapılandırıldığını doğrulayın
2. Yönetici onayının verildiğinden emin olun
3. API izinlerinin doğru şekilde ayarlandığından emin olun
4. Token önbelleğinin beklendiği gibi çalıştığını doğrulayın
5. Herhangi bir kimlik doğrulama hatası olup olmadığını görmek için uygulama günlüklerini kontrol edin
6. Ortam değişkenlerinizde DEBUG_OPENID_REQUESTS=true ayarını yaparak, URL'lere ek olarak istek başlıklarını (hassas veriler maskelenmiş şekilde) görmek için ayrıntılı OpenID istek başlığı günlüğünü etkinleştirin.