OAuth 2.0 Akış Diyagramı: Adım Adım PKCE ile Authorization Code

OAuth 2.0'ı kullanmak kolay, zihinde canlandırmak zordur. Bir giriş düğmesi üç ya da dört taraf arasında yönlendirmeleri tetikler; her biri birbirine benzeyen adlarla parametreler taşır ve hataların çoğu, bir tarafın yapması gereken bir kontrolü atlamasından kaynaklanır. Kimin kime neyi hangi sırayla gönderdiğini görmenin en net yolu bir sekans diyagramıdır.

Bu yazı, bugün neredeyse her istemci için kullanmanız gereken akışı çiziyor: PKCE ile authorization code grant. Her adımı anlatıyor, her tarafın neyi kontrol ettiğini açıklıyor ve güncel yönergelerin bırakmanızı söylediği eski akışları listeliyor.

Dört taraf

İstemci kullanıcının şifresini asla görmez. OAuth'un amacı budur: yetkilendirme sunucusu kullanıcının kimliğini doğrular ve istemciye kapsamı ve ömrü sınırlı bir token verir.

2026'da hangi akış

Orijinal OAuth 2.0 çerçevesi, RFC 6749, birkaç grant tanımladı. Ocak 2025'te yayımlanan OAuth 2.0 Security Best Current Practice, RFC 9700, seçimi daraltır:

• PKCE ile authorization code, her tür istemciden kullanıcı girişi için. Herkese açık istemciler (mobil uygulamalar, tek sayfalı uygulamalar) PKCE kullanmak zorundadır; sunucu tarafında sırrı olan gizli istemciler için önerilir.
• Implicit grant değil. Token'ları tarayıcı yönlendirmesinde döndürür ve orada sızabilirler; istemciler onu kullanmamalıdır.
• Resource owner password credentials grant değil. Kullanıcının şifresini istemciye vermek amacı boşa çıkarır; BCP kullanılmaması gerektiğini söyler.
• Client credentials, kullanıcının dahil olmadığı servisten servise çağrılar için.

OAuth 2.1 taslağı bu kuralları tek bir belgede toplar; bu yüzden yeni kütüphaneler giderek bunları varsayar.

Tek paragrafta PKCE

Proof Key for Code Exchange, RFC 7636, authorization code'u korur. Yönlendirmeden önce istemci rastgele bir code_verifier (43 ile 128 karakter arası) oluşturur ve yalnızca onun SHA-256 hash'ini, yani code_challenge değerini code_challenge_method=S256 ile gönderir. İstemci daha sonra kodu token'larla takas ederken verifier'ı gönderir. Sunucu onu hash'ler ve karşılaştırır. Kodu ele geçiren bir saldırgan, istemciden hiç çıkmayan verifier olmadan onu kullanamaz.

Adım adım akış

1. Kullanıcı Giriş yap'a tıklar. İstemci state (kullanıcının oturumuna bağlı rastgele bir değer) ile PKCE verifier ve challenge'ı üretir.
2. İstemci /authorize adresine yönlendirir; yanında response_type=code, client_id, kayıtlı redirect_uri, istenen scope, state ve code challenge vardır.
3. Yetkilendirme sunucusu kendi giriş ve onay sayfasını gösterir. İstemci işin içinde değildir; bu, sunucunun alan adında olur.
4. Kullanıcı giriş yapar, gerekiyorsa MFA'yı tamamlar ve kapsamlara onay verir.
5. Sunucu, tam olarak kayıtlı redirect_uri adresine geri yönlendirir; yanında kısa ömürlü, tek kullanımlık bir code ve aynı state vardır. İstemci state değerinin gönderdiğiyle eşleştiğini kontrol eder; eşleşmiyorsa durur. RFC 6749 kod ömrünün en fazla 10 dakika olmasını önerir.
6. İstemci /token adresine POST yapar; kodu, yönlendirme URI'sini ve code_verifier değerini (gizli bir istemciyse kendi istemci kimlik doğrulamasını da) gönderir. Bu bir yönlendirme değil, arka kanal isteğidir.
7. Sunucu token'ları döndürür: bir access token, genellikle bir refresh token ve OpenID Connect kullanıyorsanız bir ID token.
8. İstemci API'yi çağırır; Authorization: Bearer <access token> ile.
9. API token'ı doğrular ve yanıt verir. JWT access token'larda imzayı, yayıncıyı, hedef kitleyi, süreyi ve kapsamları yerel olarak kontrol eder; opak token'larda yetkilendirme sunucusunun introspection endpoint'ine sorar.
10. Access token'ın süresi dolduğunda, istemci refresh token'ı /token adresine POST eder.
11. Sunucu yeni bir access token döndürür, herkese açık istemciler için yeni bir refresh token da. RFC 9700, herkese açık istemcilerin refresh token'larının ya göndericiye bağlı olmasını ya da döndürülmesini şart koşar; böylece çalınan bir refresh token, taraflardan biri onu bir kez kullandıktan sonra çalışmaz.

Sekans diyagramı

Nasıl okunur:

• Soldan sağa dört yaşam çizgisi: kullanıcı, istemci uygulama, yetkilendirme sunucusu ve API.
• Dolu uçlu düz oklar isteklerdir; kesikli oklar yanıtlar ve geri yönlendirmelerdir.
• 2'den 5'e kadar adımlar tarayıcı üzerinden ön kanal yönlendirmeleridir; 6. adım PKCE'nin işe yaradığı arka kanal token isteğidir.
• En alttaki opt fragmenti yalnızca access token'ın süresi dolduğunda çalışır.
• Markdown bloğu her tarafın yaptığı kontrolleri listeler; gerçek hataların çoğu buralarda saklanır.

Gözden geçirmelerde çıkan hatalar

• state kontrolü yapmamak. Bu olmadan bir saldırgan, kurbanın tarayıcısında kendi hesabıyla bir giriş akışını tamamlayabilir.
• Gevşek yönlendirme URI eşleştirmesi. Sunucu kayıtlı URI ile birebir karşılaştırma yapmalıdır; önek ya da joker karakterle eşleştirme kod hırsızlığına yol açar.
• Tek sayfalı uygulamanın local storage'ında token'lar. Herhangi bir betik enjeksiyonu onları okuyabilir. Birçok ekip SPA'nın önüne token'ları tutan ve tarayıcıya bir oturum çerezi veren küçük bir backend (backend-for-frontend) koyar.
• Geçerli her token'ı kabul eden API'ler. Hedef kitleyi kontrol edin; yoksa başka bir API için verilmiş bir token sizinkinde de çalışır.
• Mobil uygulamalarda gömülü web görünümleri. RFC 8252, yerel uygulamaların sistem tarayıcısını kullanması gerektiğini söyler; böylece uygulama kullanıcının kimlik bilgilerini göremez.
• Yenileme mantığından kaçmak için uzun ömürlü access token'lar. Access token'ları kısa tutun ve yenileyin; o zaman iptal hızlı etki eder.

Bir OAuth diyagramına neler çizilmeli

• Her taraf kendi yaşam çizgisi olarak; istemcinizin bir backend'i varsa tarayıcı da dahil.
• Ön kanal ve arka kanal ayırt edilmiş olarak, çünkü güvenlik özellikleri farklıdır.
• Okların üzerinde parametre adları: state, code_challenge, code, code_verifier. Gözden geçirenler bunları arar.
• Kimin neyi doğruladığı. Tasarım kontrollerdir; oklar yalnızca veriyi taşır.

Daha geniş güvenlik resmini çiziyorsanız, zero trust mimari diyagramı kimlik sağlayıcının diğer kontrollerin arasında nerede durduğunu gösterir; API ağ geçidi mimari diyagramı da token'ları uçta bir kez doğrulamayı anlatır. Sekans diyagramı örneği burada kullanılan gösterimi daha ayrıntılı açıklar.

Archboard'da oluşturun

1. Google ya da GitHub ile giriş yapın ve bir diyagram oluşturun.
2. Sekans paketinden kullanıcı için bir Aktör, istemci uygulama, yetkilendirme sunucusu ve API için üç Yaşam çizgisi düğümü ekleyin; hepsi aynı yükseklikte, tek bir sırada olsun.
3. Her mesajı yaşam çizgileri arasında yukarıdan aşağıya düz bir kenar olarak çizin ve parametre adlarını etikete yazın. Yanıtlar ve yönlendirmeler için açık ok uçlu kesikli kenarlar kullanın.
4. Yenileme adımlarının çevresine opt operatörlü bir Parça ekleyin.
5. Her tarafın yaptığı kontrolleri içeren, Temel paketinden bir Markdown bloğu ekleyin.

Örnek 6 diyagram düğümü kullanıyor ve Free planın sınırları içinde kalıyor.

SSS

OAuth 2.0 ile OpenID Connect arasındaki fark nedir? OAuth 2.0 yetki devriyle ilgilidir: istemci bir API'yi çağırmak için token alır. OpenID Connect bunun üzerine kimlik ekler: istemciye kullanıcının kim olduğunu söyleyen bir ID token ve standart bir kullanıcı bilgisi endpoint'i.

Uygulamamın bir client secret'ı varsa PKCE gerekir mi? RFC 9700 gizli istemciler için de önerir. Kod enjeksiyonuna karşı korur ve her iki tarafta bir parametreye mal olur.

Implicit grant hâlâ kullanılmalı mı? Hayır. Güncel en iyi uygulama, istemcilerin onu kullanmaması gerektiğini söyler. Onun yerine tek sayfalı uygulamalarda da PKCE ile authorization code grant kullanın.

Tek sayfalı bir uygulama token'ları nerede saklamalı? Tercihen hiç tarayıcıda değil: bir backend-for-frontend token'ları sunucu tarafında tutup tarayıcıya güvenli bir oturum çerezi verebilir. Token'ların tarayıcıda durması şartsa onları bellekte tutun, access token'ları kısa tutun ve refresh token döndürme kullanın.

API bir access token'ı nasıl doğrular? JWT access token'larda, yetkilendirme sunucusunun yayımladığı anahtarlarla imzayı ve ayrıca yayıncı, hedef kitle, süre ve kapsamı kontrol ederek. Opak token'larda introspection endpoint'ini çağırarak.

Ücretsiz başlayın — tek kullanıcı, kredi kartı gerekmez.