BuildingBlocks.Keycloak API’yi iki ayrı Keycloak realm’ından token kabul edecek şekilde yapılandırır: Vatandaş (citizen SPA) ve Personel (yönetim paneli). Tek AddKeycloak(...) çağrısı iki JwtBearer şeması kurar, claims transformation zincirini kaydeder ve ICurrentUserService ile aktif kullanıcı bağlamını sunar.
Geniş kapsamlı Keycloak konuları (realm yapısı, provisioning, ortamlar, sorun giderme) Keycloak grubundadır. Bu sayfa paketin kod tarafına odaklanır.
Yapılandırma — KeycloakOptions
appsettings.json’daki Keycloak bölümüyle bind edilir. İki alt bölüm vardır: Vatandas ve Personel, her ikisi de KeycloakSchemeOptions tipinde.
| Üye | Tip | Açıklama |
|---|---|---|
Vatandas | KeycloakSchemeOptions | Vatandaş SPA realm’ı (citizen) |
Personel | KeycloakSchemeOptions | Yönetim paneli realm’ı (staff) |
KeycloakSchemeOptions
| Üye | Tip | Açıklama |
|---|---|---|
BaseUrl | string | API’nin Keycloak’a ulaşacağı URL. JWKS metadata ve Authority bunun üzerinden hesaplanır |
PublicBaseUrl | string? | Browser’ın gördüğü URL — token iss claim’inde bu olabilir. Boşsa BaseUrl kabul edilir |
Realm | string | Keycloak realm adı (örn. diyanet-vatandas-dev-realm) |
ClientId | string | SPA’ın Keycloak client ID’si; audience (aud) doğrulaması bu değere göre yapılır |
RequireHttpsMetadata | bool | HTTPS metadata zorunluluğu (prod’da true) |
ValidateAudience | bool | aud claim’i doğrulanacak mı |
CookieName | string | Access token’ın saklandığı HTTP-only cookie adı |
Scopes | List<string> | OIDC scope’ları (varsayılan openid, profile, email) |
Authority | string (computed) | {BaseUrl}/realms/{Realm} |
Issuer | string (computed) | Authority ile aynı (internal issuer) |
PublicIssuer | string (computed) | {PublicBaseUrl}/realms/{Realm} — boşsa Issuer |
DiscoveryEndpoint | string (computed) | {Authority}/.well-known/openid-configuration |
TokenEndpoint | string (computed) | {Authority}/protocol/openid-connect/token |
JwksUri | string (computed) | {Authority}/protocol/openid-connect/certs |
KeycloakSchemeNames
[Authorize] attribute’larında kullanılan sabit şema adları:
| Sabit | Değer | Kullanım |
|---|---|---|
Vatandas | "VatandasScheme" | Sadece vatandaş token’ları |
Personel | "PersonelScheme" | Sadece personel token’ları |
Any | "VatandasScheme,PersonelScheme" | Her iki realm |
Default şema
Personel’dir (AddAuthentication(KeycloakSchemeNames.Personel)). Şema belirtmeyen [Authorize] attribute’ları Personel realm’ını kullanır; vatandaş endpoint’leri açıkça KeycloakSchemeNames.Vatandas belirtmelidir.Arayüzler
| Arayüz | İmza | Amaç |
|---|---|---|
ICurrentUserService | Guid? UserId, Guid? TenantId, Guid? BranchId, string? Email/Phone/FullName, IReadOnlyList<string> Roles/Permissions, bool IsAuthenticated | JWT claim’lerinden aktif kullanıcı bağlamı |
bool HasPermission(string), bool HasRole(string), bool IsInTenant(Guid) | İzin/rol/tenant kontrol kısayolları | |
IUserContextProvider | Task<UserContextData> GetAsync(string sub, CancellationToken) | sub üzerinden tenant + permission bağlamı (DB/cache) |
Task InvalidateAsync(string sub, CancellationToken) | Rol/permission değişiminde cache geçersizleştirme |
ICurrentUserService HTTP context tabanlı CurrentUserService ile implement edilir; UserId önce user_id, yoksa Keycloak sub claim’ini okur. IUserContextProvider varsayılan olarak no-op NullUserContextProvider’dir — Application katmanı kendi implementasyonunu services.AddScoped<IUserContextProvider, UserContextProvider>() ile kaydeder.
DI kaydı — AddKeycloak
ConfigureScheme her şemada şunları yapar:
MapInboundClaims = false—subclaim’inin korunması kritik (aksi haldeUserContextClaimsTransformationsubbulamaz, 403 üretir).ValidIssuers=[Issuer, PublicIssuer]— Docker dev’de internal (http://keycloak:8080) ile public (http://localhost:8080) issuer farklı olabilir.ValidAudiences=[ClientId, "account"].NameClaimType = "preferred_username",ClockSkew = 30s.OnMessageReceivedtoken kaynak önceliği: 1) cookie (CookieName) → 2)Authorization: Bearerheader → 3) query stringaccess_token(yalnızca/hubsve/filespath’lerinde — SignalR/FileServer için).
Yapılandırma anahtarları
Kullanım — çift realm
İlgili
Keycloak (genel)
Realm yapısı, provisioning, ortamlar, sorun giderme.
Authorization
Permission policy provider ve RBAC akışı.
JWT
Backoffice + OTPChallenge custom JWT şemaları.
OAuth
Google/Meta/Keycloak PKCE akışı.