Aracınızın bir müşterinin takvimini okuması, hesabından bir mesaj göndermesi veya adına bir talep oluşturması gerekebilir. Hızlı çözüm, geniş erişime sahip tek bir hizmet hesabı tutmak ve onun aracılığıyla işlem yapmaktır. Her eylem "entegrasyon" olarak görünür, kimin neyi tetiklediği anlaşılamaz ve ele geçirilmiş tek bir kimlik bilgisi, temas ettiğiniz her hesabı açığa çıkarır.
Doğru çözüm, yetki devri tabanlı yetkilendirmedir: kullanıcı aracınıza kapsamlı, iptal edilebilir bir token verir, aracı o kullanıcı adına hareket eder ve denetim izi onları isimlendirir. OAuth 2.0 bunun için geliştirilmiştir. Aracılar için bunu garip kılan şey, OAuth'ın bir tarayıcı ve "İzin Ver"e tıklayacak bir kişinin varlığını varsaymasıdır, oysa aracılar sabah 3'te arka planda çalışır.
Bu rehber, bir aracıya hangi OAuth akışının uygun olduğunu, token'ları nasıl kapsayacağınızı ve saklayacağınızı, yenileme ve iptal konularında ne yapacağınızı ve tüm yolu canlı bir hesap olmadan nasıl test edeceğinizi kapsar. Hala anahtar tabanlı ve yetki devri tabanlı yetkilendirme arasında seçim yapıyorsanız, API anahtarları ve OAuth karşılaştırmamız başlangıç noktasıdır.
Apidog, ekiplerin hafife aldığı kısımda yardımcı olur: bir aracı üretimde onlarla karşılaşmadan önce, süre sonu ve iptal dahil olmak üzere akışın her dalını uygulamak.
Hizmet hesabı veya yetki devri tabanlı erişim
Dikkatli seçim yapın, çünkü iki modelin başarısızlık şekilleri farklıdır.
Bir hizmet hesabı, aracınızın kendi kimliği olup, kendi izinlerine sahiptir. Aracının sizin adınıza yaptığı işlere uygundur: kendi veritabanınızı okumak, kendi dahili servislerinizi çağırmak, altyapınıza karşı zamanlanmış işler çalıştırmak. Aracılar için en az ayrıcalıklı API anahtarları hakkındaki yazımızda belirtildiği gibi, kapsamını sıkı tutun ve döndürün.
Yetki devri tabanlı erişim, aracının belirli bir kullanıcı adına, o kullanıcının izinleriyle ve fazlası olmadan hareket etmesidir. Veriler başkasına ait olduğunda her zaman gereklidir. Üç özellik, ekstra çabaya değer kılar: kullanıcı neyin verildiğini görebilir, kullanıcı bunu iptal edebilir ve her eylemde onların kimliği logda yer alır.
Kaçınılması gereken başarısızlık modu, kullanıcılar adına hareket etmek için kullanılan, organizasyon genelinde erişime sahip bir hizmet hesabıdır. Çalışır, ancak bu şu anlama gelir: tek bir sızdırılan kimlik bilgisi herkesi açığa çıkarır, kullanıcı başına iptal ve dürüst bir denetim izi olmadan.
Bir aracıya hangi akış uyar
OAuth 2.0 birkaç yetki türü tanımlar ve burada sadece birkaçı mantıklıdır. OAuth 2.0 spesifikasyonu tüm kümesi içerir; kullanacağınızlar bunlardır.
PKCE ile Yetkilendirme Kodu. Kullanıcı adına hareket etmek için standart akıştır. Kullanıcı sağlayıcıya yönlendirilir, kapsamları onaylar ve servisiniz kodu token'larla değiştirir. PKCE değişimi korur ve OAuth 2.0 Güvenlik En İyi Güncel Uygulamaları'na göre artık her istemci türü için varsayılan öneridir. Yetkilendirme kodu yetkisi hakkındaki rehberimiz mekaniği adım adım açıklar.
Aracıya özgü nokta: bu akış, insan mevcutken, bağlantı anında bir kez çalışır. Aracı bunu asla çalıştırmaz. Akışın ürettiği yenileme token'ını kullanır. Tasarımınızda bu iki anı ayırın ve garipsiliğin çoğu ortadan kalkar.
İstemci Kimlik Bilgileri. Makineler arası, kullanıcı yok. Hizmet hesapları için doğru, kullanıcı adına hareket etmek için yanlış, çünkü onay verecek bir kullanıcı yok.
Cihaz Yetkilendirme Yetkisi. Tarayıcısı olmayan makinelerdeki aracılar için. Kullanıcı bir kod alır ve telefonundan onaylar. CLI (komut satırı) aracıları ve başsız ortamlar için kullanışlıdır.
Token Değişimi. RFC 8693, bir servisin bir token'ı daha dar kapsamlı bir token ile değiştirmesine olanak tanır. Bu, bir alt-aracıya, kullanıcının daha geniş yetkisinden türetilmiş, tek bir görev için tek bir kapsama sınırlı bir token'ı, orijinalini vermeden nasıl vereceğinizin yoludur. Çoklu aracı sistemleri çalıştırıyorsanız, bu, aracı başına kimlik bilgilerini pratik hale getiren mekanizmadır ve çoklu aracı devri hakkındaki yazımızdaki sınır kurallarına uyar.
Kapsamı daraltın ve aracı başına belirleyin
Kapsamlar, yetki devri tabanlı erişimin değerini gösterdiği yerdir ve çoğu uygulamanın, uygulamanın ihtiyaç duyabileceği her şeyi isteyerek tembellik ettiği yerdir.
Sadece bu aracının yaptığını isteyin. Bir zamanlama aracısı takvim yazma iznine ihtiyaç duyar, başka hiçbir şeye değil. E-posta değil, kişiler değil, dosyalar değil. Kullanıcılar onay ekranını okur ve uzun bir liste hem bir güven sorunu hem de etki alanı sorunudur. OAuth 2 kapsamları hakkındaki açıklamamız, sağlayıcıların bunları nasıl modellediğini kapsar.
Aşamalı olarak isteyin. Bağlantı anında minimumu isteyin, ardından kullanıcı bunu gerektiren bir özellik istediğinde daha fazlasını isteyin. Somut bir isteğe bağlı onay vermek daha kolaydır ve haklı çıkarması daha basittir.
Her aracıya kendi token'ını verin. Eğer bir araştırma aracısı ve bir faturalandırma aracısı aynı kullanıcı adına hareket ediyorsa, bir tane paylaşmak yerine farklı kapsamlara sahip iki token türetin. O zaman ele geçirilmiş bir araştırma aracısı para iadesi yapamaz ve log hangi aracının işlem yaptığını size söyler.
Varsayılan olarak okuma kapsamlarını tercih edin ve yazma işlemleri için açık bir yükseltme (izin) isteyin. Bunu, Yapay Zeka aracı koruma önlemleri hakkındaki yazımızda olduğu gibi, yıkıcı çağrılarda bir onay geçidi ile birleştirin, böylece yazma yetkisi olan bir token, aracı ile bir hata arasında duran tek şey olmaz.
Sakla, yenile ve iptal et
Token'lar kimlik bilgileridir, bu yüzden onlara kimlik bilgileri gibi davranın.
Saklama. Yenileme token'larını beklerken, kullanıcı başına anahtarlı olarak şifreleyin. Asla loglara yazmayın, asla komut istemlerine koymayın ve asla bir modelin görmesine izin vermeyin. Bağlamdaki bir token, izleme depounuzda, sağlayıcınızın loglarında ve muhtemelen bir özette yer alan bir token'dır. Aracı araç çağrılarını izleme hakkındaki yazımız, okuma zamanı yerine sınırda düzeltme yapmayı kapsar.
Yenileme. Erişim token'ları tasarım gereği kısa ömürlüdür. Aracı bunu asla kendi başına yönetmemelidir; HTTP istemcisinin önündeki bir token yöneticisi, süre dolduğunda yeniler ve 401 hatası üzerine çağrıyı bir kez daha dener.
class TokenManager:
def __init__(self, store, provider):
self.store, self.provider = store, provider
def access_token(self, user_id, agent_scope):
rec = self.store.get(user_id, agent_scope)
if rec.expires_in() > 60:
return rec.access_token
fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
self.store.save(user_id, agent_scope, fresh) # döndürme: yeni yenileme token'ını sakla
return fresh.access_token
İki detay önemlidir. Sağlayıcılar giderek daha fazla yenileme token'larını döndürür, her yenilemede yeni bir tane verir ve eskisini geçersiz kılar, bu yüzden yenisini hemen kalıcı hale getirin, aksi takdirde kullanıcıyı sistemden kilitleyeceksiniz. Ve kullanıcı başına yenilemeleri serileştirin, çünkü dönen bir sağlayıcıyla iki eşzamanlı yenileme rekabet edecek ve biri kaybedecektir.
İptal. Kullanıcılar erişimi iptal eder, token'lar sona erer, yöneticiler hesapları kaldırır. Aracı, 401 ve 403 hatalarını yeniden denenebilir değil, sonlandırıcı olarak ele almalıdır. Bir yetkilendirme hatasını yeniden denemek asla yardımcı olmaz ve kötüye kullanım korumalarını tetikleyebilir. Bir insanın hareket edebilmesi için kullanıcıyı ve kapsamı belirten açık bir mesaj döndürün, aracılar için API hata tasarımı hakkındaki yazımızdaki hata desenlerini takip ederek.
Onay sorunu
Aracılar ve OAuth'ın garip yanı: onay bir insan gerektirir ve aracılar gözetimsiz çalışır.
Bağlantı zamanını çalışma zamanından ayırın, böylece yönetilebilir hale gelir. Bağlantı anında, bir kişi bir tarayıcı aracılığıyla bir kez yetkilendirir ve siz bir yenileme token'ı saklarsınız. Çalışma zamanında, aracı o yetkiyi hiçbir insan katılımı olmadan kullanır. Bu, zamanlanmış ve arka plan aracıları için işe yarar, ki çoğu böyledir.
Planlanması gereken iki sınır. Yetkiler sona erer, bazen aylarca kullanılmamaktan sonra, bazen de politika gereği. Süresi dolmuş bir yetkiyi tespit edin, çalışmayı durdurun ve kullanıcıyı bilgilendirin, her gece sessizce başarısız olmak yerine. Ve onayın bir kapsam tavanı vardır: kullanıcının hiç vermediği bir kapsama ihtiyacı olan bir aracı, kendi başına yükseltmek yerine sormalıdır.
Yüksek riskli her şey için, eylem zamanında ikinci bir kapı ekleyin. Token, aracının işlem yapabileceğini kanıtlar; bir onay kapısı ise yapıp yapmaması gerektiğine karar verir. Bunlar farklı sorulardır ve her ikisi de bir cevabı hak eder.
Aracı karşılaşmadan önce akışı test edin
Yetkilendirme kodu yolları, çoğu entegrasyonun en az test edilen kısmıdır, çünkü bunları elle çalıştırmak, bir sağlayıcının ekranlarında tıklamak anlamına gelir.
Şu beş durumu oluşturun:
- Mutlu senaryo. Geçerli bir erişim token'ı, başarılı bir çağrı. Temel durum.
- Süresi dolmuş erişim token'ı. Sağlayıcı
401döndürür, yönetici yeniler, çağrı bir kez yeniden denenir ve başarılı olur. Bu, en yaygın gerçek yoldur ve genellikle en az test edilenidir. - İptal edilmiş yenileme token'ı. Yenileme
invalid_grantdöndürür. Aracı döngüye girmemeli, durmalı ve rapor etmelidir. - Yetersiz kapsam. Kapsam hatasıyla bir
403. Aracı yeniden denememeli ve hangi kapsamın eksik olduğunu belirtmelidir. - Eşzamanlı yenileme. Aynı kullanıcı için aynı anda iki çağrı. Tam olarak bir yenileme gerçekleşmelidir.
Bunları sahte (mock) verilere karşı çalıştırın. Apidog'da token uç noktasını ve korumalı uç noktaları tanımlayabilir, ardından hata gövdeleri dahil her yanıtı taklit edebilirsiniz, böylece tüm matris gerçek bir sağlayıcıya dokunmadan çalışır. Aracıları üretim yerine mock'lara karşı çalıştırma hakkındaki yazımız daha geniş alışkanlığı kapsar ve OAuth 2 API test rehberimiz istek düzeyindeki detayları kapsar.
Üç entegrasyon ve neye ihtiyaç duydukları
Bir takvim asistanı. Tek bir kullanıcı için müsaitlik okur ve toplantılar ayarlar. Yetki devri tabanlı erişim, iki kapsam, tarayıcıda bağlantı anında onay, ardından arka plan çalışmaları. İlginç hata iptaldir: kullanıcı entegrasyonu bağlantısını keser ve gece çalışan işlem, bir hafta boyunca ölü bir yetkiyi yeniden denemek yerine bunu fark edip durmalıdır.
Paylaşılan bir gelen kutusundaki destek aracısı. Bir ekibe ait talepler üzerinde işlem yapar. Burada kimlik sorusu daha da keskinleşir. Ekibin paylaşılan hesabı olarak hareket etmek savunulabilir, çünkü kaynak gerçekten ekibe aittir, ancak her yanıt denetim kaydında aynı görünür. Daha iyisi, kendi kapsamlarına sahip bir bot kimliği ve çalışmayı hangi insanın tetiklediğinin kaydıdır, bu, aracının bir kişi gibi davranmadan atfı sağlam tutar.
Dahili bir operasyon aracısı. Kendi altyapınızdaki hizmetleri yeniden başlatır ve panoları okur. Kullanıcı verisi yok, yetki devri yok. Dar kapsamlı bir hizmet hesabı doğru yanıttır ve çalışma, onaydan ziyade döndürme ve etki alanına odaklanır.
Ayrım noktası sahipliktir. Eğer veriler, erişiminizi makul bir şekilde iptal etmek isteyebilecek birine aitse, yetki devri tabanlı yetkilendirme kullanın. Eğer size aitse, bir hizmet hesabı kullanın ve çabanızı kapsama harcayın.
Atıfta insanı tutun
Yetki devri tabanlı yetkilendirme "kimin adına" sorusunu yanıtlar. Ancak "kimin isteği üzerine" sorusunu yanıtlamaz ve aracı çalışmaları için her ikisini de istersiniz. Bir token, aracının bir kullanıcı olarak işlem yapabileceğini kanıtlar; ancak çalışmayı hangi kişinin istediğini kaydetmez.
Bu ikinci kimliği işin yanında tutun. Aracıların atanmış görevleri yürüttüğü yerlerde, iş yönetimi katmanı doğal yerdir: bir Sharkly Görevi, işten sorumlu kişiyi, onu yürüten Aracı veya Ekip ile birlikte kaydeder, bu da insan sorumluluğunu ve aracı yürütmesini iki ayrı, görünür gerçek olarak tutar. Sharkly belgeleri bu ayrımı detaylı olarak açıklar. Nasıl saklarsanız saklayın, bir olaydan sonraki denetim sorusu genellikle "bunu kim istedi?"dir ve tek başına bir token bunu yanıtlayamaz.
Modelin kimlik bilgilerini tutmasına izin vermeyin
Tek bir mimari kural, aracı sistemlerindeki çoğu kimlik doğrulama olayını önler: model asla bir token görmez.
Token'lar yürütücü tarafından HTTP katmanında, model bir araç seçip argümanlar ürettikten sonra enjekte edilir. Araç şeması token parametresi içermez, komut istemi hiçbir kimlik bilgisi içermez ve modelin okuduğu yanıtta Authorization başlığı çıkarılmıştır.
Bu, model girdisinin nereye gittiği nedeniyle sıradan istemcilerden çok aracılar için daha önemlidir. Bağlamdaki herhangi bir şey bir devire özetlenebilir, bir izlemeye yazılabilir, bir hata mesajında yankılanabilir veya aracının kendisini açıklamasını isteyen bir kullanıcıya döndürülebilir. Bu yolların hiçbiri düşmanca değildir; hepsi, bir kimlik bilgisi kapsam içine girdiği anda sızıntı haline gelen normal özelliklerdir.
Aynı kural kullanıcı kimliği için de geçerlidir. Yürütücü, bu çalıştırmanın hangi kullanıcı adına işlem yaptığını bilir ve token'ı buna göre seçer. Modelin kullanıcıyı adlandırmasına izin vermek, sistemdeki en az tahmin edilebilir bileşen tarafından verilen bir yetkilendirme kararıdır.
Kontrol listesi
- Verilerin bir kullanıcıya ait olduğu her yerde yetki devri tabanlı erişim, hizmet hesapları sadece kendi kaynaklarınız için.
- Bağlantı anında PKCE ile yetkilendirme kodu, başsız makineler için cihaz yetkisi.
- Aracı başına istenen kapsamlar, minimal, aşamalı olarak yükseltilmiş.
- Alt-aracılar, kullanıcının yetkisinin kopyalarını değil, takas edilmiş token'ları alır.
- Yenileme token'ları beklemedeyken şifrelenmiş ve asla komut istemlerinde, loglarda veya izlemelerde yer almaz.
- Yenileme bir token yöneticisi tarafından yönetilir, kullanıcı başına serileştirilir, döndürme kalıcı hale getirilir.
401ve403, kullanıcı ve kapsamı belirten bir mesajla sonlandırıcı olarak ele alınır.- Süresi dolmuş yetkiler tespit edilir ve kullanıcıya gösterilir, gece yeniden denenmez.
- Yüksek riskli eylemler, token'ın yanı sıra onay ile korunur.
- Tüm beş kimlik doğrulama senaryosu CI'da sahte verilere karşı test edildi.
Yetki devri tabanlı yetkilendirme, paylaşılan bir anahtardan daha fazla iş demektir ve bir aracı başkaları adına işlem yaptığında ihtiyacınız olan iki şeyi size sağlar: kullanıcı bunu geri alabilir ve log kimin ne yaptığını söyler. Bir aracı gözetimsiz çalışmadan önce token akışını ve hata durumlarını oluşturmak için Apidog'u indirin.
Sıkça sorulan sorular
Aracı OAuth onay akışını kendi başına tamamlayabilir mi? Hayır, denememeli de. Onay, neyi vereceğine karar veren bir kişi gerektirir. Bir insanın normal bir tarayıcı akışı aracılığıyla bir kez yetkilendirmesini sağlayın, ardından aracının elde edilen yetkiyi kullanmasına izin verin.
Her aracının kendi OAuth istemcisi olmalı mı? Ürün entegrasyonu başına ayrı istemciler ve genellikle token değişimi yoluyla içinde aracı başına ayrı token'lar. Ayrı istemciler, sağlayıcılar istemci başına hız sınırları uyguladığında veya bağımsız iptal istediğinizde yardımcı olur.
Yenileme token'ı dönerse ve yenisini kaçırırsam ne olur? Kullanıcı kilitlenir ve yeniden bağlanmak zorunda kalır. Yeni yenileme token'ını eskiyi tüketen aynı işlemde kalıcı hale getirin ve iki çalışanın rekabet etmemesi için kullanıcı başına yenilemeleri serileştirin.
Modelin bir erişim token'ını görmesine izin vermek güvenli mi? Hayır. Token'lar HTTP katmanına aittir, yürütücünüz tarafından enjekte edilir. Bir modelin gördüğü herhangi bir şey bir izlemede, bir özette veya bir yanıtta yer alabilir, aracılar için en az ayrıcalıklı API anahtarları hakkındaki yazımızda belirtildiği gibi.
Hangi aracının ne yaptığını nasıl denetlerim? Her çağrıda kullanıcı kimliğini, aracı adını, kullanılan kapsamı ve token tanımlayıcısını loglayın, asla token'ın kendisini değil. Aracı araç çağrılarını izleme hakkındaki yazımız kayıt şeklini kapsar.
Sağlayıcı token değişimini desteklemiyorsa ne olur? Sağlayıcının birden fazlasına izin verdiği yerlerde aracı başına ayrı yetkiler saklayın veya kendi ağ geçidinizde kapsam daraltmayı uygulayın, böylece her aracının çağrıları ağınızdan ayrılmadan önce izin verilen işlemleriyle filtrelenir.