OIDC Kimlik Sağlayıcı

bilgi

"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ı 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

uyarı

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.

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).

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.

Bağlantıyı Test Et

Kayıt ekranının üst kısmındaki Bağlantıyı Test Et düğmesi, formda o an girilmiş olan sağlayıcı bilgileriyle 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 işlem herhangi bir veriyi kaydetmez.

bilgi

Bağlantıyı Test Et ve Keşfet işlemleri, formda girilen adreslere Manager üzerinden giden istekler ürettiği için "Kimlik Doğrulama Hizmetlerini Yönet" yetkisi gerektirir.

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-groups gerekir (yukarıda zaten listelendi).
• Rol Senkron Kaynağı = İstemci Rolleri — hedef istemcinin rol listesini çözebilmek için ayrıca view-clients gerekir.

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ı).

İ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.