Geliştiriciler için OIDC Entegrasyonu Rehberi#

(keysis & hvl-oauth-oidc-client – Authorization Code Flow)#

Bu doküman, hvl-oauth-oidc-client ile geliştirilen bir uygulamanın
keysis Identity Provider üzerinden OpenID Connect (OIDC) kullanarak nasıl kimlik doğrulama yaptığını, Authorization Code Flow temelinde açıklar.

Doküman; konfigürasyon detaylarından ziyade, entegrasyonun mantıksal akışını ve sorumluluk dağılımını anlatmayı amaçlar.

Amaç ve Kapsam#

Bu rehber aşağıdaki konuları kapsar:

keysis’in OIDC tabanlı kimlik doğrulama rolü
hvl-oauth-oidc-client kullanan uygulamanın OAuth2 Client davranışı
Authorization Code Flow’un uçtan uca çalışma mantığı
Login sonrası session ve güvenlik bağlamının oluşumu

Bu doküman: - UI implementasyon detaylarını - framework’e özgü kod parçalarını - alternatif IdP senaryolarını

kapsamaz.

Mimari Roller ve Terminoloji#

OIDC entegrasyonunda roller aşağıdaki gibidir:

Rol	Açıklama
Identity Provider (IdP)	keysis
Authorization Server	keysis
OAuth2 Client	hvl-oauth-oidc-client kullanan uygulama
Resource Owner	Son kullanıcı
Resource Server	Korumalı backend servisleri

Kimlik doğrulama (authentication) işlemi yalnızca keysis tarafından yapılır.
Uygulama, OIDC standartlarında tanımlı OAuth2 Client rolündedir.

OIDC Discovery Mekanizması#

keysis çalıştığında, OIDC standardına uygun olarak aşağıdaki endpoint’i sunar:

/.well-known/openid-configuration#

Bu endpoint üzerinden:

Authorization endpoint
Token endpoint
UserInfo endpoint
JWKS (public key) bilgileri

otomatik olarak keşfedilir.

hvl-oauth-oidc-client, bu discovery mekanizmasını kullanarak IdP’ye ait uç noktaları merkezi ve güvenli şekilde öğrenir.

Authorization Code Flow – Mantıksal Akış#

1. Korumalı Kaynağa Erişim#

Kullanıcı, uygulama üzerinde kimlik doğrulama gerektiren bir kaynağa erişmeye çalışır.

Uygulama, kullanıcının henüz authenticate olmadığını tespit eder.

2. keysis Authorization Endpoint’e Yönlendirme#

Uygulama, OAuth2 Authorization Code Flow gereği kullanıcıyı keysis authorization endpoint’ine yönlendirir.

Bu yönlendirme sırasında:

client_id
redirect_uri
scope (openid, profile, vb.)
response_type=code

bilgileri iletilir.

3. Kullanıcının keysis Üzerinde Doğrulanması#

Kullanıcı, keysis arayüzü üzerinden kimliğini doğrular.

Bu aşamada:

Kimlik doğrulama yöntemleri (şifre, MFA vb.)
Güvenlik politikaları
Kullanıcıya ait kimlik bilgileri

tamamen keysis sorumluluğundadır.

4. Authorization Code’un Üretilmesi#

Başarılı doğrulama sonrası keysis:

Kısa ömürlü
Tek kullanımlık

bir authorization code üretir ve kullanıcıyı tanımlı redirect_uri adresine yönlendirir.

5. Authorization Code → Token Değişimi#

Uygulama, aldığı authorization code’u kullanarak doğrudan (server-to-server) keysis token endpoint’ine istek yapar.

Bu istek sonucunda:

ID Token
Access Token
(policy’ye bağlı olarak) Refresh Token

elde edilir.

Bu aşamada kullanıcı tarayıcısı sürecin dışında kalır.

6. Güvenlik Bağlamı ve Session Oluşumu#

Token’ların başarıyla alınmasının ardından:

ID Token üzerinden kullanıcı kimliği doğrulanır
Spring Security context oluşturulur
Kullanıcıya ait HTTP session başlatılır

Session verileri:

Varsayılan olarak in-memory
redis profili aktifse Redis üzerinde

saklanabilir.

7. Korumalı Kaynaklara Erişim#

Artık kullanıcı:

Uygulama içindeki korumalı sayfalara
Backend API çağrılarına

yetkili şekilde erişebilir.

Access token, resource server çağrılarında kullanılır.

Güvenlik ve Sorumluluk Sınırları#

Bu entegrasyon modelinde:

keysis → kimlik doğrulama ve token üretiminden sorumludur
Uygulama → token tüketimi ve session yönetiminden sorumludur
Redis → kimlik doğrulama yapmaz, yalnızca session saklar

Bu sınırlar özellikle SSO, logout ve ölçeklenebilirlik açısından kritiktir.

Logout ile İlişki (Kısa Not)#

Bu akış sonucunda oluşan session’lar:

Front-channel logout
Back-channel logout

mekanizmaları ile keysis tarafından sonlandırılabilir.

Dağıtık mimarilerde Redis session kullanımı, logout işlemlerinin tutarlı uygulanmasını sağlar.

Uygulama Tarafı Ön Koşullar#

OIDC entegrasyonunun sağlıklı çalışabilmesi için uygulama tarafında aşağıdaki ön koşullar sağlanmalıdır:

Uygulamanın login page URL’i, keysis üzerinde tanımlı UI URL ile birebir uyumlu olmalıdır.

application-authentication.yml dosyasında: AUTH_OIDC_LOGIN_PAGE_URL -> UI URL ile aynı olmalı.

Bu URL uyumsuzluğu, redirect veya login sonrası geri dönüş hatalarına yol açabilir.

Client Bilgileri (Test Senaryosu)#

Test amaçlı bir OIDC client için örnek bilgiler:

Client ID: auth-experimental
Client Secret: test

Bu bilgiler yalnızca test ortamı için örnek teşkil eder.

Özet#

hvl-oauth-oidc-client ile geliştirilen bir uygulama,
keysis Identity Provider üzerinden Authorization Code Flow kullanarak
güvenli bir şekilde kimlik doğrulama yapar.
Kimlik doğrulama keysis’te, oturum ve yetkilendirme ise uygulama tarafında yönetilir.