Sekans Diyagramı Örneği: PKCE ile OAuth 2.0 Yetkilendirme Kodu Akışı

Bir mimari diyagramı kimin kimle konuştuğunu gösterir. Hangi sırayla konuştuklarını ya da kimin kimi beklediğini gösteremez; oysa birçok problemde asıl hikâye o sıradır. Giriş akışları klasik örnektir: aynı beş mesaj farklı bir sırayla gelirse ortada bir güvenlik açığı vardır.

Bu rehber, sekans diyagramı gösterimini çoğu mühendisin er ya da geç karşılaştığı tek bir akış üzerinden öğretiyor: kullanıcıyı PKCE'li OAuth 2.0 yetkilendirme kodu akışıyla giriş yaptıran, ardından bir API'yi çağıran tek sayfalı bir uygulama.

Sekans diyagramı neyi gösterir

Zaman aşağı doğru akar. Her katılımcının bir yaşam çizgisi vardır: altında kesikli bir çizgi bulunan bir kutu. Her mesaj da gönderenden alıcıya giden yatay bir oktur. Yukarıdan aşağı okumak olayların sırasını verir; soldan sağa okumak her adımda kimin yer aldığını söyler.

UML 2.5.1 spesifikasyonundaki gösterim:

Akış: PKCE'li yetkilendirme kodu

Tek sayfalı bir uygulama public bir istemcidir: tarayıcıya gönderdiği her şey okunabilir, bu yüzden bir client secret saklayamaz. RFC 7636 ile tanımlanan PKCE, yetkilendirme kodunu yine de korur: uygulama, kodu takas edenin akışı başlatan örnekle aynı olduğunu kanıtlar. OAuth 2.0 güvenlik için en iyi güncel uygulama belgesi RFC 9700, public istemciler için PKCE'yi zorunlu tutar, diğer tüm istemcilere önerir ve istemcilerin implicit grant kullanmaması gerektiğini söyler.

Adımlar:

1. Kullanıcı Giriş yap'ı seçer.
2. Uygulama bir code verifier ve bir challenge oluşturur. code_verifier, 43 ile 128 karakter arasında rastgele bir dizedir. code_challenge ise S256 yöntemiyle BASE64URL(SHA256(code_verifier)) değeridir. Uygulama ayrıca rastgele bir state saklar.
3. Uygulama tarayıcıyı challenge ile birlikte yetkilendirme uç noktasına gönderir:

GET /authorize?response_type=code
    &client_id=orders-spa
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=orders.read
    &state=af0ifjsldkj
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: auth.example.com

4. Yetkilendirme sunucusu kullanıcıyı giriş yaptırır ve onay ister.
5. Kullanıcıyı geri yönlendirir: redirect_uri adresine, kısa ömürlü bir code ve aynı state ile.
6. Uygulama state değerini sakladığı değerle karşılaştırır.
7. Uygulama kodu token uç noktasında takas eder ve sakladığı verifier'ı gönderir:

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&client_id=orders-spa&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

8. Yetkilendirme sunucusu verifier'ın hash'ini alır ve sonucu 3. adımdaki challenge ile karşılaştırır. Eşleşirlerse bir erişim token'ı döndürür; yenileme token'ı veriyorsa onu da.
9. Uygulama API'yi çağırır: Authorization: Bearer <access token> başlığıyla.
10. API token'ı doğrular, örneğin imzasını, yayıncısını, hedef kitlesini, son kullanma zamanını ve kapsamını; ardından yanıt verir.

Yukarıdaki verifier ve challenge, RFC 7636'daki örnek değerlerdir; S256 hesabını kendiniz kontrol edebilirsiniz.

Diyagram

Nasıl okunur:

• Dört katılımcı tek sırada: aktör olarak kullanıcı, ardından tarayıcı uygulaması, yetkilendirme sunucusu ve API için yaşam çizgileri. Her mesaj kendi yüksekliğinde, sırayla numaralanmış yatay bir oktur.
• 2'den 7'ye kadar olan mesajlar yetkilendirme kodu akışıdır. Notlar akışı güvenli kılan iki kontrolü gösterir: uygulama yönlendirmeden sonra state değerini karşılaştırır, yetkilendirme sunucusu da verifier'ın hash'ini challenge ile karşılaştırır.
• 8 ve 9 numaralı mesajlar API çağrısıdır. Yanıtlar kesikli ve açık ok uçludur.
• opt parçası, erişim token'ının süresinin dolduğu durumu kapsar: bir 401, bir yenileme ve yeniden deneme.

Yalnızca mutlu yolu değil, hata yolunu da gösterin

Çoğu sekans diyagramı "200 OK" ile biter. İlginç hatalar dallarda yaşar; bu yüzden en azından her gün yaşanan dalı çizin. Diyagram, her biri bir koşula (guard) bağlı, birbirini dışlayan birkaç dal gösteriyorsa alt; yalnızca koşulu doğru olduğunda çalışan tek bir bölüm için opt kullanın. Buradaki yenileme bir opt: yalnızca erişim token'ının süresi dolduğunda gerçekleşir.

Yenileme dalının kendi kuralları vardır. Tarayıcı uygulamalarında yenileme token'ları genellikle bearer token'dır; bu yüzden RFC 9700 ve tarayıcı tabanlı uygulamalar için Ağustos 2026'da yayımlanan en iyi güncel uygulama belgesi RFC 10017, yetkilendirme sunucusunun bu token'ları her kullanımda yenilemesini ya da istemciye bağlamasını ve ömürlerini sınırlamasını şart koşar. 13 numaralı mesajın yeni bir yenileme token'ı döndürmesinin nedeni budur.

RFC 10017 ayrıca tarayıcı uygulamaları için mimarileri güvenliğe göre sıralar. Token'ları sunucuda tutan bir backend-for-frontend en güçlüsüdür; bu diyagramdaki gibi OAuth istemcisi olarak davranan bir tarayıcı uygulaması ise en basit olanı ve kötü amaçlı JavaScript'e en açık olanıdır. Tarayıcı modelini seçerseniz, nedenini yazmak için diyagram iyi bir yerdir.

Sekans diyagramlarında sık yapılan hatalar

• Çok fazla yaşam çizgisi. Altı yediyi geçince etiketler çakışır ve okuyucu akışın ipini kaybeder. Akışı bölün ya da iç servisleri tek bir yaşam çizgisinin arkasında toplayın.
• Etiketsiz yanıtlar. "Yanıt" hiçbir şey söylemez. Durumu ya da içeriği yazın: "code ile 302", "401 invalid_token".
• Karışık ayrıntı seviyeleri. Bir okta HTTP parametreleri, bir sonrakinde "kullanıcı mutlu" yazması iki kitleyi de şaşırtır. Bir seviye seçin ve ona sadık kalın.
• Yalnızca mutlu yol. Zaman aşımları, yeniden denemeler ve süresi dolmuş kimlik bilgileri, diyagramların emeğinin karşılığını verdiği yerlerdir.
• Her parametre. Okuyucunun kontrol etmesi gerekenleri gösterin, örneğin state, code_challenge ve code_verifier; gerisini API referansına bırakın.

Ne zaman kullanılır, ne zaman kullanılmaz

Protokoller, el sıkışmaları, yeniden denemeler, zaman aşımları, yarış durumları ve olay zaman çizelgeleri için, yani sıranın ve beklemenin önemli olduğu her şey için sekans diyagramı kullanın. Statik yapı için (bir mimari ya da C4 diyagramı), çok sayıda tüketiciye yayılan olaylar için (olay güdümlü mimari diyagramı) ve verinin güven sınırlarını nerede geçtiğine bakan güvenlik incelemeleri için (tehdit modelleme için veri akış diyagramı) başka bir diyagram kullanın.

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, tarayıcı uygulaması, yetkilendirme sunucusu ve API için de üç Yaşam çizgisi düğümünü aynı yükseklikte, tek sıra hâlinde ekleyin.
3. Her mesajı iki yaşam çizgisi arasında, yukarıdan aşağıya, numaralı bir etiketle düz bir kenar olarak çizin. Yanıtları kesikli yapın.
4. 10 ile 14 arasındaki mesajların çevresine bir Parça ekleyin; operatörünü opt, etiketini "[access token expired]" yapın.
5. Kontroller için UML paketinden Not düğümleri ekleyin: state, verifier'ın hash'i ve token doğrulama.

Örnek 5 diyagram düğümü kullanıyor ve Free planın sınırları içinde kalıyor. Archboard'un kendi MCP sunucusu da AI uygulamalarını bu akışla, PKCE'li (S256) yetkilendirme kodu grant'iyle giriş yaptırır; ayrıntılar için AI ajanlarıyla mimari diyagram nasıl oluşturulur yazısına bakın.

SSS

PKCE yalnızca mobil uygulamalar için mi? Hayır. Native uygulamalar için tasarlandı, ama RFC 9700 tek sayfalı uygulamalar dahil tüm public istemciler için zorunlu tutuyor ve gizli (confidential) istemcilere de öneriyor.

Tek sayfalı bir uygulama implicit akışı kullanmalı mı? Hayır. RFC 9700, istemcilerin implicit grant kullanmaması gerektiğini söylüyor. PKCE'li yetkilendirme kodu akışını kullanın.

OAuth 2.1 tamamlanmış bir standart mı? Bu yazının yazıldığı tarihte (Ekim 2026) değil. Hâlâ OAuth 2.0'ı ve PKCE dahil güvenlik uygulamalarını bir araya getiren bir IETF Internet-Draft'ı.

alt ile opt arasındaki fark nedir? alt, her biri bir koşula bağlı, birbirini dışlayan iki veya daha fazla dal içerir. opt ise yalnızca koşulu doğru olduğunda çalışan tek bir bölüm içerir.

Bir sekans diyagramına kaç mesaj sığar? İnsanların baktığı boyutta okunaklı kaldığı kadar; genellikle 15 ile 20 arası. Daha uzun akışları her aşama için bir diyagram olacak şekilde bölün.

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