Oturum açma adımını çalıştırma

POST /fapi/v1/transactions/current/steps/{step} · ortamın oturum açma sunucusundan çağrılır

Geçerli işlemin bir adımını çalıştırır. Bu sürüm identifier ve password adımlarını kabul eder. Başarısız her kimlik bilgisi adımı aynı 401 invalid_credentials yanıtını döndürür; böylece yanıt bir hesabın var olup olmadığını asla ortaya koymaz. Parola adımı işlemi tamamladığında oturum çerezleri __Host-idp_session (gerektiğinde __Host-idp_device ile birlikte) ayarlanır ve işlem çerezi kaldırılır.

İstek

Üstbilgiler:

Yol: step, adımın adı (identifier, password, sso_start).

otp_send adımında next_steps[].methods, etkin politikanın izin verdiği parolasız yöntemleri listeler (email_otp, magic_link); istemci yalnızca bunları sunar.

Gövde (alanlar adıma göre değişir; next_steps[].fields bunları listeler):

Yanıt

Adımdan sonraki işlem ile 200 OK döndürülür. completed işleminin csrf_token yoktur.

Ortam ikinci bir faktör gerektiriyor ve kullanıcının henüz hiç faktörü yoksa, ortamın mfa.enrollment_grace_days süresi içindeki kullanıcı yine de oturum açar ve completed yanıtı şunu içerir: mfa_enrollment required_by (RFC 3339, sürenin bitiş zamanı, sunucu tarafından hesaplanır) ve methods (webauthn, totp: kullanıcının şimdi kaydedebileceği faktörler, ekrandaki sırayla). Tarihi gösterin ve kullanıcının devam etmesine izin verin; kayıt, hesap ayarlarına eklenir. Alan; süre tanınmadığında, kullanıcı politikayı zaten karşıladığında veya kayıt hemen zorunlu olduğunda bulunmaz. Bir uygulamanın min_acr ve istenen acr_values hiçbir zaman süre tanınması nedeniyle ertelenmez.

Kurumsal SSO (ana bölge keşfi)

identifier adımı, alan adı bir kurumsal bağlantıya ait olan bir e-posta adresi aldığında oturum açma o bağlantıyla devam eder. Keşif için yalnızca @ sonrasındaki kısım kullanılır.

• Tek bağlantı: İşlem federated_redirect durumuna geçer ve yanıt, kimlik sağlayıcının başlangıç adresi olan redirect_url alanını içerir. Üst düzey pencereyi oraya yönlendirin. Adres tek kullanımlık bir belirteç içerir: onu saklamayın ve günlüğe yazmayın.
• Birden fazla bağlantı: İşlem identifier_pending durumunda kalır ve yanıt sso_connections listesini içerir (connection_id, display_name, protocol). display_name alanını metin olarak gösterin ve kullanıcının seçimini sso_start adımıyla gönderin (identifier ve connection_id). Alan adı için sunulmayan bir bağlantı 422 validation_failed döndürür.
• Bağlantı yok veya keşif geçici olarak kullanılamıyorsa normal oturum açma devam eder; böylece bir kesinti diğer oturum açma yöntemlerini engellemez. sso_start açık bir seçimdir ve bunun yerine 503 temporarily_unavailable döndürür.

Oturum açma isteği SSO gerektiren bir kuruluşu belirttiğinde işlem yalnızca o kuruluşun bağlantılarını sunar: parola ve e-posta kodu adımları sunulmaz; Passkey yalnızca kuruluşun acil durum (break-glass) hesapları varsa kullanılabilir kalır. İşlemi oluşturmak, tek olan bağlantıyı zaten başlatır (federated_redirect ile redirect_url) ya da sso_connections içinde birden fazlasını listeler; seçimi yalnızca sso_start ve connection_id ile gönderin, identifier burada isteğe bağlıdır. Bu gereksinim altında keşif başka yöntemlere geri dönmez: kurumsal oturum açmaya ulaşılamadığında adım 503 temporarily_unavailable döndürür. E-posta alan adı, doğrulanmış alan adları için SSO isteyen bir kuruluşa aitse aynı kural geçerlidir.

Kimlik sağlayıcıdan sonra tarayıcı, oturum açma sunucusundaki /u/sso/complete adresine döner; barındırılan sayfa oturum açmayı tamamlar.

Kurumsal oturum açmayı mevcut hesapla bağlama

Kurumsal bir bağlantı e-posta adreslerini doğrulamıyorsa ve bildirdiği adres ortamın bir hesabında zaten doğrulanmışsa, kurumsal oturum açma bir oturum başlatmaz. Tarayıcı, nesnesi account_link taşıyan yeni bir işlemle barındırılan oturum açma sayfasına döner: connection_name ve bağlantı bir kuruluşa aitse organization_name. Kullanıcıya zaten bir hesabı olduğunu ve bağlantıyı bağlamak için o hesaba giriş yapması gerektiğini söyleyin; hesabı asla adıyla belirtmeyin. Bu işlemde sso_start ve magic_link sunulmaz ve identifier adımı kurumsal bir bağlantıya yönlendirmez.

Kullanıcı mevcut hesabına kendi yöntemleriyle giriş yapar; ikinci faktörü kayıtlı bir kullanıcıdan bu faktör istenir. İşlemi tamamlayan adım bir oturum açmaz: bağlantı hesaba bağlanır ve yanıt, aynı bağlantı için redirect_url bulunan ve federated_redirect durumunda yeni bir işlemdir. Üst düzey pencereyi oraya yönlendirin; kurumsal oturum açma artık olağan şekilde tamamlanır. Kurumsal oturum açma başlatılamazsa yeni işlem identifier_pending durumunda olur ve ardından olağan bir oturum açma gelir.

Başka bir hesapla, kayıtlı ikinci faktör olmadan veya bağlantı isteğinden daha eski bir oturum açmayla tamamlamak hiçbir şeyi bağlamaz ve oturum açmaz: 409 transaction_state_conflict. Süresi dolmuş (10 dakika) veya zaten kullanılmış bir bağlantı isteği 410 transaction_expired döndürür. Bir bağlantı isteği, sonucu ne olursa olsun bir kez kullanılır. Reddetmek için POST /fapi/v1/transactions/current:cancel çağrısını yapın.

Kuruluş politikası

Yetkilendirme isteği bir kuruluşa bağlıysa kuruluşun oturum açma politikası, birinci faktörden sonra ve oturum açılmadan hemen önce yeniden denetlenir:

• İstemcinin IP adresi kuruluşun izin listesinde değilse: 403 ip_not_allowed.
• İşlemin faktörleri kuruluş politikasını karşılamıyorsa (kuruluşun izin vermediği bir yöntem, eksik bir faktör ya da kuruluşun AAGUID izin listesi dışında bir güvenlik anahtarı veya Passkey): 403 no_allowed_method.
• Kuruluşun politikası okunamıyorsa: 503 temporarily_unavailable. Oturum açma kapalı kalır ve politika olmadan asla devam etmez.

Hiçbir oturum açılmaz. İşlem tamamlanırken yapılan bir red, işlem çerezini kaldırır; birinci faktörden sonraki 503 işlemi olduğu yerde bırakır ve adım yeniden denenebilir. Hata gövdesi hiçbir zaman kuruluşu, kullanıcıyı veya IP adresini adıyla belirtmez.

DPoP'ye bağlı başsız işlemler

DPoP üstbilgisiyle başlatılan bir işlem için, Idp-Csrf-Token yerine aynı anahtardan yeni bir kanıt gönderin (htm POST, htu adım URL'si); çerez kullanılmaz. İşlemi tamamlayan adım authorization_response değerini yalnızca bir kez döndürür:

{
  "state": "completed",
  "authorization_response": { "code": "<code>", "state": "<your state>", "iss": "https://example.keenauth.app" },
  "next_steps": [],
  "schema_version": 1,
  "expires_at": "2026-11-02T10:15:00Z"
}

state ile iss değerlerinin eşleştiğini doğrulayın, ardından kodu /oauth2/token adresinde code_verifier ve aynı anahtardan bir DPoP kanıtıyla değiştirin. Başka bir anahtardan gelen kanıt invalid_grant döndürür. Yetkilendirme isteği bir kodla sonuçlanamazsa (onay, yasal şartlar, bir kuruluş seçimi ya da yeni bir oturum açma gerekiyorsa veya erişim reddedilmişse), adım 403 authorization_failed döndürür ve error üyesi OAuth hata kodunu taşır; hiçbir kod verilmez.

Hatalar

Örnek

curl -X POST https://example.keenauth.app/fapi/v1/transactions/current/steps/identifier \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Idp-Csrf-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"identifier":"jane@example.com"}'

Kişisel veriler

Bu uç nokta kişisel veri içerir: son kullanıcı profili ve kimlik bilgileri. KeenAuth API'lerinde kişisel veriler neyin saklandığını, ne kadar süre tutulduğunu ve nasıl silindiğini açıklar. Hiçbir alanda özel nitelikli kişisel verileri (sağlık, biyometrik veriler, din, siyasi görüşler, cinsel yönelim) göndermeyin.