OIDC Kimlik Sağlayıcı
"Project Owner" gibi "Kimlik Doğrulama Hizmetlerini Yönet" yetkisine sahip roller tarafından erişilebilir ve yönetilebilir.
Sağlayıcının salt-okunur detay (görüntüleme) ekranı, aşağıda anlatılan alanları bölümlere ayrılmış panellerde gösterir.
Sayfanın üst kısmındaki [<> Variable] butonu ile Issuer URL, Discovery URL, uç nokta ve İstemci ID gibi URL/istemci alanlarına dinamik değer seçilebilir; bu alanlar ${var}/#{var} söz dizimini backend'de çözer. Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Ne Zaman Kullanılır
OIDC Kimlik Sağlayıcı, Keycloak, Auth0, Azure AD, Okta gibi bir OpenID Connect/OAuth2 sağlayıcısını Apinizer'a kimlik kaynağı olarak bağlamak için kullanılır. Bir kez tanımlanan sağlayıcı, OIDC Kimlik Doğrulama politikasından veya diğer kimlik doğrulama politikalarının Identity/Role/Group Service seçiminden referans olarak kullanılabilir; böylece aynı sağlayıcı bilgisi (issuer, uç noktalar, istemci, doğrulama kuralları) tek bir yerde yönetilir.
Sağlayıcının seçilebildiği politikalar ve oradaki davranışı:
| Politika | Nerede | Davranış |
|---|---|---|
| OIDC Kimlik Doğrulama | Sağlayıcı referans modu | Sağlayıcının uç noktalarıyla tarayıcı oturumu (authorization code / implicit / hybrid) ve bearer doğrulaması. |
| JWT Kimlik Doğrulama | Identity Role Group → OIDC | PASSWORD grant: sağlayıcı sunulan token'ı doğruladıktan sonra politika kendi token'ını üretir. CLIENT_CREDENTIALS: politika token üretmez; sağlayıcının ürettiği token her istekte doğrulanır (JWKS / introspection), /auth/* 400 döner. |
| OAuth 2 Kimlik Doğrulama | Identity Role Group → OIDC | JWT ile aynı; opak token'lar introspection ile doğrulanır. |
| Basic Kimlik Doğrulama | Identity Role Group → OIDC, yalnızca API Anahtarını Bearer Token Olarak Kullan açıkken | Bearer değeri sağlayıcının ürettiği token olarak kabul edilir ve aynı şekilde doğrulanır. |
Keycloak'ın ürettiği client-credentials token'larında kimlik claim'i preferred_username = service-account-<clientId> gelir; Consumer'larınız client id ile adlandırıldıysa Kullanıcı Adı Claim Yolu alanını azp yapın.
Sağlayıcı Türü: Generic ve Keycloak
Sağlayıcı Türü alanı iki değer alabilir:
- Generic: Herhangi bir standart-uyumlu OIDC sağlayıcısı için discovery/JWKS tabanlı token doğrulamayı etkinleştirir. Kullanıcı/grup/rol senkronizasyonu bu türde kullanılmaz.
- Keycloak: Token doğrulamaya ek olarak, Keycloak'a özgü Admin API üzerinden kullanıcı/grup/rol senkronizasyonunu etkinleştirir.
Bu ayrımın nedeni şudur: token doğrulama (imza kontrolü, issuer/audience kontrolü, introspection) OIDC/OAuth2 standardının bir parçasıdır ve her sağlayıcıda aynı şekilde çalışır. Ancak kullanıcı listeleme hiçbir OAuth2/OIDC standardında tanımlı değildir — her sağlayıcının kendine özgü bir Admin API'si vardır. Bu sürümde yalnızca Keycloak'un Admin API'si desteklenir; bu yüzden senkronizasyon özelliği yalnızca Keycloak sağlayıcı türünde anlamlıdır.
Genel sekmesi
| Alan | Açıklama |
|---|---|
| Ad | Oluşturulan OIDC Kimlik Sağlayıcısı için ad bilgisidir. |
| Açıklama | Oluşturulan OIDC Kimlik Sağlayıcı ile ilgili yönetimi kolaylaştırmak için açıklama yazılabilir. |
| Sağlayıcı Türü (Vendor Type) | Generic veya Keycloak. Yukarıdaki Sağlayıcı Türü bölümüne bakınız. |
| Issuer URL | OIDC issuer (iss) adresidir. Discovery dokümanının adresini türetmek için de kullanılır. |
| Discovery URL | Varsayılan olarak {Issuer URL}/.well-known/openid-configuration adresi kullanılır; farklı bir adres gerekiyorsa burada geçersiz kılınabilir. |
| Endpointleri otomatik keşfet (Auto Discover) | Açıkken uç nokta alanları salt-okunur olur ve sağlayıcının discovery dokümanıyla senkron tutulur. Kapatılırsa Endpointler sekmesindeki alanlar elle girilir. |
Endpointler sekmesi
Token, introspection, userInfo, JWKS ve end-session uç noktaları bu sekmede yer alır.
| Alan | Açıklama |
|---|---|
| Token Endpoint | Token uç noktasıdır. |
| Introspection Endpoint | RFC 7662 introspection uç noktasıdır; Online/Hibrit doğrulama modunda kullanılır. |
| UserInfo Endpoint | Kullanıcı bilgisi uç noktasıdır. |
| JWKS Endpoint | İmza doğrulama anahtarlarının (JWKS) alındığı uç noktadır. |
| End-Session Endpoint | Oturum sonlandırma (logout) uç noktasıdır. |
Keşfet düğmesi, Issuer URL veya Discovery URL girildikten sonra sağlayıcının discovery dokümanını çeker ve boş bırakılmış uç nokta alanlarını doldurur; bu işlem kaydetmeden önce yapılır, herhangi bir veriyi kalıcı olarak değiştirmez. Endpointleri otomatik keşfet açıkken bu alanlar salt-okunurdur.
İstemci sekmesi
| Alan | Açıklama |
|---|---|
| İstemci ID (Client ID) | Sağlayıcı tarafında tanımlı OAuth/OIDC istemci kimliğidir. |
| İstemci Secret (Client Secret) | İstemci sırrıdır; maskeli gösterilir, göz simgesiyle görüntülenebilir ve kopyala düğmesiyle kopyalanabilir. Düzenleme sırasında alan boş bırakılırsa mevcut sır korunur (değiştirilmek istenmiyorsa dokunulmadan bırakılabilir). |
| İstemci Kimlik Doğrulama Yöntemi (Client Auth Method) | Token/introspection uç noktasına karşı istemci kimlik doğrulama yöntemidir: • İstemci Secret (Basic) — HTTP Basic header'da client_id:client_secret. • İstemci Secret (POST body) — form-body'de client_id + client_secret. • Private Key JWT — imzalı JWT assertion; client secret gerekmez. |
Doğrulama sekmesi
Doğrulama Modu
| Değer | Açıklama |
|---|---|
| Offline (yalnız imza) | Token imzası yerel JWKS ile doğrulanır; introspection uç noktasına gidilmez. Düşük gecikme sağlar; internet erişimi olmayan (air-gapped) kurulumlarda Statik JWKS kaynağıyla birlikte kullanılabilir. |
| Online (introspection) | Her istekte introspection uç noktasına sorulur. İptal edilmiş (revoke edilmiş) token'lara anında duyarlıdır; opak (imzasız/kapalı) token'ların doğrulanabildi ği tek yoldur. Yüksek gecikme getirir. |
| Hibrit | Önce yerel imza doğrulaması yapılır, ardından gerektiğinde introspection ile teyit edilir. |
JWKS Kaynağı
| Değer | Açıklama |
|---|---|
| Discovery (uzak JWKS) | JWKS Endpoint'ten (veya discovery dokümanından türetilen adresten) canlı olarak çekilir ve önbelleklenir. |
| Statik (yapıştırılan JWKS) | Statik JWKS (JSON) alanına elle girilmiş JWKS JSON'u kullanılır; discovery veya ağ erişimi gerekmez — internet erişimi olmayan (air-gapped) ortamlar için tercih edilir. |
| Alan | Açıklama |
|---|---|
| Statik JWKS (JSON) | JWKS Kaynağı Statik seçildiğinde görünür; anahtar materyalinin JSON içeriğidir. |
| Sertifika | Yalnızca JWKS kaynağı Statik iken ve anahtar materyali saklı bir Sertifika kaydından geliyorsa kullanılır. |
| İzin Verilen İmza Algoritmaları | Kabul edilecek imza algoritmalarının listesidir (RS256, RS384, RS512, ES256 vb.). |
| Maks. Saat Sapması (saniye) | Token zaman damgalarında (iat/exp/nbf) kabul edilen en fazla saat sapmasıdır. |
| Bağlantı Zaman Aşımı (saniye) | Sağlayıcıya bağlanırken beklenecek en fazla süredir. |
| Okuma Zaman Aşımı (saniye) | Sağlayıcıdan yanıt okunurken beklenecek en fazla süredir. |
Güvenlik Varsayılanları — Issuer ve Audience Doğrulama
Issuer Doğrula ve Audience Doğrula alanları varsayılan olarak açık gelir ve kapalı-durumda-güvenli (fail-closed) çalışır: doğrulama açıkken beklenen değer boş bırakılırsa kontrol atlanmaz, aksine token reddedilir. Kayıt sırasında da bu tutarsızlık engellenir.
| Alan | Açıklama |
|---|---|
| Issuer Doğrula (Validate Issuer) | Token'ın iss claim'ini beklenen issuer ile karşılaştırır. Varsayılan: açık. |
| Beklenen Issuer (Expected Issuer) | Boş bırakılırsa Issuer URL değeri kullanılır. |
| Audience Doğrula (Validate Audience) | Token'ın aud claim'ini beklenen audience listesiyle karşılaştırır. Varsayılan: açık. |
| Beklenen Audience (Expected Audience) | Kabul edilen audience değerlerinin listesidir; boş bırakılırsa İstemci ID değerine düşer. |
Audience doğrulaması varsayılan olarak kapatılamaz çünkü kapalı bırakıldığında, aynı realm'de kayıtlı başka bir uygulama için üretilmiş — doğru issuer'a sahip, imzası geçerli, süresi dolmamış — bir access token bu proxy tarafından da kabul edilir. Bu, klasik bir audience-confusion (cross-client token replay) açığıdır ve paylaşılan-realm Keycloak kurulumlarında sık görülen bir senaryodur.
Claim Eşlemesi sekmesi
| Alan | Açıklama |
|---|---|
| Kullanıcı Adı Claim (Username Claim Path) | Kullanıcı adının token içinde hangi claim'den okunacağını belirtir. Boş bırakılırsa varsayılan preferred_username kullanılır. |
| E-posta Claim | Kullanıcının e-posta adresinin okunacağı claim'dir. Varsayılan: email. |
| Ad Soyad Claim | Kullanıcının görünen adının okunacağı claim'dir. Varsayılan: name. |
| Roller Claim | Kullanıcının rollerinin token'dan okunacağı claim yoludur (Rol Kaynağı Token Claim veya İkisi Birden iken kullanılır). |
| Gruplar Claim | Kullanıcının gruplarının token'dan okunacağı claim yoludur. |
| Eşleşen Credential Zorunlu Olsun | Açıkken, imzası ve claim'leri geçerli olsa dahi eşleşen bir Kimlik Bilgisi kaydı bulunamayan bir token anonim kabul edilmek yerine reddedilir. Kapalıyken (kapatılması önerilmez) böyle bir token yine de kabul edilir; ancak isteğe hiçbir Kimlik Bilgisi bağlanmadığı için credential'a dayalı ACL, kota ve rate-limit kontrolleri uygulanmaz, ve Rol Kaynağı = Senkronize Credential iken rol listesi boş kalır. Varsayılan: açık. |
| Rol Kaynağı (Role Source) | Kimliği doğrulanan kullanıcının rol listesinin nereden üretileceğini belirler: • Token Claim — Roller/Gruplar Claim üzerinden doğrudan token'dan okunur. • Senkronize Credential — daha önce senkronize edilmiş Kimlik Bilgisi/Kurum üyeliğinden okunur (varsayılan). • İkisi Birden — ikisi birleştirilir. |
Eşleşen Credential Zorunlu Olsun, senkronizasyondan bağımsız bir ayardır: senkronizasyon kapalı olsa da varsayılan olarak açık kalır. Açık olduğu sürece, doğrulanan bir token yalnızca aynı kullanıcı adına sahip bir Kimlik Bilgisi kaydı zaten varsa kabul edilir — bu kaydın nereden geldiği (bu sağlayıcının senkronizasyonu, bir LDAP veya Veritabanı sağlayıcısı ya da elle giriş) fark etmez. Token'ın claim'lerine tek başına güvenilmesini istiyorsanız bu ayarı kapatmanız gerekir.
Parola Modeli
Kullanıcı parolası her zaman Keycloak/IdP tarafında kalır; hiçbir zaman Apinizer'a taşınmaz. Senkronizasyon ile oluşan Kimlik Bilgisi kayıtlarının parolası yoktur — kimlik doğrulaması, kullanıcının sağlayıcıdan aldığı token'ın claim'leriyle önceden senkronize edilmiş kayıt arasında eşleşme kurularak yapılır. Kullanıcı adı/parola çiftinin doğrudan sağlayıcıya vekaleten iletildiği bir akış (resource owner password credentials / ROPC) desteklenmez.
Bu modelin çalışması için Kullanıcı Adı Claim ile senkronizasyonun Kimlik Bilgisi kaydına yazdığı kullanıcı adı aynı değere çözülmelidir: senkronizasyon Keycloak'taki kullanıcı adını (username) doğrudan Kimlik Bilgisi kaydının kullanıcı adına yazar, doğrulama tarafı ise varsayılan olarak preferred_username claim'ini okur — standart bir Keycloak kurulumunda ikisi aynı değere karşılık gelir. Kullanıcı Adı Claim özelleştirilirse, bu eşleşmenin bozulmadığından emin olunmalıdır; aksi halde token doğrulanır ama hiçbir Kimlik Bilgisi kaydıyla eşleşmez (Eşleşen Credential Zorunlu Olsun açıkken bu durumda istek reddedilir).
Senkronizasyon sekmesi
Yalnızca Sağlayıcı Türü Keycloak iken anlamlıdır. Senkronizasyonu Etkinleştir açıldığında bu sağlayıcıdan kullanıcı, grup ve rol bilgileri zamanlanmış veya elle tetiklenen bir işle Kimlik Bilgisi kayıtlarına senkronize edilir.
Sağlayıcı Türü Generic iken bu sekmedeki tüm alanlar pasiftir; senkronizasyonu etkinleştirmeye çalışmak kayıt sırasında (ve zaten kayıtlı bir sağlayıcı için Senkron Et'e tıklandığında da) hata ile reddedilir — önce Sağlayıcı Türünü Keycloak olarak değiştirmek gerekir.
| Alan | Açıklama |
|---|---|
| Senkronizasyonu Etkinleştir | Açıkken bu sağlayıcıdan kullanıcı/grup/rol senkronizasyonu çalışır. |
| Realm | Keycloak realm adıdır. |
| Admin API Taban URL | Keycloak sunucusunun taban adresidir (örn. https://keycloak.example.com). |
| Senkron İstemci ID | Yalnızca Rol Senkron Kaynağı = İstemci Rolleri seçildiğinde kullanılır: rolleri kullanıcının rolleri olarak okunacak Keycloak istemcisini adlandırır. Admin API'ye kimlik doğrulayan istemci DEĞİLDİR — o, İstemci sekmesindeki Client ID / Client Secret'tır. |
| Senkron Sayfa Boyutu | Keycloak Admin API'sinden kullanıcılar sayfalanarak (paged) çekilirken kullanılan sayfa boyutudur. Varsayılan: 250 — motor her sayfa (batch) için bir worker deploy'u tetiklediğinden, büyük kullanıcı havuzlarında (~4000 kullanıcı) worker'a gönderilen güncelleme sayısını azaltmak için varsayılan değer 100'den yükseltilmiştir. |
| Grupları Senkronize Et | Açıkken Keycloak grup ağacı, Kurumlar yapısına yansıtılır. Bir Keycloak grup yolu, başka bir kaynağa ait (elle oluşturulmuş ya da başka bir sağlayıcıdan senkronize edilmiş) mevcut bir kurum kaydıyla aynı koda çözülürse, bu düğüm devralınmaz — atlanır (senkron geçmişinde Atlanan sayacına yansır) ve dokunulmadan bırakılır; aksi halde o kurum bu sağlayıcıya devralınıp, düğüm Keycloak'tan kalktığında yanlışlıkla silinebilirdi. |
| Rol Senkron Kaynağı | Kullanıcı rol/grup üyeliğinin Keycloak Admin API'sinden hangi kaynaktan çekileceğini belirler: • Realm Rolleri — realm seviyesindeki rol atamaları. • İstemci Rolleri — Senkron İstemci ID altındaki istemci seviyesindeki rol atamaları. • Gruplar — kullanıcının üye olduğu grup (ve alt grup) adları. |
| Senkron Zamanlaması (cron) | Senkronizasyonun ne sıklıkla çalışacağını belirten Quartz cron ifadesidir. Boş bırakılırsa yalnızca elle tetikleme yapılabilir. |
| Deaktivasyon Modu | Son senkronizasyon koşusunda Keycloak'ta artık bulunmayan kullanıcılara karşılık gelen Kimlik Bilgisi kayıtlarına uygulanacak işlemdir. Keycloak'ta hâlâ listelenen ama enabled=false olarak işaretli bir kullanıcı bu ayardan bağımsız olarak her koşuda doğrudan devre dışı bırakılır (Deaktivasyon Modu yalnızca kaynaktan tamamen kalkan kullanıcıları kapsar). |
Senkronizasyonu Etkinleştir, Grupları Senkronize Et ve Rol Senkron Kaynağı alanlarının yanındaki (i) simgesi, Sağlayıcı Türü Keycloak iken o okuma için servis hesabına gereken realm-management rollerini gösterir — güncel ve tam liste için aşağıdaki Keycloak Service Account Gereksinimleri bölümüne bakınız. Sağlayıcı Türü Generic iken aynı simge, senkronizasyonun yalnızca Keycloak sağlayıcı türünde kullanılabildiğini belirten genel bir metin gösterir.
Senkron Geçmişi bölümündeki Senkron Et düğmesi ile zamanlamayı beklemeden anında senkronizasyon tetiklenebilir; en son koşunun eklenen/güncellenen, deaktive edilen ve hata sayıları burada görüntülenir. Ortak alanların ayrıntılı açıklaması, zamanlama davranışı ve Kimlik Doğrulama Hizmetlerini Yönet ekranındaki toplu izleme görünümü için Kimlik Bilgisi Senkronizasyonu sayfasını inceleyebilirsiniz.
Senkron Et senkronizasyonu arka planda başlatır; sonuç isteğin yanıtında dönmez. Sağlayıcının görüntüleme ekranındaki son koşu özeti ile hemen altındaki Senkronizasyon Geçmişi tablosu, tetiklemeden yaklaşık üç saniye sonra kendiliğinden tazelenir ve yeni koşu satırını gösterir. Tazeleme geldiğinde satır Kuyrukta veya Çalışıyor durumunda görünebilir — koşu kaydı tetiklemeyle birlikte doğar, sonucunu ise bittiğinde alır.
Bu noktadan sonra Senkronizasyon Geçmişi tablosu koşuyu kendisi takip eder: çalışan bir satır görünürken tablo yaklaşık beş saniyede bir sessizce güncellenir ve koşu bittiğinde sonucunu ekranda alır. Büyük bir realm nedeniyle uzun süren bir koşuda da sonuç bu yolla görünür; artık sayfayı tarayıcıdan yenilemek gerekmez. Takibin ayrıntıları ve sınırları için Kimlik Bilgisi Senkronizasyonu sayfasına bakınız.
Bir kaynak için aynı anda yalnızca bir koşu çalışabilir; koşu durumlarının anlamı, yarıda kalan koşuların nasıl kapandığı ve koşu hata listesi için Kimlik Bilgisi Senkronizasyonu sayfasına bakınız.
Tablonun üstündeki son koşu özeti bu canlı takibe dahil değildir: koşu tabloda sonucunu aldıktan sonra bile özet kutusundaki sayılar bir önceki koşuya ait kalabilir. Özeti ve tabloyu birlikte tazelemek için Senkronizasyon Geçmişi başlığının yanındaki Yenile düğmesi kullanılır; en yeni koşu en üstte doğduğu için tablo ilk sayfaya döner. Zamanlanmış bir koşu siz ekranı açık tutarken arka planda başlarsa canlı takip kendiliğinden devreye girmez — o koşuyu ekrana getirmenin yolu da Yenile'dir.
Sağlayıcı düzenleme ekranındaki Senkron Geçmişi bölümü de aynı biçimde davranır; orada yalnızca son koşunun özeti ve o özete ait Yenile düğmesi bulunur. Koşuların tamamı, sağlayıcının görüntüleme ekranındaki Senkronizasyon Geçmişi tablosundadır.
Bağlantı Testi ve Dizin Önizleme
Kaydedilmiş bir sağlayıcının düzenleme ekranının üst kısmında üç tanı düğmesi yan yana durur. Üçü de formda o an girilmiş olan bilgilerle çalışır, hiçbiri kaydetme yapmaz. Düğmeler yalnızca kaydedilmiş bir sağlayıcıda görünür; yeni oluşturulan bir sağlayıcının önce kaydedilmesi gerekir.
| Düğme | Ne yapar |
|---|---|
| Bağlantıyı Test Et | Sırasıyla discovery dokümanını, JWKS anahtarlarını ve (istemci bilgileri doluysa) bir client-credentials token isteğini dener; herhangi bir adım başarısız olursa açıklayıcı bir hata döndürür. Bu düğme ve davranışı değişmemiştir, olduğu gibi durur. |
| Bağlantı Testini Çalıştır | Aynı bağlantıyı sekiz ayrı adım olarak ölçer ve her adımı kendi satırında gösterir — bkz. Bağlantı Testi Adım Matrisi. |
| Dizini Önizle | Sağlayıcı dizininden ilk kullanıcı, grup ve rol kayıtlarını okuyup gösterir — bkz. Dizin Önizleme. |
Bu üç işlem ve Keşfet, formda girilen adreslere Manager üzerinden giden istekler ürettiği için "Kimlik Doğrulama Hizmetlerini Yönet" yetkisi gerektirir.
Bağlant ı Testi Adım Matrisi
Bağlantı Testini Çalıştır, tek bir "başarılı/başarısız" özeti yerine bağlantıyı sekiz adıma böler ve her adımı tek tek ölçer — düşen bir adım kendinden sonrakileri gizlemez. Sonuçlar bir pencerede adım, durum, süre, açıklama, HTTP durumu ve sağlayıcı hata kodu sütunlarıyla listelenir; bir adım düştüğünde gerekçesi doğrudan tabloda okunur, ayrı bir hata mesajı aramak gerekmez.
| Adım | Ne ölçer |
|---|---|
| Yapılandırma Kontrolü | Ağa hiç çıkmadan formun kendi içinde tutarlı olup olmadığı: discovery adresi bilgilerden türetilebiliyor mu, JWKS kaynağı Statik ise yapıştırılan anahtar materyali geçerli mi. |
| Discovery Belgesi | Discovery adresine erişilebiliyor ve geçerli bir belge dönüyor mu. |
| İmza Anahtarları (JWKS) | İmza doğrulama anahtarlarının adresi çözülebiliyor ve okunabiliyor mu; Statik kaynakta anahtar materyali yerel olarak doğrulanır. |
| Client Credentials Token'ı | İstemci bilgileriyle token uç noktasından token alınabiliyor mu. |
| Admin API Token'ı | Keycloak Admin API'sine service-account token'ı ile erişilebiliyor mu. |
| Kullanıcı Okuma | Realm'den kullanıcı listesi okunabiliyor mu. |
| Grup Okuma | Grup ağacı okunabiliyor mu. |
| Rol Okuma | Rol listesi okunabiliyor mu. |
Her adım dört durumdan birini alır:
| Durum | Anlamı |
|---|---|
| Başarılı | Adım koşuldu ve beklenen sonucu verdi. |
| Başarısız | Adım koşuldu ve düştü. Gerekçe, varsa sağlayıcının döndürdüğü HTTP durumu ve hata kodu aynı satırda görünür. |
| Uygulanmaz | Adım bu yapılandırmada koşmaz. İki nedeni olabilir: adım gereksizdir (JWKS kaynağı Statik olduğu için discovery çekilmez, grup senkronizasyonu kapalı olduğu için gruplar okunmaz) ya da önceki bir adım düştüğü için ölçülemez. Hangisi olduğu satırın açıklamasında yazar. |
| Desteklenmiyor | Sağlayıcı bu adımı hiç yapamaz — yapılandırma değişikliğiyle açılabilecek bir durum değildir. |
Kullanıcı Okuma, Grup Okuma ve Rol Okuma adımlarında Keycloak Admin API'sinin döndürdüğü 403 yanıtı, düz bir HTTP kodu olarak değil, "İzin eksik: servis hesabı <ilgili okuma> okuyamıyor (HTTP 403)" açıklamasıyla ve yukarıdaki Keycloak Service Account Gereksinimleri bölümüne yönlendiren bir bağlantıyla gösterilir. Aynı adımlarda dönen 401 yanıtı "kimlik reddedildi" olarak gösterilir; bu ikisi dışındaki bir HTTP durum kodu olduğu gibi görüntülenir.
Bu sağlayıcının senkronizasyon koşu geçmişinde de aynı 403 durumu İzin eksik sebep rozetiyle görünür.
Sağlayıcı Türü Generic iken ilk dört adım (yapılandırma, discovery, JWKS, client-credentials) normal şekilde koşar; bunlar OIDC/OAuth2 standardının parçasıdır ve her sağlayıcıda çalışır. Son dört adım (Admin API token'ı, kullanıcı/grup/rol okuma) Desteklenmiyor döner, çünkü Generic bir sağlayıcıda okunacak bir Keycloak Admin API'si yoktur. Matrisin varlık sebebi tam olarak budur: bağlantı "yarım başarılı" değildir — sağlayıcının yapabildikleri ile yapamadıkları ayrı ayrı okunur.
Sağlayıcı hata kodu sütunu, yalnızca sağlay ıcının yanıtındaki standart OAuth hata kodunu (örneğin invalid_client) taşır. Hata açıklaması, ham yanıt gövdesi, istemci sırrı ve token değerleri bu ekrana hiçbir zaman yansıtılmaz.
Dizin Önizleme
Dizini Önizle, senkronizasyonu hiç çalıştırmadan "bu sağlayıcıdan ne gelecek" sorusunu yanıtlar: Keycloak dizininden ilk 10 kullanıcı, grup ve rol kaydını okur ve Kullanıcılar / Gruplar / Roller / Sorunlar sekmelerinde gösterir.
- Kullanıcılar — kullanıcı adı, e-posta, ad soyad ve kullanıcının sağlayıcıdaki etkin/pasif durumu.
- Gruplar — her düğümün adı, yolu, normalize edilmiş kurum kodu karşılığı ve ağaçtaki derinliği. Böylece motorun sabit eşlemesinin bu veride ne üreteceği, senkronizasyon çalışmadan önce görülür.
- Roller — Rol Senkron Kaynağı ayarına göre okunan rol adları.
- Sorunlar — üç alandan biri okunamadıysa gerekçesi. Bir alanın okunamaması diğerlerinin gösterilmesini engellemez.
Bir alanda dizinde daha fazla kayıt varsa listenin altında "ilk 10 kayıt gösteriliyor, devamı var" notu görünür.
Dizin önizleme sağlayıcı dizinini yalnızca okur. Apinizer tarafında hiçbir kimlik bilgisi, kurum ya da rol kaydı oluşturulmaz, güncellenmez veya silinmez; kaynağın senkronizasyon sayaçlarına ve koşu geçmişine de dokunulmaz. Önizleme bir senkronizasyon koşusu değildir — koşu geçmişinde satır oluşturmaz ve çalışan bir koşuyu engellemez.
- Toplam sayı gösterilmez. Sağlayıcı bu okumada toplam kullanıcı/grup sayısını vermediği için ekranda yalnızca "ilk N kayıt + devamı var" bilgisi bulunur; uydurma bir toplam üretilmez.
- Kullanıcı başına kurum ve rol ataması önizlenmez. Bunun için her grubun üye listesinin taranması gerekirdi; büyük bir realm'de bu, hafif bir okuma olmaktan çıkardı. Önizleme yalnızca dizinin kendisini okur.
- Grup ağacı ilk düğümlerde durur. Ağaç yürüyüşü istenen kayıt sayısına ulaşınca biter; derin bir ağacın tamamı gezilmez.
- Generic sağlayıcıda kullanılamaz. Sağlayıcı Türü Generic iken düğme pasiftir; okunacak bir Admin API olmadığı için önizleme yapılamaz.
Keycloak Service Account Gereksinimleri
Admin API token'ı İstemci sekmesindeki Client ID / Client Secret ile alınır; dolayısıyla o istemci service account'u olan gizli (confidential) bir istemci olmalıdır. Bu service account'a, ilgili realm'in realm-management istemcisi altında en az şu client role'ler atanmalıdır: view-users, query-groups ve view-realm (view-realm rol üyeliklerini okumak için gereklidir — olmadan /roles/{name}/users 403 döner).
Açılan seçeneklere göre ek gereksinimler:
- Grupları Senkronize Et — grup ağacını ve üyelikleri okumak için
query-groupsgerekir (yukarıda zaten listelendi). - Rol Senkron Kaynağı = İstemci Rolleri — hedef istemcinin rol listesini çözebilmek için ayrıca
view-clientsgerekir.
Bu roller olmadan Keycloak Admin REST API ilgili çağrılara 403 Forbidden döner; senkronizasyon koşumu hatayı raporlar ve mevcut hiçbir kimlik bilgisini deaktive etmez (bkz. Davranış ve Güvenlik Notları).
Sorun Giderme — Senkronizasyon "kullanıcı çekilemiyor" ile düşüyor
Senkronizasyon koşumu düştüğünde Administration > Logging > Application Logs ekranında IdentitySyncService: user fetch failed ... satırı görünür. Bu satır yalnızca "çekilemedi" der; nedeni hemen öncesindeki sağlayıcı satırındadır.
Kaynak, beklenen kullanıcı/grup/rol listesi yerine başka bir yanıt döndürdüyse şu WARN satırı yazılır:
OidcIdentitySyncProvider: Keycloak admin response is NOT a JSON array — kind=HTML diagnosis='...'
path=/admin/realms/<realm>/users status=200 contentType=text/html bodyLength=1834 bodyPreview=[...]
providerId=... realm=... adminBaseUrl=...
Satırdaki alanlar: yanıtın sabit sınıflandırması (kind), okunabilir açıklaması (diagnosis), hangi uç noktanın okunduğu (path — sorgu parametreleri yazılmaz), dönen HTTP durumu (status), yanıtın türü (contentType), gövde uzunluğu (bodyLength), gövdenin ilk 200 karakteri (bodyPreview — token/parola değerleri ve URL sorgu dizeleri *** ile maskelenir) ve senkronize edilen sağlayıcı (providerId, realm, adminBaseUrl).
Koşumun kendisi de IdentitySyncService: user fetch failed ... satırıyla düşer ve o satır kind, path, status, contentType, bodyLength değerlerini tekrar eder; yani yalnızca ERROR seviyesi tutulmuş bir logda da sınıflandırma okunabilir. Gövde önizlemesi sadece yukarıdaki WARN satırında yer alır.
kind alanına göre nereye bakılacağı:
| kind | Anlamı | Yapılacak |
|---|---|---|
KEYCLOAK_ERROR_OBJECT | Kaynak, liste yerine kendi hata nesnesini döndürdü (error / error_description ya da errorMessage). Hata kodu ve açıklaması diagnosis alanında yazılıdır. | Genellikle yetki veya istemci sorunudur. Service account'un realm-management altındaki view-users, query-groups, view-realm (ve İstemci Rolleri seçiliyse view-clients) rollerini doğrulayın. |
HTML | Yanıt bir HTML sayfasıdır — genellikle Keycloak giriş ekranı ya da araya giren bir ters vekil sunucunun hata sayfası. | Endpointler sekmesindeki Admin Base URL ile Genel sekmesindeki Realm değerini doğrulayın; eski Keycloak sürümlerinde adres /auth ön ekiyle biter. Keycloak'ın önünde bir ters vekil sunucu / WAF varsa /admin/realms/... yolunun ona takılmadığını kontrol edin. |
EMPTY | Kaynak başarılı bir yanıt döndürdü ama gövde boş. Keycloak boş listeyi boş dizi olarak döndürür, boş gövde döndürmez. Boş gövde sayfalama döngüsünü erken bitirdiği için Apinizer'ın okuduğu liste eksiktir. | Araya giren ters vekil sunucu / yük dengeleyici gövdeyi düşürüyor olabilir. Aynı adrese Apinizer sunucusundan doğrudan istek atarak yanıtı karşılaştırın. Koşum eksik okuma olarak işaretlenir: okunan kayıtlar yine uygulanır, deaktivasyon atlanır ve koşum uyarı ile biter. |
JSON_OBJECT | Yanıt geçerli bir JSON nesnesidir ama liste değildir. | Admin Base URL'in bir Keycloak Admin API kökünü gösterdiğini doğrulayın; farklı bir servise (veya API Gateway'e) yönlendirilmiş olabilir. |
MALFORMED | Yanıt ne JSON dizisi ne de JSON nesnesidir — kırpılmış ya da ikili bir gövde. | Yanıtı yeniden yazan veya sıkıştıran bir vekil sunucu olup olmadığını kontrol edin ve Apinizer sunucusundan doğrudan yapılan bir çağrıyla karşılaştırın. |
Aynı teşhis kullanıcı, grup ve rol okumalarının hepsinde geçerlidir; path alanı hangi okumanın düştüğünü söyler.
Admin token isteği başarılı yanıt verdiği hâlde içinde access_token yoksa eşdeğer bir satır yazılır (OidcIdentitySyncProvider: OIDC admin token response carries no access_token — kind=... diagnosis=...). Bu satır aynı sınıflandırmayı Endpointler sekmesindeki Token Endpoint için verir ve oradaki başarılı bir yanıt gerçek bir token taşıyacağı için gövde önizlemesi hiç basmaz.
Kullanıcı listesi okunamadığında koşu hatayla biter ve hiçbir kimlik bilgisi deaktive edilmez; okunamamış kayıtların "kaynaktan silinmiş" sayılması bu şekilde engellenir. Ayrıntı için Davranış ve Güvenlik Notları bölümüne bakabilirsiniz.
Sağlayıcı ekranındaki Bağlantı Testi aynı okumaları tek kayıtla dener ve adım adım sonuç verir; bir senkronizasyon koşumu beklemeden aynı sorunu yüzeye çıkarır. Bkz. Bağlantı Testi ve Dizin Önizleme.
İlgili Sayfalar
Token taşıyan politikalarda bu sağlayıcının nasıl referans gösterileceği için OIDC Kimlik Doğrulama sayfasını, senkronize edilen kayıtlar için Kimlik Bilgileri sayfasını, ortak senkronizasyon davranışı için Kimlik Bilgisi Senkronizasyonu sayfasını inceleyebilirsiniz.