OAuth 2.0 ve OpenID Connect uç noktaları

Durum: planned. Bu sayfa, planda (§13) belirtildiği şekliyle her KeenAuth ortamının protokol yüzeyini açıklar. Uç noktalar 2. aşamada geliştiriliyor ve henüz barındırılan bir ortamda kullanılabilir değil. Genel kullanıma sunulmadan önce ayrıntılar hâlâ değişebilir.

Her ortam kendi OAuth 2.0 yetkilendirme sunucusu ve OpenID Connect sağlayıcısıdır. Uç noktalar yönetim API'sinin parçası değildir: ortam sunucusunda, https://<environment-slug>.<region>.keenauth.app adresinde ya da doğrulanmış özel alan adınızda bulunurlar. Tabloda <issuer>, ortamın düzenleyicisidir; keşif belgesindeki issuer değeridir.

Uç noktalar

Uç nokta	Yöntem ve yol	İstemci kimlik doğrulaması
Keşif	`GET <issuer>/.well-known/openid-configuration` ve `GET <issuer>/.well-known/oauth-authorization-server` (RFC 8414, aynı içerik)	Yok
Anahtarlar	`GET <issuer>/.well-known/jwks.json`	Yok
Yetkilendirme	`GET` veya `POST <login host>/oauth2/authorize`	Yok (tarayıcı)
İtilmiş yetkilendirme isteği (RFC 9126)	`POST <issuer>/oauth2/par`	Gizli istemciler için gerekli; genel istemciler için `client_id`
Belirteç	`POST <issuer>/oauth2/token`	Gizli istemciler için gerekli; genel istemciler için `client_id` (DPoP isteğe bağlıdır)
Cihaz yetkilendirmesi (RFC 8628)	`POST <issuer>/oauth2/device_authorization`	Belirteç uç noktasıyla aynı
İptal (RFC 7009)	`POST <issuer>/oauth2/revoke`	Belirteç uç noktasıyla aynı
İnceleme (RFC 7662)	`POST <issuer>/oauth2/introspect`	Yalnızca gizli istemci
UserInfo	`GET` veya `POST <issuer>/oauth2/userinfo`	Bearer veya DPoP erişim belirteci
Oturumu sonlandırma	`GET` veya `POST <login host>/oauth2/logout`	Yok (`id_token_hint` veya `client_id`)

<login host>, ortamın herhangi bir giriş alan adıdır: varsayılan sunucu ya da eklenmiş bir özel alan adı. Keşif belgesi yalnızca düzenleyici sunucusunda sunulur. Başka bir giriş sunucusunda /.well-known/openid-configuration adresi, gövdesinde düzenleyici URL'si bulunan bir 404 yanıtı döndürür.

Grant türleri

Grant	Kullanım
`authorization_code`	Tarayıcı ve yerel uygulama girişi. `S256` ile PKCE gereklidir.
`refresh_token`	Belirteçleri yeniler. Her kullanımda yenileme belirteci döndürülür; eski bir belirtecin yeniden kullanılması tüm belirteç ailesini iptal eder.
`client_credentials`	Makineden makineye erişim.
`urn:ietf:params:oauth:grant-type:device_code`	Klavyesi olmayan cihazlar, örneğin bir TV veya komut satırı aracı.
`urn:ietf:params:oauth:grant-type:token-exchange`	Hizmetler arasında yetki devri ve taklit.

Örtülü akışlar (response_type=token ve id_token içeren her şey), kaynak sahibi parola grant'ı ve hibrit yanıt türleri şimdi ya da daha sonra desteklenmeyecektir. RFC 9700 ilk ikisini yasaklamaktadır.

Cihaz yetkilendirmesi

Tarayıcısı olmayan bir cihaz, akışı POST <issuer>/oauth2/device_authorization ile başlatır. Yalnızca device veya native türündeki ve cihaz grant'ını açıkça listeleyen uygulamalar bunu kullanabilir. Yanıt bir device_code, bir user_code ve bir doğrulama adresi içerir. Kullanıcı adresi başka bir cihazda açar, giriş yapar ve onaylar. Bu sırada cihaz, grant_type=urn:ietf:params:oauth:grant-type:device_code ile belirteç uç noktasını yoklar. user_code 8 karakterlidir ve XXXX-XXXX biçiminde gösterilir. Bir cihaz kodu 10 dakika geçerlidir ve yalnızca bir kez çalışır. Cihaz en fazla her 5 saniyede bir yoklama yapar; daha sık yoklamaya slow_down yanıtı verilir ve bu, aralığa 5 saniye ekler. verification_uri adresi https://<login host>/u/device biçimindedir ve onaylamadan önce kullanıcıya uygulama, istenen kapsamlar ve isteği başlatan cihazın ülkesi gösterilir.

Güvenlik kuralları

Ortam, OAuth 2.0 Güvenlik En İyi Güncel Uygulama belgesini (RFC 9700) istisnasız uygular:

Yönlendirme URI'si, kayıtlı bir URI ile bayt bayt eşleşmelidir. Joker karakter yoktur.
PKCE yalnızca S256 kabul eder; plain her zaman reddedilir. PKCE genel istemciler için zorunludur ve her uygulama için varsayılan olarak açıktır. Gizli bir web uygulaması bunu ayarlarında kapatabilir; ancak bu durumda ortam yine de nonce gerektiriyorsa.
Resmi SDK'lar 128 bitlik bir state ve bir nonce gönderir ve dönüşte ikisini de denetler.
Bir yetkilendirme kodu 60 saniye geçerlidir ve yalnızca bir kez çalışır. Kullanılmış bir kod sunulursa invalid_grant döner ve ilk kullanımın ürettiği yenileme belirteçleri ile erişim belirteci iptal edilir.
İtilmiş yetkilendirme istekleri, istek parametrelerini tarayıcının adres çubuğunun dışında tutar. Her pakette kullanılabilir; require_par ayarı ise bunları bir uygulama ya da tüm ortam için zorunlu kılar.
Yenileme belirteçleri her kullanımda döndürülür ve yeniden kullanım tespiti aileyi iptal eder.
DPoP (RFC 9449), bir erişim belirtecini istemcinin tuttuğu bir anahtara bağlar. API'nizde bağlı belirteçleri doğrulamak için API'nizde belirteçleri doğrulama sayfasına bakın.

Oturumlar ve çıkış

Başarılı bir girişten sonra ortam, giriş sunucusunda HttpOnly bir çerezde tek bir tek oturum açma oturumu tutar. Aynı ortamdaki uygulamalar bu oturumu yeniden kullanır; bu nedenle ikinci bir uygulama, ilkası daha güçlü ya da daha yeni bir kimlik doğrulama gerektirmedikçe parola istemez. Kodunuz çerezi hiçbir zaman görmez; yalnızca yetkilendirme yanıtını görür.

Oturumu sonlandırma uç noktası (OpenID Connect RP-Initiated Logout 1.0) bu oturumu sonlandırır, oturuma ait yenileme belirteçlerini iptal eder ve arka kanal çıkış adresi kaydettiren uygulamaları bilgilendirir. Bir kullanıcının oturumlarını arka ucunuzdan listelemek ya da iptal etmek için yönetim API'sinin oturum uç noktalarını kullanın.

Kullanıcı bir kurumsal bağlantı üzerinden giriş yaptıysa, kimlik sağlayıcısında da çıkış yaptırmak için oturumu sonlandırma isteğine federated=true ekleyin. Buradaki oturum önce sonlandırılır; ardından tarayıcı kimlik sağlayıcısının çıkış adresine (SAML tek oturum kapatma ya da OpenID sağlayıcısının oturumu sonlandırma uç noktası) gider ve post_logout_redirect_uri adresine geri döner. Bu yalnızca bağlantıda kimlik sağlayıcı çıkışı açıksa ve sağlayıcı bir çıkış adresi yayımlıyorsa gerçekleşir. Aksi halde ya da sağlayıcıya ulaşılamazsa istek, parametre olmadan olduğu gibi çalışır. Kimlik sağlayıcıda çıkış yapmak, kullanıcının onu kullanan diğer uygulamalarındaki oturumları da sonlandırabilir.