OAuth 2.0 Authorization Code Flow, üçüncü taraf uygulamaların kullanıcı adına API kaynaklarına güvenli erişim sağlaması için tasarlanmış bir yetkilendirme akışıdır. Bu akış, özellikle sunucu tarafı uygulamalarda (web, mobil backend) tercih edilir ve refresh token desteği sayesinde uzun süreli erişim sağlar. Aşağıda bu akışı sıfırdan nasıl uygulayacağınızı adım adım bulacaksınız.
Authorization Code Flow'un Temel Bileşenleri
Akış üç ana aktörden oluşur: Kullanıcı (Kaynak Sahibi), İstemci Uygulama (sizin web/mobil uygulamanız) ve Yetkilendirme Sunucusu (örneğin Auth0, Keycloak). Yetkilendirme kodu, istemci ile kullanıcı arasında bir ara adım olarak kullanılır, böylece access token hiçbir zaman tarayıcıda açığa çıkmaz.
OAuth 2.0 Authorization Code Flow, access token'ın istemci tarafında değil, sunucu tarafında saklanmasını sağlayarak güvenliği artırır. Refresh token ise yetkilendirme sunucusunda kısa ömürlü token'lar yenilenirken kullanılır.
Adım 1: Yetkilendirme İsteği Başlatma
İstemci, kullanıcıyı yetkilendirme sunucusunun /authorize endpoint'ine yönlendirir. URL parametreleri şunları içerir:
- response_type=code (akış tipini belirtir)
- client_id (istemcinin kimliği)
- redirect_uri (yetkilendirme kodunun gönderileceği URI)
- scope (istenen izinler, örn.
openid profile email) - state (CSRF saldırılarına karşı rasgele bir değer)
Adım 2: Yetkilendirme Kodunu Alma
Kullanıcı kimlik doğrulaması yapıp izin verdiğinde, yetkilendirme sunucusu kullanıcıyı redirect_uri'ye yönlendirir ve URL'ye bir code parametresi ekler. İstemci bu kodu sunucu tarafında yakalar.
Adım 3: Access Token için Kod Değişimi
İstemci, /token endpoint'ine bir POST isteği gönderir. İstek gövdesinde şu parametreler bulunur:
- grant_type=authorization_code
- code (bir önceki adımdan alınan kod)
- redirect_uri (aynı URI)
- client_id ve client_secret (istemci kimlik doğrulaması için)
Başarılı yanıtta bir access token, opsiyonel refresh token ve token türü döner.
Adım 4: Access Token ile API İstekleri
Artık istemci, her API isteğinde Authorization: Bearer <access_token> header'ını kullanarak kaynaklara erişebilir. Access token genellikle kısa ömürlüdür (15-60 dakika).
Adım 5: Refresh Token ile Token Yenileme
Access token süresi dolduğunda, istemci refresh token'ı kullanarak /token endpoint'ine grant_type=refresh_token ile istek atar. Yanıtta yeni bir access token ve bazen yeni bir refresh token döner.
Güvenlik İpuçları
- PKCE (Proof Key for Code Exchange): Mobil ve tek sayfa uygulamalarda
code_challengevecode_verifierkullanarak yetkilendirme kodunun ele geçirilmesini önleyin. - Client Secret'i gizli tutun: Yalnızca sunucu tarafında kullanılmalı, frontend'de asla ifşa edilmemelidir.
- State parametresini doğrulayın: Otorizasyon isteğinde gönderilen state ile geri dönen state eşleşmelidir.
Örnek Uygulama: Node.js ile Express.js
Aşağıda basit bir Node.js sunucusunda Authorization Code Flow'un nasıl uygulanacağına dair bir örnek verilmiştir. Tam kaynak kodlara buradan ulaşabilirsiniz.
| Endpoint | HTTP Metodu | Açıklama |
|---|---|---|
| /auth/login | GET | Kullanıcıyı yetkilendirme sunucusuna yönlendirir |
| /auth/callback | GET | Yetkilendirme kodunu alır ve token değişimi yapar |
| /auth/refresh | POST | Refresh token ile yeni access token alır |
| /api/protected | GET | Access token doğrulaması gerektirir |
Callback işleminde axios ile token isteği yapabilir ve refresh token'ı güvenli bir HTTP-only cookie'de saklayabilirsiniz. İstemci tarafında ise alınan access token'ı React Context API ile yönetmek yaygın bir pratiktir. Bu konuda React'te Prop Drilling'den Kurtulmak: Context API ve State Management Kütüphaneleri Karşılaştırması yazımızdan faydalanabilirsiniz.
Benzer şekilde, no-code platformlarda OAuth entegrasyonu da aynı prensiplerle çalışır. Bubble'da Kullanıcı Girişi ve Yetkilendirme: OAuth Entegrasyonu ve Özel Roller Nasıl Yapılandırılır? makalesi, bu akışı görsel bir arayüzle nasıl kuracağınızı gösteriyor.
Sık Yapılan Hatalar ve Dikkat Edilmesi Gerekenler
- Token'ı istemci tarafında localStorage'a kaydetmek: XSS saldırılarına karşı risklidir. Bunun yerine HTTP-only cookie veya bellek kullanın.
- Redirect URI'yi doğrulamamak: Otorizasyon sunucusunun yalnızca kayıtlı redirect URI'lerini kabul ettiğinden emin olun.
- Refresh token'ın süresini kontrol etmemek: Refresh token da süresiz değildir; yenileme başarısız olduğunda kullanıcıyı tekrar girişe yönlendirin.
Bu rehberi uygulayarak REST API’nizde güçlü ve standartlara uygun bir yetkilendirme mekanizması kurabilirsiniz. OAuth 2.0’ın diğer akışları (Implicit, Client Credentials) farklı kullanım senaryolarına uygundur; ihtiyacınıza en uygununu seçmeyi unutmayın.
Sık Sorulan Sorular
OAuth 2.0 Authorization Code Flow ile Implicit Flow arasındaki temel fark nedir?
Authorization Code Flow'da access token sunucu tarafında alınır ve refresh token kullanılabilirken, Implicit Flow'ta token doğrudan URL fragment'te döner ve refresh token desteği yoktur. Implicit Flow artık güvenlik gerekçeleriyle önerilmez.
PKCE (Proof Key for Code Exchange) neden önemlidir?
PKCE, yetkilendirme kodunun ele geçirilmesini önlemek için mobil ve tek sayfa uygulamalarda kullanılır. İstemci, önceden bir code_challenge gönderir ve kod değişiminde bunu doğrular, böylece interception saldırılarına karşı koruma sağlar.
Access token süresi dolduktan sonra refresh token ile yeni token alırken nelere dikkat edilmeli?
Refresh token'ın da bir son kullanma tarihi olabilir. Yenileme başarısız olursa kullanıcıyı tekrar kimlik doğrulamasına yönlendirin. Ayrıca refresh token'ı güvenli bir yerde (sunucu tarafı veya HTTP-only cookie) saklayın.
Authorization Code Flow'da client_secret'i neden frontend'de kullanmamalıyız?
Client_secret, istemci uygulamanın kimliğini doğrulamak için kullanılır. Frontend'de açığa çıkması, üçüncü kişilerin uygulamanızı taklit etmesine izin verir. Bu nedenle yalnızca sunucu tarafında güvenli bir şekilde saklanmalıdır.
