OAuth 2.0 / OpenID Connect Entegrasyonu

SecTrail MFA v2.1, OAuth 2.0 Authorization Server ve OpenID Connect (OIDC) Identity Provider olarak çalışarak sunucu taraflı web uygulamalarıyla entegrasyon sağlar. Bu sayede uygulamalar kullanıcı kimliğini doğrulamak için SecTrail MFA'nın MFA korumasından yararlanır.

Genel Bakış

Desteklenen Grant Türleri

Grant Türü	Kullanım Senaryosu
Authorization Code	Web uygulamaları (sunucu taraflı)

OIDC Endpoint'leri

SecTrail MFA aşağıdaki standart OIDC endpoint'lerini sunar:

Endpoint	URL	Açıklama
Discovery	`/.well-known/openid-configuration`	OIDC yapılandırma metadata
Authorization	`/oauth/authorize`	Yetkilendirme başlatma
Token	`/oauth/token`	Token alımı ve yenileme
UserInfo	`/oauth/userinfo`	Kimliği doğrulanmış kullanıcı bilgileri
JWKS	`/oauth/jwks`	RSA public key seti
End Session	`/oauth/logout`	Oturum sonlandırma

Discovery endpoint'i üzerinden tüm yapılandırma bilgilerine erişilebilir:

GET /.well-known/openid-configuration

Örnek yanıt:

{
  "issuer": "https://register.sectrail.local",
  "authorization_endpoint": "https://register.sectrail.local/oauth/authorize",
  "token_endpoint": "https://register.sectrail.local/oauth/token",
  "userinfo_endpoint": "https://register.sectrail.local/oauth/userinfo",
  "jwks_uri": "https://register.sectrail.local/oauth/jwks",
  "end_session_endpoint": "https://register.sectrail.local/oauth/logout",
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "profile", "email", "phone", "offline_access"],
  "backchannel_logout_supported": true,
  "backchannel_logout_session_supported": true
}

OAuth İstemci Yönetimi

Admin panelinde OAuth → İstemciler menüsünden OAuth istemcileri oluşturulur ve yönetilir.

Yeni İstemci Oluşturma

Admin Paneli → OAuth → İstemciler → Yeni İstemci yolunu izleyin.

Yapılandırma alanları:

Alan	Açıklama	Örnek
İsim	İstemcinin görünen adı	`Kurumsal Portal`
Redirect URI	Yetkilendirme sonrası yönlendirme adresi	`https://app.ornek.com/callback`
Consent Gerekli	Kullanıcıdan onay ekranı gösterilip gösterilmeyeceği	Aktif / Pasif
Backchannel Logout URI	Back-channel logout endpoint (opsiyonel)	`https://app.ornek.com/backchannel-logout`
Scope'lar	İstemcinin talep edebileceği scope'lar	`openid`, `profile`, `email`

İstemci oluşturulduktan sonra sistem otomatik olarak:

Client ID: İstemcinin genel tanımlayıcısı
Client Secret: Token endpoint kimlik doğrulaması için gizli anahtar

değerlerini üretir. Bu değerler istemci listesinde görüntülenebilir.

İstemci Özellikleri

Access Token Ömrü: Varsayılan olarak 60 dakika. İstemci bazında özelleştirilebilir.

Refresh Token Ömrü: Varsayılan olarak 1440 dakika (24 saat).

Consent Ekranı: consent_required aktif olan istemcilerde, kullanıcı ilk yetkilendirmede hangi bilgilerin paylaşılacağını gösteren bir onay ekranı ile karşılaşır. Ekranda hassas veriler (telefon, e-posta) maskelenerek gösterilir.

Auto-Approve: consent_required pasif ise kullanıcı için geçerli bir token varsa yeniden onay istenmeden otomatik yetkilendirme yapılır.

Authorization Code Flow (Yetkilendirme Akışı)

1. Yetkilendirme İsteği

Uygulama, kullanıcıyı aşağıdaki URL'ye yönlendirir:

GET /oauth/authorize
  ?response_type=code
  &client_id=<CLIENT_PUBLIC_ID>
  &redirect_uri=https://app.ornek.com/callback
  &scope=openid profile email
  &state=<RANDOM_STATE>
  &nonce=<RANDOM_NONCE>

Parametre	Zorunlu	Açıklama
`response_type`	Evet	Her zaman `code`
`client_id`	Evet	İstemcinin `public_id` değeri
`redirect_uri`	Evet	İstemcide kayıtlı redirect URI
`scope`	Evet	Talep edilen scope'lar (boşlukla ayrılmış)
`state`	Önerilir	CSRF koruması için rastgele değer
`nonce`	Önerilir	ID Token tekrar saldırılarına karşı
`prompt`	Hayır	`none`, `login`, `consent` değerlerini alabilir

prompt parametresi:

login: Geçerli bir session olsa bile kullanıcıdan yeniden giriş istenir.
consent: Geçerli bir token olsa bile onay ekranı gösterilir.
none: Etkileşim olmaksızın yetkilendirme yapılır; kullanıcı oturumu yoksa hata döner.

2. Kullanıcı Kimlik Doğrulama ve MFA

SecTrail MFA, kullanıcıyı kayıt paneli giriş sayfasına yönlendirir. Kullanıcı yapılandırılmış MFA yöntemiyle kimliğini doğrular.

Kullanıcı Login Sayfası

consent_required aktifse kullanıcıya paylaşılacak bilgileri gösteren onay ekranı gösterilir. Kullanıcı Onayla veya Reddet seçeneklerinden birini seçer.

Onay Ekranı

4. Authorization Code Alımı

Kullanıcı onayladıktan sonra redirect_uri'ye yönlendirilir:

https://app.ornek.com/callback?code=<AUTH_CODE>&state=<STATE>

5. Token Alımı

Uygulama, authorization code ile token endpoint'ini çağırır:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<AUTH_CODE>
&redirect_uri=https://app.ornek.com/callback
&client_id=<CLIENT_PUBLIC_ID>
&client_secret=<CLIENT_SECRET>

Başarılı yanıt:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ...",
  "refresh_token": "def5020...",
  "id_token": "eyJ..."
}

6. Token Yenileme

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<REFRESH_TOKEN>
&client_id=<CLIENT_PUBLIC_ID>
&client_secret=<CLIENT_SECRET>

ID Token ve Access Token

ID Token Yapısı

SecTrail MFA, RS256 algoritmasıyla imzalanmış JWT formatında ID Token üretir.

Header:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "<KEY_ID>"
}

Payload (örnek):

{
  "iss": "https://register.sectrail.local",
  "sub": "42",
  "aud": "a1b2c3d4-...",
  "exp": 1745123456,
  "iat": 1745119856,
  "jti": "abc123...",
  "nonce": "xyz789",
  "email": "kullanici@ornek.com",
  "name": "Ad Soyad",
  "preferred_username": "kullanici"
}

ID Token, openid scope'u talep edildiğinde her zaman üretilir.

Token İmzası Doğrulama

Token imzası JWKS endpoint'inden alınan RSA public key ile doğrulanabilir:

GET /oauth/jwks

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "<KEY_ID>",
      "n": "<MODULUS_BASE64URL>",
      "e": "AQAB"
    }
  ]
}

UserInfo Endpoint

Geçerli bir access token ile kullanıcı bilgileri sorgulanabilir:

GET /oauth/userinfo
Authorization: Bearer <ACCESS_TOKEN>

Yanıt, istemcinin talep ettiği scope'lara göre şekillenir:

{
  "sub": "42",
  "email": "kullanici@ornek.com",
  "name": "Ad Soyad",
  "preferred_username": "kullanici",
  "phone_number": "+905xxxxxxxx"
}

Scope ve Claim Yönetimi

Sistem Scope'ları

Scope	Açıklama
`openid`	OIDC temel scope; ID Token üretilmesi için zorunlu
`profile`	Kullanıcının adı ve kullanıcı adı
`email`	E-posta adresi
`phone`	Telefon numarası
`offline_access`	Refresh token verilmesini sağlar

Claim Eşleme

Admin Paneli → OAuth → Scope'lar bölümünden her scope için hangi kullanıcı alanının hangi claim adıyla iletileceği yapılandırılır.

Alan	Açıklama
Claim Adı	Token'a eklenecek alan adı (örn: `email`, `phone_number`)
Kaynak Attribute	LDAP attribute veya yerel kullanıcı alanı (örn: `mail`, `telephoneNumber`)
Kullanıcı Türü	`LDAP` veya `Yerel` kullanıcı
Hassas	Aktifse consent ekranında değer maskelenerek gösterilir

LDAP kullanıcıları için desteklenen attribute'lar: sAMAccountName, mail, givenName, sn, displayName, telephoneNumber, mobile ve diğer standart AD attribute'ları.

İstemci Bazlı Scope Kısıtlaması

Her istemci yalnızca kendisine atanan scope'ları talep edebilir. İzin verilmeyen scope'lar yetkilendirme sırasında otomatik olarak filtrelenir.

Logout

Front-Channel Logout

Kullanıcı uygulamadan çıkış yaptığında SecTrail MFA'ya bildirim göndermek için:

GET /oauth/logout
  ?id_token_hint=<ID_TOKEN>
  &post_logout_redirect_uri=https://app.ornek.com/logout-success
  &state=<STATE>

SecTrail MFA, bu istek üzerine ilgili kullanıcının tüm OAuth session'larını iptal eder ve post_logout_redirect_uri'ye yönlendirir.

Back-Channel Logout

SecTrail MFA, kullanıcı oturumu sonlandırıldığında (admin panelinden veya kayıt panelinden) istemcinin backchannel_logout_uri adresine logout_token içeren bir POST isteği gönderir:

POST https://app.ornek.com/backchannel-logout
Content-Type: application/x-www-form-urlencoded

logout_token=<LOGOUT_JWT>

logout_token RS256 imzalı JWT formatındadır. Header'ı "typ": "logout+jwt" olarak işaretlenmiştir ve aşağıdaki claim'leri içerir:

Header:

{
  "typ": "logout+jwt",
  "alg": "RS256",
  "kid": "<KEY_ID>"
}

Payload:

{
  "iss": "https://register.sectrail.local",
  "sub": "42",
  "aud": "<CLIENT_PUBLIC_ID>",
  "iat": 1745119856,
  "exp": 1745120156,
  "jti": "<UUID>",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  }
}

OAuth Session Yönetimi

Admin Panelinde Session Görüntüleme

Admin Paneli → OAuth → Oturumlar menüsünden tüm aktif OAuth oturumları görüntülenebilir:

Bilgi	Açıklama
Kullanıcı	Oturumu açan kullanıcı adı
İstemci	Bağlantı kurulan OAuth istemcisi
IP Adresi	Oturumun açıldığı IP adresi
User Agent	Kullanılan tarayıcı / istemci bilgisi
Oluşturulma	Oturumun başlangıç zamanı

Yönetici işlemleri:

Aktif oturumları listeleme
Belirli bir oturumu sonlandırma (token iptal + back-channel logout gönderimi)

Kayıt Panelinde Session Yönetimi

Kullanıcılar Kayıt Paneli → Oturumlarım bölümünden kendi OAuth oturumlarını görüntüleyebilir ve sonlandırabilir.

GÜVENLİK

Kullanıcılar tanımadıkları bir cihaz ya da IP adresinden açılmış oturumu hemen sonlandırabilirler. Bu özellik hesap güvenliği için kritik bir kontrol mekanizması sağlar.

Desteklenen Kimlik Doğrulama Yöntemleri

OAuth akışı sırasında kullanılabilecek MFA yöntemleri:

LDAP Doğrulaması: Active Directory / LDAP ile kimlik doğrulama
Yerel Doğrulama: SecTrail MFA yerel kullanıcı veritabanı
LDAP + OTP: Şifre ve OTP ile çift faktörlü doğrulama
Soft OTP: SecTrail Authenticator uygulaması ile TOTP
SMS OTP: SMS ile gönderilen tek kullanımlık şifre
Mail OTP: E-posta ile gönderilen tek kullanımlık şifre
Push Bildirimi: SecTrail Authenticator push onayı
QR ile Giriş (Parolasız): Mobil uygulama ile QR kod taraması
WebAuthn (FIDO2): FIDO2 uyumlu donanım anahtarları

Teknik Gereksinimler

İstemci Gereksinimleri

redirect_uri istemci yapılandırmasındaki değerle tam eşleşmelidir (trailing slash dahil).
Token imzası doğrulaması için JWKS endpoint'i kullanılmalıdır; public key hard-code edilmemelidir.

BİLGİ

OAuth 2.0 entegrasyonu için uygulamanızın Authorization Code Grant'ı desteklemesi gerekmektedir.

OAuth 2.0 / OpenID Connect Entegrasyonu

Genel Bakış​

Desteklenen Grant Türleri​

OIDC Endpoint'leri​

OAuth İstemci Yönetimi​

Yeni İstemci Oluşturma​

İstemci Özellikleri​

Authorization Code Flow (Yetkilendirme Akışı)​

1. Yetkilendirme İsteği​

2. Kullanıcı Kimlik Doğrulama ve MFA​

3. Consent Ekranı (Gerekirse)​

4. Authorization Code Alımı​

5. Token Alımı​

6. Token Yenileme​

ID Token ve Access Token​

ID Token Yapısı​

Token İmzası Doğrulama​

UserInfo Endpoint​

Scope ve Claim Yönetimi​

Sistem Scope'ları​

Claim Eşleme​

İstemci Bazlı Scope Kısıtlaması​

Logout​

Front-Channel Logout​

Back-Channel Logout​

OAuth Session Yönetimi​

Admin Panelinde Session Görüntüleme​

Kayıt Panelinde Session Yönetimi​

Desteklenen Kimlik Doğrulama Yöntemleri​

Teknik Gereksinimler​

İstemci Gereksinimleri​