Kimlik doğrulama ve oturumlar

Cluster ERP kiracı kullanıcılarını kullanıcı adı veya şirket e-postası ve parola ile içeri alır, ardından kısa ömürlü bir erişim belirteci ve dönen bir yenileme belirteci verir. Web istemcisi iki belirteci de HttpOnly çerez olarak alır; masaüstü istemcisi ve betikler yanıt gövdesinde alır ve Bearer başlığı gönderir. Bu sayfa modules/auth/login/routes.py içindeki giriş uçlarını, modules/auth/jwt_utils.py içindeki belirteç yardımcılarını, modules/auth/session_cookies.py içindeki çerez taşımayı, modules/auth/password.py içindeki parola özetlemeyi, auth_token_blacklist ile iptali ve modules/auth/auth_cache.py içindeki izin belleğini açıklar. Operatör konsolunun kendi girişi vardır; bkz. operatör konsolu.

Kısaca¶

• Parolalar argon2.PasswordHasher ile Argon2 olarak özetlenir; parametreleri eskimiş bir özet yeniden hesaplanır (src/cluster_erp/modules/auth/password.py:3-21, src/cluster_erp/modules/auth/users/services.py:298-308).
• Erişim ve yenileme belirteçleri secret_key ayarıyla imzalanır; her biri benzersiz bir jti ve verify_token tarafından denetlenen bir type iddiası taşır (src/cluster_erp/modules/auth/jwt_utils.py:10-60, src/cluster_erp/modules/auth/jwt_utils.py:80-91).
• Web istemcisi çerez taşımayı X-Token-Transport başlığıyla ister; çerezle gelen yazma istekleri ayrıca X-Requested-With başlığını taşımalıdır (src/cluster_erp/modules/auth/session_cookies.py:31-39, src/cluster_erp/modules/auth/session_cookies.py:112-121).
• Her yenileme sunulan yenileme belirtecini harcar ve yeni bir çift verir; oturum sonu girişte sabitlenir ve döndürmede korunur (src/cluster_erp/modules/auth/login/routes.py:283-354).
• Çıkış, parola değişikliği ve anonimleştirme last_logout_at damgasını basar; bu, daha önce verilen her belirteci geçersiz kılar (src/cluster_erp/modules/auth/login/routes.py:423-424, src/cluster_erp/modules/auth/users/services.py:273-276, src/cluster_erp/modules/auth/privacy_handlers.py:96, src/cluster_erp/modules/auth/guards.py:153-165).

Nasıl çalışır¶

Giriş ve yenileme akışı¶

Dizi bir web girişini, sonraki bir isteği ve bir yenilemeyi gösterir.

sequenceDiagram
 participant C as web istemcisi
 participant L as giriş ucu
 participant U as UserService
 participant G as get_current_user
 participant R as yenileme ucu
 C->>L: X-Token-Transport ile POST /api/v1/auth/login
 L->>L: _check_attempt_budget
 L->>U: get_by_identifier, authenticate
 U-->>L: AuthUser veya None
 L-->>C: kullanıcı ve izinler, belirteçler HttpOnly çerezde
 C->>G: erişim çerezi ve X-Requested-With ile istek
 G->>G: verify_token, jti kara listesi, last_logout_at
 C->>R: yenileme çereziyle POST /api/v1/auth/refresh
 R->>R: eski jti harcanır, last_logout_at denetlenir
 R-->>C: yeni erişim ve yenileme çerezleri

Düz anlatımla:

1. Giriş ucu önce istemci adresi ve kullanıcı adı çifti için hatalı deneme bütçesini denetler (src/cluster_erp/modules/auth/login/routes.py:129-131).
2. get_by_identifier kullanıcı adını çözer. Eşleşme yoksa ve tanımlayıcı @ içeriyorsa önce şirket e-postasını, sonra @ öncesindeki kısmı kullanıcı adı olarak dener (src/cluster_erp/modules/auth/users/services.py:92-119).
3. Kilitli bir hesap parola denetlenmeden reddedilir (src/cluster_erp/modules/auth/login/routes.py:135-147).
4. authenticate pasif kullanıcıları reddeder, parolayı doğrular ve gerekirse yeniden özetler (src/cluster_erp/modules/auth/users/services.py:298-308).
5. Başarıda uç hata sayacını sıfırlar, last_login_at damgasını en çok dakikada bir basar ve rol ve izin kodlarını yükler (src/cluster_erp/modules/auth/login/routes.py:181-201).
6. Belirteçleri verir. Çok kiracılı kipte iki belirteç de istek için çözülen kiracı anahtarını taşır (src/cluster_erp/modules/auth/login/routes.py:203-228).
7. Çerez istemcisi gövdede boş belirteç alanları, çerezlerde belirteçleri alır; diğer istemciler belirteçleri gövdede alır (src/cluster_erp/modules/auth/login/routes.py:230-257).
8. Korunan her istek get_current_user çalıştırır. Kimlik bilgisini okur, CSRF kuralını uygular, erişim belirtecini doğrular, jti ister, kara listeyi denetler, canlı kullanıcıyı rolleriyle yükler ve iat değerini last_logout_at ile karşılaştırır (src/cluster_erp/modules/auth/guards.py:85-167).
9. Yenileme ucu yenileme belirtecini doğrular, jti değerini kara listeye ekler, kısa bir tolerans penceresinden sonra ikinci kullanımı reddeder, son çıkıştan önce verilmiş belirteçleri reddeder ve aynı mutlak oturum sonuyla yeni bir çift verir (src/cluster_erp/modules/auth/login/routes.py:260-370).

Belirteç içeriği¶

read_tenant_claim imzası doğrulanmış bir belirtecin kiracı iddiasını okur ve süre dolumunu yok sayar. Yalnızca isteği kiracı veritabanına yönlendirir; kimlik doğrulama yine verify_token ile çalışır (src/cluster_erp/modules/auth/jwt_utils.py:63-77). Bkz. çok kiracılılık.

Çerez taşıma¶

set_session_cookies iki çerez yazar. İkisi de HttpOnly, SameSite=Strict ve HTTPS üzerinde Secure olur. Erişim çerezi / yolunu kullanır ve HTTPS üzerinde __Host- önekini alır; yenileme çerezi /api/v1/auth yoluyla sınırlıdır (src/cluster_erp/modules/auth/session_cookies.py:46-54, src/cluster_erp/modules/auth/session_cookies.py:124-153). "Beni hatırla" seçilmezse (Bu cihazda oturumum açık kalsın, webapp/i18n/tr.json anahtarı auth.remember_me) çerezler Max-Age taşımaz ve yenileme zinciri jwt_session_hours sonunda biter (src/cluster_erp/modules/auth/login/routes.py:215-220). Biçimi doğru bir Bearer başlığı erişim çerezinden önce gelir (src/cluster_erp/modules/auth/session_cookies.py:63-75).

İptal ve çıkış¶

• POST /api/v1/auth/logout erişim belirtecinin jti değerini, çerez oturumunda ayrıca yenileme belirtecinin jti değerini kara listeye ekler. İki çerezi siler ve last_logout_at damgasını basar (src/cluster_erp/modules/auth/login/routes.py:373-431).
• Kara liste tablosu auth_token_blacklist, token_jti (benzersiz) ve expires_at sütunlarını tutar (src/cluster_erp/modules/auth/token_blacklist/models.py:11-23). Günlük kayıt saklama geçişi süresi dolmuş satırları siler (src/cluster_erp/server/app.py:1168-1192, src/cluster_erp/server/app.py:1281).
• POST /api/v1/auth/users/me/change-password mevcut parolayı doğrular ve last_logout_at damgasını basar (src/cluster_erp/modules/auth/users/routes.py:162-174, src/cluster_erp/modules/auth/users/services.py:255-278).

Hatalı denemeler¶

Parola tahminini iki mekanizma sınırlar:

• İstemci adresi ve kullanıcı adı başına bir hata bütçesi. Her işçi sürecinin aynı bütçeyi görmesi için auth_login_budget tablosunda sayılır. Sınır login_rate_limit_per_minute ayarıdır; aşılınca uç AUTH_TOO_MANY_ATTEMPTS ile HTTP 429 döner (src/cluster_erp/modules/auth/login/routes.py:53-120). Başarılı girişler bütçeden düşmez (src/cluster_erp/modules/auth/login/routes.py:56-58).
• Belirli sayıda ardışık hatadan sonra belirli bir süre için hesap kilidi (_MAX_FAILED_ATTEMPTS, _LOCKOUT_MINUTES); durum failed_login_count ve locked_until sütunlarında tutulur (src/cluster_erp/modules/auth/login/routes.py:48-49, src/cluster_erp/modules/auth/login/routes.py:150-168, src/cluster_erp/modules/auth/users/models.py:67-76).

İzin belleği¶

auth_cache her kullanıcının izin kodlarını ve her iznin etkin politikalarını süreç belleğinde auth_cache_seconds saniye boyunca, veritabanı adına göre anahtarlanmış olarak tutar (src/cluster_erp/modules/auth/auth_cache.py:41-55, src/cluster_erp/modules/auth/auth_cache.py:97-135, src/cluster_erp/server/app.py:1310). Veritabanı tetikleyicilerinin ilerlettiği core_cache_versions sürüm damgası, bir işçideki değişikliği sonraki istekte tüm işçilere görünür kılar (src/cluster_erp/modules/auth/auth_cache.py:63-89). Bir after_flush dinleyicisi roller, atamalar, kullanıcı rolleri, izinler veya politikalar değişince belleği temizler (src/cluster_erp/modules/auth/auth_cache.py:153-184). Kullanıcı satırının kendisi önbelleğe alınmaz (src/cluster_erp/modules/auth/auth_cache.py:13-14).

İlk yönetici¶

Açılışta _seed_permissions_from_metadata önce admin rolünü güvenceye alır, sonra yalnızca veritabanında hiç kullanıcı yoksa bir yönetici yaratan ensure_bootstrap_admin çağrılır (src/cluster_erp/server/app.py:862-900, src/cluster_erp/modules/auth/users/services.py:412-453). Hesap adını, e-postasını ve parolasını bootstrap_admin_username, bootstrap_admin_email ve bootstrap_admin_password veya bootstrap_admin_password_hash ayarlarından alır (src/cluster_erp/config/settings.py:195-201). Parola yapılandırılmamışsa rastgele bir parola üretilir ve bootstrap_password_file ile adlandırılan, yalnızca sahibinin okuyabildiği bir dosyaya yazılır; günlükte yalnızca dosya yolu yer alır (src/cluster_erp/server/app.py:881, src/cluster_erp/server/app.py:914-923, src/cluster_erp/server/app.py:591-609). assign_admin_to_unassigned yalnızca etkin bir yönetici yokken rolsüz kullanıcılara admin rolünü verir (src/cluster_erp/modules/auth/users/services.py:455-499); tests/test_admin_bootstrap.py bunu sabitler.

Neden böyle kurulmuştur¶

• session_cookies.py modül açıklaması çerez taşımanın gerekçesini verir: hiçbir tarayıcı deposu belirteci enjekte edilmiş betikten korumaz, bu yüzden web istemcisi belirteci hiç görmez; özel başlık SameSite=Strict yanında ikinci bir CSRF engeli ekler (src/cluster_erp/modules/auth/session_cookies.py:1-20).
• Döndürme yorumu, yeniden kullanım tolerans penceresinin aynı kökenden iki çerçevenin aynı anda yenilemesine izin verdiğini söyler (src/cluster_erp/modules/auth/login/routes.py:283-286). Mutlak oturum sonu döndürmenin oturumu uzatmasını engeller (src/cluster_erp/modules/auth/jwt_utils.py:41-45).
• Hata bütçesi veritabanında durur, çünkü süreç içi bir sayaç her işçiye ayrı bir bütçe veriyordu (src/cluster_erp/modules/auth/login/routes.py:53-59).
• Hatalı deneme sayacı hata yanıtından önce işlenir (commit), çünkü oturum bağımlılığı herhangi bir istisnada geri alır (src/cluster_erp/modules/auth/login/routes.py:162-168).

Kurallar ve sınırlar¶

• Diğer modüller auth modülünden yalnızca modules/auth/guards.py dosyasını kullanır; yorum bu sınırı koruyan test olarak tests/test_architecture_boundaries.py dosyasını adlandırır (src/cluster_erp/modules/auth/guards.py:22-27).
• Değişiklik geçmişindeki işlemi yapan, oturum bağımlılığında _resolve_actor_id tarafından aynı erişim belirtecinden yeniden okunur (src/cluster_erp/server/dependencies.py:82-101). Bkz. veritabanı ve oturumlar.
• Belirteç ömürleri, oturum uzunluğu, yeniden kullanım tolerans penceresi, hata bütçesi ve bellek ömrü ayardır: jwt_access_expire_minutes, jwt_refresh_expire_days, jwt_session_hours, jwt_refresh_reuse_grace_seconds, login_rate_limit_per_minute ve auth_cache_seconds (src/cluster_erp/config/settings.py:307-332). Türleri ve varsayılanları ayarlar başvurusu sayfasındadır.

Diğer parçalarla etkileşim¶

• auth modülü diğer modüller için EventBus üzerinde GetUserById ve GetUserPermissions sorgularını yanıtlar (src/cluster_erp/modules/auth/module.py:81-82, src/cluster_erp/modules/auth/module.py:110-144).
• Çok kiracılı kipte oturum bağımlılığı kiracıyı giriş ucu çalışmadan önce çözer ve uç kiracı anahtarını iki belirtece de basar (src/cluster_erp/server/dependencies.py:104-157, src/cluster_erp/modules/auth/login/routes.py:203-213).
• Girişin web istemcisi tarafı açılış, oturum ve API sayfasında belgelenir.

Sınırlar ve açık noktalar¶

• Bu commit'teki kodda kiracı kullanıcılarının ikinci doğrulama adımı yoktur: verify_totp yalnızca src/cluster_erp/server/operators.py:162 içinden çağrılır. Bkz. ikinci doğrulama adımı ve gizli değer saklama.
• Uzunluk dışında bir parola politikası koddan belirlenemedi. Şemalar 8 ile 128 karakter arası uzunluk koyar; password_min_length ayarını (src/cluster_erp/config/settings.py:327) bu commit'te hiçbir kod okumaz (src/cluster_erp/modules/auth/users/schemas.py:12, src/cluster_erp/modules/auth/users/schemas.py:54-60).

Tanıtılan terimler¶

İlgili sayfalar¶

• Kimlik, erişim, kiracılık, gizlilik ve lisans
• Roller ve izinler
• Çok kiracılılık
• Auth modülü
• API kimlik doğrulama ve başlıklar
• Ayarlar başvurusu

92f8051 numaralı commit ile 2026-11-13 tarihinde doğrulandı.