REST API Kimlik Doğrulama Nasıl Yapılır?

💡 Özet (TL;DR):

• Stateless Yapı: İyi bir REST API'de sunucu tarafında oturum (session) bilgisi tutulmaz; her istek, kendini doğrulayacak tüm bilgiyi (token, API key vb.) beraberinde taşır.
• Kimlik Doğrulama Yöntemleri:
  • Basic Auth: En basit ama güvensiz olanıdır; kullanıcı adı/şifreyi Base64 ile kodlayıp gönderir.
  • Bearer (Token-based): İstek başlığında bir token (genellikle JWT) taşınır; mobil ve modern web uygulamalarında standarttır.
  • API Keys: Üçüncü taraf servis entegrasyonlarında tercih edilir.
  • OAuth 2.0 / OIDC: Yetkilendirme ve harici kimlik doğrulama sunucuları için kullanılır.

Bu yazı RESTful API Tasarım İncelikleri serisinin bir parçası niteliğindedir. Eğer okumadıysanız önce serinin diğer yazılarını okumanızı tavsiye ederim.

• REST API Temelleri
• REST API Çıktı Formatı Ne Olmalı?
• REST API URI Yapısı Nasıl Olmalı?
• REST API HATEOAS Kavramı Nedir? (Bu diziye sonradan eklendi)
• REST API Kimlik Doğrulama Nasıl Yapılır? (Authentication)
• REST API Hata Yönetimi Nasıl Yapılır? (Error Handling)
• REST API Güvenliği Nasıl Sağlanır? (Security)
• REST API Dokümantasyon (Documentation) ve Testi Nasıl Yapılır?
• Örnek REST API Projesi

Bu Yazı Dizisi ve Muhtemel Sorular Hakkında

Bu yazı dizisine başlarken bu kadar zor olacağını tahmin etmiyordum. Sadece tek bir yazı olarak başlamışken, bir yazı dizisine dönüştürmem gerektiğini fark ettim; fakat yazmaya devam ettikçe bunun aslında kitap yazılacak bir konu olduğunu görüyorum. Basitleştirmeye çalıştıkça bilgi yetersiz kalırken, detaya girdikçe de konu dallanıp budaklanıyor ve karmaşık hale geliyor.

Konuya iyi bir REST API uygulamasının Stateless olması gerektiğini söyleyerek başlayacaktım, sonra kendi kendime "iyi ama önce stateless ne demek bunu açıklamak gerekir" dedim. Konuyu hem dağıtmadan hem de eksik nokta bırakmadan anlatmak çok güç. Bu nedenle eksik bulduğunuz noktalar veya sorularınız olursa lütfen sosyal medyadan bana ulaşın.

STATEFUL ve STATELESS Ne Demek?

Stateless tanımını anlatmanın en iyi yolu Stateful nedir onu anlatmak olacak. Aslında her iki tanım da "state" kelimesinden geliyor.

Stateful ve stateless terimleri sadece REST API veya yazılım değil, DevOps ve sunucu sistemleri için de önemli bir bilgidir.

State, bir sistemin veya koşulun belirli bir andaki durumunu tanımlar. (Zaten state kelimesinin Türkçe karşılığı da durumdur). Örneğin odanızdaki lambanın iki durumu (state) var: açık ya da kapalı. Bu lambayı kontrol eden bir kodun stateless olması için lambanın herhangi bir andaki durumunu bilmiyor olması gerekir. Stateful bir sistem ise tam tersi, herhangi bir anda lamba açık mı kapalı mı bunu bilir.

Sanal bir sistem kuralım. Bu sistemde herkesin kendine ait bir odası olsun. Yüz binlerce kişi canı istediği zaman odasının ışığını açsın veya kapatsın. Sistemi stateless kurarsak sunucu herhangi bir odanın ışığı o anda açık mı kapalı mı bilmeyecektir. Her istemci kendi odasının son durumunu bilmekten sorumludur. Sunucuya "ışığı aç" veya "ışığı kapat" isteği gönderir. Böylece sunucu tarafında yüz binlerce odanın ışığı açık mı/kapalı mı takip etmeyiz. Aksi durumda bu bilgiyi tutmak zorunda olduğumuz gibi, ne zaman gereksiz hale geldiğini de bilemeyiz.

Yazıyı stateless ve stateful konulu bir yazıya çevirmemek için daha fazla uzatmak istemiyorum ama (istisnalar hariç) çoğu zaman stateless bir yapı inşa etmek (eğer mümkünse) daha sorunsuz ve doğru bir çözüm olacaktır.

REST API'nin Stateless Olması Ne Demek?

İyi bir REST API tanım gereği stateless olmalı ve sunucu tarafında bir oturum (session) bilgisi tutmamalıdır. Bir isteğin anlaşılması ve doğrulanması için gereken tüm bilgi istemci tarafından sunucuya gönderilmelidir. Bu sınırlama, sunucu tarafında hiçbir bilgi olmayacağı veya o işlem için kullanılan tüm bilginin istemci tarafından gönderileceği anlamına gelmez. Ancak sunucu, oturum veya bir önceki durumla ilgili bir bilgiyi hafızasında tutmaz.

Bunu daha rahat anlamak için sayfalama örneğini düşünebiliriz. İstemci bir sorgu gönderecekse o sorgunun kaçıncı sayfasını istediğini belirtmelidir. Sunucu tarafında "bir önceki istekte 5. sayfa verilmişti, şimdi sıra 6. sayfada" bilgisi tutulmaz.

Öte yandan sunucu tarafında o anki bağlantının 123 ID'li kullanıcıdan geldiği de tutulmaz. Sunucu kendisine gelen isteğin 123 ID'li kullanıcıdan geldiğini isteğin kendisinden tespit edebilmelidir. Peki nasıl?

Sonunda Geldik Kimlik Doğrulama Kısmına

Gerekli/gereksiz bir sürü bilginin ardından geldik kimlik doğrulamayı nasıl yapacağımıza; gönderdiğimiz istekte ben "ID=123" veya "username=evrenbal" nasıl diyeceğimize. Bu tabii ki genellikle bu kadar kolay değildir (HTTP Basic Authentication yöntemi hariç).

Hangi yöntem kullanılırsa kullanılsın HTTPS üzerinden kullanılması önemlidir. REST API tasarımında güvenlik için ilk söylenecek şey HTTPS kullanmak olsa gerek.

En çok kullanılan 4 yöntemi inceleyelim:

1. HTTP Authentication

Basic Authentication

HTTP protokolünün en eski ve en temel yöntemi. Mevcut yöntemler arasında en kolayı ama belki de en güvensiz olanıdır. İsteğin başlık bölümünde (Request Header) Base64 ile kodlanmış kullanıcı adı ve şifreyi göndermeye dayanır. Base64 bir şifreleme yöntemi olmadığı için bilgilerin açık olarak gönderildiğini kabul edebiliriz.

Authorization: Basic ZXZyZW46YmFs

Bearer Token

Bearer, İngilizcede "Hamili/Taşıyıcısı" anlamına gelir. Bir nevi "bu kodu taşıyan kişi hamili yakınımdır, içeriye alabilirsin" demektir. İsteğin gönderim şekli olarak Basic Authentication'a benzer bir yapıya sahip olan Bearer yönteminde fark, kullanıcı adı şifre yerine bir 'token' gönderiliyor olmasıdır.

Authorization: Bearer <token>

Bearer yöntemi ve yanında token oluşturma/doğrulama için JWT (JSON Web Token) kullanıldığında hızlı ve pratik bir çözüm elde edilmiş olur. Ben bu ikilinin ileri seviye güvenlik gerektirmeyen çoğu uygulama için yeterli olduğunu düşünüyorum. Fakat JWT kullanacaksanız daha önce yazmış olduğum "JWT Güvenli Derken Güvenlik Açığı Oluşturmayın" başlıklı yazımı okumanızı tavsiye ederim.

2. API Anahtarları (API Keys)

Bu yöntem son kullanıcı uygulamalarından ziyade, üçüncü parti entegrasyonlar veya sistemler arası (M2M) haberleşmeler için kullanışlıdır. İsteğin sunucuya gönderilmesi Bearer yöntemine benzerdir. Fark, API anahtarının oluşturulması ve istemci tarafında kaydedilmesi sürecindedir. O kullanıcıya servisinizi kullanabileceği benzersiz bir API anahtarı oluşturur ve o anahtarı kendi sisteminde/kodunda tanımlamasını istersiniz. Örneğin bu blog için çeşitli servislerin API anahtarlarını WordPress yönetim panelinde ilgili alanlara girerek blogumun o servisleri kullanabilmesini sağlıyorum.

Fakat son kullanıcıya hitap eden bir mobil uygulamada, sunucudan token'ın alınması, istemcide saklanması, istek başlığında Bearer yöntemiyle gönderilmesi gibi süreçleri bizim yönetmemiz gerekir.

3. OAuth 2.0 ve OpenID Connect (OIDC)

OAuth 2.0 kimlik doğrulamasından çok bir erişim yetkilendirmesi (authorization) protokolüdür. Örneğin bir web sitesine Facebook hesabınızı bağladığınızda, Facebook'un o siteye "isminiz ve profil resminize ulaşma yetkisi vermesini" onaylamış, yani "bu siteye şu bilgilere ulaşabilmesi için bir erişim token'ı (access token) ver" demiş olursunuz.

Sizin API'nızın da başka sitelerle entegre çalışabilmesi gerekiyorsa bunu OAuth 2.0 uygulaması ile çözebilirsiniz. Amacınız sunucunuz ve istemci arasında doğrudan kimlik doğrulaması yapmaksa bunu OAuth 2.0'ı temel alan OpenID Connect ile çözmelisiniz.

OpenID Connect, bir doğrulama sunucusunun istemciyi doğrulamasını sağlar. Uygulamanız ve istemci arasında yine ekstra bir sunucu vardır ama bu sunucunun işi istemcinin kimlik doğrulamasını yaparak gerekli temel bilgileri sizin uygulamanızla paylaşmaktır.

OpenID kimlik doğrulaması için üçüncü parti bir OpenID Provider kullanılabilir veya OpenID web sitesindeki çeşitli kütüphanelerle kendi doğrulama çözümünüzü oluşturabilirsiniz.

REST API Kimlik Doğrulama Yöntemleri Karşılaştırması

Hangi Yöntemi Tercih Etmeliyiz?

Bu yöntemler arasında tek bir doğru olmadığı gibi yanlış olan bir yöntem de yoktur. Kullanım ve güvenlik ihtiyaçlarına göre hangi yöntemi kullanacağınız değişiklik gösterecektir. Dikkat ederseniz her yöntem farklı bir ihtiyaca hizmet eder.

Yazı dizisinin bir sonraki bölümünde hata yönetiminin nasıl yapılması gerektiğini inceleyeceğiz.

REST API Hata Yönetimi

Bu Yazıda Yapılan Değişiklikler

• 11.05.2022: Yazı özeti düzenlendi.
• 20.06.2026: REST API terimleri standartlaştırıldı, imla hataları düzeltildi, TL;DR özet ve yöntem karşılaştırma tablosu eklendi.