- Konu sahibi
- #1
API secret nedir?
API secret, bir uygulamanın başka bir API’ye yaptığı isteğin yetkili bir uygulamadan geldiğini kanıtlamak için kullanılan gizli kimlik bilgisidir. Servise göre bir tanımlayıcıyla birlikte kullanılır, istek imzası üretir veya tek başına gizli erişim anahtarı görevini görür. API secret parola gibi korunmalı, tarayıcıya, mobil uygulamanın içine, Git deposuna ya da istemciye gönderilen JavaScript koduna konulmamalıdır.
Nasıl çalışır?
Her servis aynı adlandırmayı kullanmaz. Key–secret çifti kullanan bir serviste key tanımlayıcı, secret doğrulama bilgisi olabilir; başka bir servisin API key adını verdiği değer de gizli erişim bilgisi olabilir. Servislerin kullandığı yönteme göre secret şu şekillerde kullanılabilir:
- İsteğin
Authorizationbaşlığında doğrudan kimlik doğrulama bilgisi olarak kullanılabilir. - İstek gövdesi ve zaman damgası secret ile imzalanabilir. Sunucu aynı imzayı hesaplayarak isteğin değiştirilmediğini kontrol eder.
- OAuth benzeri akışlarda uygulamanın kimliğini doğrulayan
client_secretolarak görev yapabilir.
API secret’ın biçimi ve gönderileceği alan her serviste farklıdır. Bu nedenle secret’ın kendisini tahmin etmeye veya farklı bir API’deki kullanım biçimini kopyalamaya çalışmak yerine ilgili servisin kimlik doğrulama dokümanı izlenmelidir.
Somut örnek
Bir sunucu tarafı uygulamanızın bir e-posta API’sine istek gönderdiğini varsayalım. API size
MAIL_API_KEY ve MAIL_API_SECRET bilgilerini vermiş olsun. Kullanıcı tarayıcıda bir iletişim formu doldurduğunda tarayıcı doğrudan e-posta API’sine bağlanmaz. İstek önce sizin sunucunuza gelir; sunucunuz secret’ı kullanarak e-posta API’sine yetkili isteği gönderir.Secret, kaynak koduna sabitlenmek yerine çalışma ortamından okunabilir. Aşağıdaki örnekteki değerler gerçek kimlik bilgisi değildir; bunları istemciye açılan bir .env dosyasında yayımlamayın:
Kod:
MAIL_API_KEY=example-public-identifier
MAIL_API_SECRET=example-server-secretUygulama bu değerleri ortam değişkenlerinden alır. Bu satırlar yalnızca temsili ortam ayarlarıdır; tek başına bir e-posta göndermez. Uygulamanız sağlayıcının API çağrısını ayrıca yapmalıdır. Servisin kabul yanıtı çoğu zaman iletinin kuyruğa alındığını gösterir; alıcıya teslim edildiğini kanıtlamaz. Kullanıcıya sonucu bu ayrımla bildirin. Kimlik doğrulama hatası alınırsa secret’ın yanlış, eksik, süresi dolmuş veya ilgili ortamda tanımlanmamış olması muhtemeldir.
API key, API secret ve token farkı
Aşağıdaki ayrım, hangi bilginin nerede tutulacağını belirlemeye yardımcı olur:
| Bilgi | Temel amacı | İstemci tarafında kullanılabilir mi? |
|---|---|---|
| API key | Uygulamayı veya projeyi tanımlamak | Servisin açıkça izin verdiği durumlar dışında hayır |
| API secret | Uygulamanın gizli kimliğini doğrulamak veya imza üretmek | Hayır; sunucuda tutulmalıdır |
| Access token | Belirli bir kullanıcı ya da yetkiyle API erişimi sağlamak | Akışa göre; kısa ömürlü ve sınırlı yetkili olması tercih edilir |
Bu bilgiler birbirinin yerine geçmez. Bir servisin API key’i tek başına yeterli olabilir; başka bir servis secret ile imza isteyebilir. Kesin gereksinim, kullanılan API’nin kimlik doğrulama yöntemidir.
Uygulamada doğru kullanım
- Secret’ı yalnızca sunucu tarafındaki yapılandırmaya veya gizli değişken yönetimine ekleyin; kaynak koduna sabitlemeyin.
- Yerel geliştirme, test ve canlı ortam için mümkünse ayrı kimlik bilgileri kullanın.
- Secret’ı loglara, hata mesajlarına, istemciye dönen JSON yanıtlarına ve ekran görüntülerine yazdırmayın.
- Depoya yanlışlıkla eklendiyse yalnızca dosyayı silmekle yetinmeyin; servisin panelinden secret’ı iptal edip yenisini üretin. Git geçmişinde eski değer kalabilir.
- Gerektiğinden geniş izin veren bir kimlik bilgisi yerine yalnızca gerekli API işlemlerine yetkili bir credential kullanın.
Sık yapılan hatalar
En yaygın hata, frontend kodunda secret saklamaktır. JavaScript dosyası, mobil uygulama paketi veya ağ isteği kullanıcı tarafından incelenebildiği için burada bulunan gizli değer gizli kalmaz. Böyle bir mimaride doğru yaklaşım, secret kullanan işlemi sunucuya taşımak ve tarayıcıya yalnızca gerekli sonucu döndürmektir.
Bir diğer hata da API key ile API secret’ı aynı şey sanmaktır. Key görünür olması tasarlanan bir tanımlayıcı olabilir; secret ise adı açıkça belirtilmese bile gizli kabul edilmelidir. Kimlik doğrulama başarısız olduğunda değeri rastgele değiştirmek yerine önce ortam değişkeninin yüklendiğini, doğru API ortamına ait olduğunu ve servisin beklediği başlık ya da imza biçiminin kullanıldığını kontrol edin.
Sık sorulan sorular
Sunucuya taşımak API işlemini tek başına korur mu?
Hayır. İletişim formu örneğinde kendi uç noktanız da kullanıcı yetkisini, girdi sınırlarını ve istek hızını kontrol etmelidir. Aksi hâlde gizli değer görünmese bile herkese açık sunucu uç noktası üzerinden istenmeyen işlemler yaptırılabilir.
Secret sızdıysa uygulamayı kapatmak gerekir mi?
Öncelikle sızan secret’ı servis panelinden iptal edin veya yenileyin. Ardından yeni değeri sunucu yapılandırmasına ekleyip uygulamayı yeniden başlatın ve eski değerin loglarda, depolarda veya dağıtım ayarlarında kalmadığını kontrol edin.
