Apidog'da OAuth 2.0 API'leri Nasıl Test Edilir (Yetkilendirme Kodu, İstemci Kimlik Bilgileri ve Token Yenileme)

Her API ekibi aynı duvara çarpar: Uç noktalar tek başına çalışır, ancak OAuth 2.0 devreye girdiğinde test paketinin yarısı 401 hatası vermeye başlar. Yetkilendirme sunucuları, kısa ömürlü erişim jetonları ve kapsamlarla uğraşırken, cURL yanıtından jetonu elle Authorization başlığına kopyalamak hızla yorucu hale gelir.

Apidog'u bugün deneyin

Çözüm, testlerde kimlik doğrulamayı atlamak değil; jeton yönetimini test kurulumunun bir parçası haline getirmektir. Bu kılavuzda iki temel OAuth 2.0 akışını Apidog ile yapılandıracağız:

• Kullanıcı adına çalışan API'ler için PKCE'li Yetkilendirme Kodu akışı
• Makineden makineye çağrılar için İstemci Kimlik Bilgileri akışı

Tüm yetkilendirme türlerini karşılaştırmak için OAuth 2.0 akışlarına genel bakış makalesine göz atabilirsiniz.

API Testleri İçin Hangi OAuth Akışını Kullanmalısınız?

Seçimi şu soruyla yapın:

API bir kullanıcı adına mı, yoksa bir hizmet adına mı hareket ediyor?

PKCE ile Yetkilendirme Kodu Akışı

Yetkilendirme Kodu akışı, kullanıcıya bağlı bir jeton almak için standart yöntemdir:

1. İstemci kullanıcıyı yetkilendirme sunucusuna yönlendirir.
2. Kullanıcı giriş yapar ve onay verir.
3. Sunucu istemciyi tek kullanımlık bir kodla geri yönlendirir.
4. İstemci bu kodu erişim jetonuyla değiştirir.

Bu akış RFC 6749 bölüm 4.1 içinde tanımlanır.

PKCE (Proof Key for Code Exchange), yetkilendirme isteğinde gönderilen hash'lenmiş bir meydan okuma ile sonradan sunulan özgün doğrulayıcıyı eşleştirir. Böylece kodu ele geçiren bir saldırgan onu kullanamaz. PKCE mobil uygulamalar için geliştirilmiş olsa da oauth.net güncel olarak her yetkilendirme kodu değişimi için PKCE'yi önermektedir.

Şu durumlarda bu akışı kullanın:

• GET /orders yalnızca oturum açmış kullanıcının siparişlerini döndürüyorsa
• Yönetici uç noktaları role göre korunuyorsa
• Kullanıcı başına hız limitleri uygulanıyorsa

İstemci Kimlik Bilgileri Akışı

İstemci Kimlik Bilgileri akışı kullanıcı etkileşimini tamamen atlar. İstemci kendi kimliği ve sırrıyla doğrulanır ve uygulamanın kendisini temsil eden bir jeton alır:

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=orders_service \
  -d [REDACTED CREDENTIAL] \
  -d scope="orders:read orders:write"

Tarayıcı, yönlendirme veya insan müdahalesi gerekmediği için bu akış şu senaryolarda kullanılır:

• Dahili mikro hizmetler
• Cron işleri
• Dağıtım API'sini çağıran CI ardışık düzenleri
• Kullanıcı kimliğinin test edilen davranış olmadığı otomatik testler

Makineden makineye çağrılarda, test ortamınız test istemcisi sağlamanıza izin veriyorsa İstemci Kimlik Bilgileri akışını tercih edin.

Apidog'da OAuth 2.0 Kimlik Doğrulamasını Yapılandırma

Apidog, OAuth 2.0'ı istek veya klasör düzeyinde yapılandırılabilen bir kimlik doğrulama türü olarak destekler. Platform:

• Jeton alır
• İsteklere Bearer [REDACTED] ekler
• Jetonları saklar
• Yenileme jetonlarını kullanarak süresi dolan erişim jetonlarını yeniler

Desteklenen yetkilendirme türleri arasında Yetkilendirme Kodu, PKCE'li Yetkilendirme Kodu, İstemci Kimlik Bilgileri, Parola Kimlik Bilgileri ve Örtük akış bulunur.

Aşağıdaki örneklerde kurgusal bir sipariş yönetimi API'si kullanacağız.

İstemci Kimlik Bilgileri Kurulumu

İsteği veya tercihen klasörü açın:

1. Kimlik Doğrulama sekmesine gidin.
2. Kimlik doğrulama türü olarak OAuth 2.0 seçin.
3. Yetkilendirme türünü İstemci Kimlik Bilgileri olarak ayarlayın.
4. Aşağıdaki alanları doldurun:

• Erişim Jetonu URL'si: https://auth.example.com/oauth/token
• İstemci Kimliği: orders_service
• İstemci Sırrı: Sağladığınız sır
• Kapsam: orders:read orders:write

Apidog, istemci kimlik bilgilerini iki şekilde gönderebilir:

• Basic Auth başlığıyla
• İstek gövdesinde

Yetkilendirme sunucunuzun beklediği yöntemi seçin. Auth0 ve Okta her iki yöntemi de kabul edebilirken bazı şirket içi sunucular yalnızca gövdeyi ayrıştırır.

Jeton Al seçeneğine tıkladığınızda Apidog:

1. Jeton uç noktasını çağırır.
2. Yanıtı saklar.
3. Jetonu geçerlilik süresiyle birlikte gösterir.
4. Sonraki isteklerde Authorization: Bearer <token> başlığını otomatik ekler.

Bu yaklaşımda manuel kopyalama veya {{token}} değişkeni oluşturma gerekmez.

PKCE ile Yetkilendirme Kodu Kurulumu

Kullanıcı bağlamını test etmek için yetkilendirme türü olarak Yetkilendirme Kodu (PKCE ile) seçin. Apidog'da PKCE ayrı bir yetkilendirme seçeneğidir; yalnızca bir onay kutusu değildir.

Gerekli alanlar:

• Yetkilendirme URL'si: https://auth.example.com/oauth/authorize
• Erişim Jetonu URL'si: https://auth.example.com/oauth/token
• Geri Çağırma URL'si: Sağlayıcınıza kayıtlı yönlendirme URI'si
• İstemci Kimliği ve İstemci Sırrı: OAuth uygulama kaydınızdan alınan değerler

Jeton Al seçeneğine tıklayın. Apidog giriş sayfasını açar. Test kullanıcınızla giriş yapıp onay verdikten sonra jeton Apidog'a döner ve yönetilen kimlik doğrulama deposuna kaydedilir.

Sağlayıcınız erişim jetonuna ek olarak OpenID Connect ID jetonu döndürüyorsa, Kullanılan Jeton Türü seçeneği hangi jetonun isteklere ekleneceğini belirler. Bu seçenek, API'nin ID jetonunu doğruladığı senaryolarda kullanışlıdır.

Her rol için ayrı test kullanıcısı oluşturun:

• Alıcı
• Yönetici
• Salt okunur denetçi

Her kullanıcı adına jeton alıp aynı senaryoyu yeniden çalıştırmak, rol tabanlı erişim kurallarını hızlıca doğrulamanızı sağlar.

Jeton Yeniden Kullanımı ve Otomatik Yenileme

Erişim jetonlarının süresi çoğunlukla bir saat içinde dolar. Manuel yenileme yapılmadığında bu durum başarısız test çalıştırmalarına ve gereksiz yeniden yapılandırmaya neden olur.

Yetkilendirme sunucusu yenileme jetonu verdiğinde Apidog erişim jetonunu otomatik olarak yenileyebilir. Saklanan jetonun süresi dolduğunda:

1. Apidog yenileme jetonunu kullanır.
2. Yeni erişim jetonunu alır.
3. İstek gönderilmeden önce eski jetonu yenisiyle değiştirir.

Bu özellik Apidog'un Haziran güncellemesinde sunuldu. Sağlayıcınız yenileme için ayrı bir uç nokta kullanıyorsa, gelişmiş ayarlarda özel yenileme jetonu URL'si belirleyebilirsiniz.

İstemci Kimlik Bilgileri akışında birçok sunucu yenileme jetonu döndürmez. Spesifikasyon buna izin verir; istemci gerektiğinde yeniden kimlik doğrulaması yapabilir. Bu durumda Jeton Al seçeneğini yeniden çalıştırmak yeterlidir. Planlı veya CI çalıştırmaları da her çalıştırmanın başında yeni bir jeton isteyebilir.

Klasör Düzeyinde Kimlik Doğrulamayı Devralma

Her istekte OAuth yapılandırmak yerine klasör düzeyinde kimlik doğrulama ayarlayın.

Örneğin, Siparişler API'si klasöründe OAuth 2.0 yapılandırmasını bir kez tanımladığınızda, içindeki tüm istekler aynı yapılandırmayı ve yönetilen jetonu devralır. Buna daha sonra eklenen istekler de dahildir.

Bu özellikle çok adımlı senaryolarda önemlidir:

POST /carts
POST /carts/{id}/items
POST /orders

Klasör düzeyinde kimlik doğrulamayla:

• Tüm adımlar aynı jetonu kullanır.
• Senaryo sırasında jetonun süresi dolarsa otomatik yenileme devreye girer.
• İstemci sırrı değiştiğinde tek bir klasörü güncellemeniz yeterlidir.

İstekler, ebeveyn klasörün kimlik doğrulamasını geçersiz kılabilir. Bu özellik, negatif testler için gereklidir.

OAuth Hata Yollarını Test Etme

Başarılı yol testleri jeton hattının çalıştığını gösterir. Hata yolu testleri ise API'nizin kimlik doğrulamayı doğru uyguladığını kanıtlar.

API anahtarları ve taşıyıcı jetonların karşılaştırması, beklenen durum kodlarını anlamak için yararlı bir başvuru kaynağıdır.

Süresi Dolmuş veya Eksik Jeton: 401 Bekleyin

Senaryodaki bir isteği çoğaltın ve klasörden devralınan kimlik doğrulamayı geçersiz kılın:

• Kimlik doğrulama olmadan gönderin veya
• Bearer [REDACTED]_not_rotate gibi geçersiz bir jeton kullanın.

Şunları doğrulayın:

• Durum kodu 401
• WWW-Authenticate yanıt başlığının bulunması
• Yanıt gövdesinin yığın izlerini veya dahili ana bilgisayar adlarını sızdırmaması

Burada 200 kritik bir güvenlik hatasıdır. 403 ise tasarım sorunu olabilir; sunucu kimlik doğrulanamayan istemciyle kimliği doğrulanmış ancak yetkisi olmayan istemciyi ayırt etmelidir.

Yanlış Kapsam: 403 Bekleyin

Yalnızca orders:read kapsamına sahip ikinci bir test istemcisi oluşturun. Bu istemciyle jeton alıp POST /orders gibi yazma gerektiren bir uç noktayı çağırın.

Şunları doğrulayın:

• Durum kodu 403
• API'niz RFC 6750'yi uyguluyorsa, WWW-Authenticate başlığında error="insufficient_scope" bulunması

Bu test, bazı rotalarda kapsam kontrolünün ağ geçidinde uygulanıp diğerlerinde unutulması gibi yanlış yapılandırmaları yakalar. Kapsamları tasarlamak için OAuth 2.0 kapsamları açıklandı makalesine bakabilirsiniz.

Geçersiz İstemci: Jeton Uç Noktasında Hata Bekleyin

Sahte bir client_secret ile doğrudan jeton uç noktasına istek gönderin:

https://auth.example.com/oauth/token

RFC 6749 bölüm 5.2'ye göre sunucu şunlardan birini döndürmelidir:

• JSON gövdesinde "error": "invalid_client" ile birlikte 400
• Başarısız istemci kimlik doğrulaması için 401

Hem durum kodunu hem de hata gövdesini doğrulayın. Yetkilendirme sunucuları da API'dir; hata sözleşmeleri test kapsamınızın bir parçasıdır.

Jeton Yanıtlarını Doğrulama

Jeton uç noktasını yalnızca geçersiz istemci testiyle sınırlamayın. Test senaryonuza doğrudan jeton uç noktasını çağıran bir adım ekleyin ve yanıt için şu doğrulamaları yapın:

• access_token mevcut ve boş değil.
• token_type, büyük/küçük harf duyarsız olarak bearer değerine eşit.
• expires_in sıfırdan büyük ve politikanız dahilinde; örneğin 3600 değerini aşmıyor.
• scope, istenen kapsamla eşleşiyor.

Apidog test senaryolarında bu kontrolleri yanıt JSON'una görsel doğrulamalar olarak ekleyebilirsiniz; komut dosyası yazmanız gerekmez. Ham OAuth sözleşmesini test etmek istediğinizde access_token değerini bir sonraki adım için değişkene de çıkarabilirsiniz.

Senaryoyu CI çalıştırmanıza bağlayın. Böylece yanlış davranan bir yetkilendirme sunucusu üretimde gizemli bir 401'e dönüşmeden önce derlemeyi başarısız eder.

Önerilen Test Yapısı

Tam akış şu şekilde olmalıdır:

1. Başarılı yollar için klasör düzeyinde OAuth 2.0 yapılandırması oluşturun.
2. 401 testleri için istek düzeyinde eksik veya süresi dolmuş jeton kullanın.
3. 403 testleri için yetersiz kapsamlı istemci kullanın.
4. Jeton uç noktasının hata ve başarı sözleşmesini doğrudan doğrulayın.
5. Kullanıcı bağlamı API'lerinde PKCE'li Yetkilendirme Kodu akışını kullanın.
6. Hizmetten hizmete API'lerde İstemci Kimlik Bilgileri akışını kullanın.
7. Sağlayıcı yenileme jetonu sunuyorsa otomatik yenilemeyi etkinleştirin.
8. Senaryoları CI çalıştırmalarına bağlayın.

Apidog'u indirin ve ücretsiz deneyin. OAuth 2.0 kimlik doğrulama türü ücretsiz planda çalışır; kendi jeton uç noktanıza dakikalar içinde bağlanabilirsiniz.

SSS

API testi için hangi OAuth akışını kullanmalıyım?

Makineden makineye çağrılar ve çoğu otomatik test paketi için İstemci Kimlik Bilgileri akışını kullanın; tarayıcı etkileşimi gerektirmez.

Test edilen davranış kullanıcı kimliğine bağlıysa PKCE'li Yetkilendirme Kodu akışını kullanın:

• Kullanıcı başına veri izolasyonu
• Rol kontrolleri
• Onay davranışı

Yeni test planlarında Örtük ve Parola Kimlik Bilgileri akışlarından kaçının; güncel OAuth rehberliği bu akışları önermemektedir.

Apidog'da süresi dolan jetonu otomatik olarak nasıl yenilerim?

Kimlik Doğrulama sekmesinde OAuth 2.0'ı yapılandırın ve Jeton Al seçeneğiyle bir jeton alın. Yetkilendirme sunucusu yenileme jetonu döndürüyorsa Apidog, erişim jetonu süresi dolduğunda yeniden kimlik doğrulama gerektirmeden onu yeniler.

Sağlayıcınız ayrı bir yenileme uç noktası kullanıyorsa gelişmiş ayarlarda bu URL'yi belirleyin. Yenileme jetonu olmayan İstemci Kimlik Bilgileri kurulumlarında Jeton Al seçeneğini yeniden çalıştırmanız yeterlidir.

Bir senaryodaki her istek aynı OAuth jetonunu paylaşabilir mi?

Evet. OAuth 2.0 yapılandırmasını üst klasöre ayarlayın; içindeki istekler yapılandırmayı ve yönetilen jetonu devralır.

Tek tek istekler klasör yapılandırmasını geçersiz kılabilir. Bu sayede süresi dolmuş jeton veya yanlış kapsam gibi negatif testleri aynı senaryoya ekleyebilirsiniz.

OAuth korumalı API'lerde 401 ile 403 ne anlama gelmeli?

Kimlik doğrulama başarısız olduğunda 401 döndürün:

• Jeton eksik
• Jeton süresi dolmuş
• Jeton hatalı biçimlendirilmiş

Jeton geçerli ancak yetkisi yetersiz olduğunda 403 döndürün; örneğin gerekli kapsam eksikse.

Bu ayrım istemci yeniden deneme mantığı için önemlidir: 401 istemciye yeniden kimlik doğrulaması yapmasını, 403 ise isteği durdurmasını bildirir. Jetonun kendisini doğrulamak için JWT kimlik doğrulamasını test etme kılavuzuna bakabilirsiniz.