API Koruması

Geliştirici olarak API'nizi koruduğunuzda yetkilendirmeye odaklanırsınız. Kaynağınızın API'sini çağırmak için uygulamaların uygulama yetkilendirmesi alması gerekir. Kaynak, yetkilendirme uygulanmasını sağlar. Bu makalede Sıfır Güven hedeflerinize ulaşmak için en iyi yöntemleri öğreneceksiniz. Kayıt, izin ve onay tanımı ve erişim zorlaması aracılığıyla API'nizi nasıl koruyacağınızı açıklar.

Korumalı API'nizi kaydetme

API'nizi Microsoft Entra Id (Microsoft Entra ID) ile korumak için API'nizi kaydedin. Ardından kayıtlı API'lerinizi yönetebilirsiniz. Microsoft Entra Id'de API, bunu başka bir uygulamanın erişebileceği bir kaynak veya API olarak tanımlayan belirli uygulama kayıt ayarlarına sahip bir uygulamadır. Microsoft Entra yönetim merkezinde, Microsoft Kimlik Geliştirici, Uygulama kayıtları, kiracıda iş kolu API'leri veya Microsoft Entra ID'nin koruduğu API'lere sahip Yazılım olarak Hizmet (SaaS) sağlayıcılarının hizmetleri olarak bulunan API'lerdir.

Kayıt sırasında, çağrı yapan uygulamaların API'nize ve API'nin delegeli veuygulama izinlerine nasıl başvuracağını tanımlarsınız. Uygulama kaydı hem istemci uygulamaları hem de API'leri olan bir çözümü temsil edebilir. Ancak bu makalede, tek başına bir kaynağın BIR API'yi kullanıma sunma senaryosunu ele alıyoruz.

Normalde API kimlik doğrulaması gerçekleştirmez veya doğrudan yetkilendirme istemez. API, çağıran uygulamanın sunduğu bir belirteci doğrular. API'lerde etkileşimli oturum açma işlemleri yoktur, bu nedenle yeniden yönlendirme URI'si veya uygulama türü gibi ayarları kaydetmeniz gerekmez. API'ler belirteçlerini Microsoft Entra Id ile etkileşim kurarak değil, bu API'leri çağıran uygulamalardan alır. Web API'leri için yetkilendirme için OAuth2 erişim belirteçlerini kullanın. Web API'leri çağıranları yetkilendirmek için taşıyıcı belirteçleri doğrular. Kimlik belirteçlerini izin kanıtı olarak kabul etmeyin.

Varsayılan olarak, Microsoft Entra Id herhangi bir yeni uygulama kaydının API izinlerine ekler User.Read . Çoğu web API'sinde bu izni kaldırırsınız. Microsoft Entra Id, yalnızca bir API başka bir API çağırdığında API izinleri gerektirir. API'niz başka bir API çağırmıyorsa, API'nizi kaydederken User.Read iznini kaldırın.

API'nize erişmesi gereken istemci uygulamalarının API'nizi çağırmak için izin istediği, API'niz için Uygulama Kimliği URI'si olarak bilinen benzersiz bir tanımlayıcıya ihtiyacınız vardır. Uygulama Kimliği URI'sinin tüm Microsoft Entra kiracılarında benzersiz olması gerekir. Portaldaki varsayılan öneri olan api://<clientId>, kayıtlı API'nizin Uygulama Kimliği olan <clientId>'i kullanabileceğiniz yerdir.

API'nizi çağıran geliştiricilere daha kolay bir ad sağlamak için API'nizin adresini Uygulama Kimliği URI'niz olarak kullanabilirsiniz. Örneğin, yourdomain.com Microsoft Entra kiracınızdaki yapılandırılmış bir yayımcı etki alanı olduğunda https://API.yourdomain.com kullanabilirsiniz. Microsoft, etki alanını API'niz için benzersiz bir tanımlayıcı olarak kullanabilmeniz amacıyla sahip olduğunuzu doğrular. Bu adreste kod olması gerekmez. API istediğiniz yerde olabilir, ancak API'nin adresini Uygulama Kimliği URI'si olarak kullanmak https iyi bir uygulamadır.

En az ayrıcalıkla yetkili izinler tanımlayın

Kullanıcıları olan uygulamalar API'nizi çağıracaksa, en az bir temsilci izni tanımlayın (bkz. Uygulama kaydında kapsam eklemeAPI'yi kullanıma sunma).

Kuruluş veri depolarına erişim sağlayan API'ler, söz konusu verilere erişmek isteyen kötü aktörlerin dikkatini çekebilir. Yalnızca bir temsilci iznine sahip olmak yerine, izinlerinizi en az ayrıcalık erişimi olan Sıfır Güven ilkesiyle tasarlarsınız. Daha sonra tüm istemci uygulamaları tam ayrıcalıklı erişimle başlıyorsa en az ayrıcalıklı modele girmek zor olabilir.

Geliştiriciler sıklıkla kullanıcı olarak erişim veya kullanıcı kimliğine bürünme gibi tek bir izin kullanma desenine girer (ki bu teknik olarak yaygın bir yanlış ifadedir). Bunlar gibi tek izinler yalnızca API'nize tam ayrıcalıklı erişim sağlar.

Uygulamalarınızın tehlikeye açık olmaması veya hiç istemediğiniz bir görevi gerçekleştirmek için kullanılmaması için en düşük ayrıcalık seviyelerini bildirin. API İzinleri'nde birden çok kapsamınızı tanımlayın. Örneğin, kapsamları verileri okuma ve güncelleştirmeden ayırın ve salt okunur izinler sunmayı göz önünde bulundurun. Yazma erişimi oluşturma, güncelleştirme ve silme işlemleri için ayrıcalıklar içerir. İstemci, yalnızca okuma verileri için hiçbir zaman yazma erişimi gerektirmemelidir.

API'niz hassas verilerle çalışırken standart ve tam erişim izinlerini göz önünde bulundurun. Standart bir iznin erişime izin vermemesi için hassas özellikleri kısıtlayın (örneğin, Resource.Read). Ardından, özellikleri ve hassas bilgileri döndüren bir tam erişim izni (örneğin, Resource.ReadFull) uygulayın.

İşi yapmak için mutlak en az ayrıcalıklı kümeyi aradığınızdan emin olmak için istediğiniz izinleri her zaman değerlendirin. Daha yüksek ayrıcalık izinleri istemekten kaçının. Bunun yerine, her çekirdek senaryo için ayrı bir izin oluşturun. Bu yaklaşımın iyi örnekleri için Microsoft Graph izin başvurusuna bakın. gereksinimlerinizi karşılamak için doğru sayıda izin bulun ve kullanın.

Kapsam tanımlarınızın bir parçası olarak, belirli bir kapsamla gerçekleştirilebilecek işlem aralığının yönetici onayı gerekip gerekmediğine karar verin.

API tasarımcısı olarak, hangi kapsamların güvenli bir şekilde yalnızca kullanıcı onayı gerektirebileceği konusunda rehberlik sağlayabilirsiniz. Ancak, kiracı yöneticileri, tüm izinlerin yönetici onayı gerektirmesini sağlamak için bir kiracı yapılandırması yapabilir. Bir kapsamı yönetici onayı gerektiren olarak tanımlarsanız, izin her zaman yönetici onayı gerektirir.

Kullanıcı veya yönetici onayına karar verdiğinizde şu önemli noktalara sahipsiniz:

  • İznin ardındaki işlem aralığının tek bir kullanıcıdan fazlasını etkileyip etkilemediği. İzin, kullanıcının hangi uygulamanın yalnızca kendi bilgilerine erişebileceğini seçmesine izin veriyorsa, kullanıcı onayı uygun olabilir. Örneğin, kullanıcı e-posta için tercih ettiği uygulamayı seçmeyi onaylayabilir. Ancak, iznin ardındaki işlemler tek bir kullanıcıdan fazlasını içeriyorsa (diğer kullanıcıların tam kullanıcı profillerini görüntüleme gibi), bu izni yönetici onayı gerektiren olarak tanımlayın.

  • İznin arkasındaki işlem aralığının geniş bir kapsama sahip olup olmadığı. Örneğin geniş kapsamlı bir kapsam, bir iznin bir uygulamanın kiracıdaki her şeyi değiştirmesine veya geri alınamaz olabilecek bir şey gerçekleştirmesine olanak sağladığı durumdur. Geniş bir kapsam, kullanıcı onayı yerine yönetici onayına ihtiyacınız olduğunu gösterir.

Şüpheniz varsa ihtiyatlı olun ve yönetici onayı talep edin. İzin dizelerinizdeki onayın sonuçlarını net ve kısa bir şekilde açıklayın. Açıklama dizelerinizi okuyan kişinin API'lerinizi veya ürününüzü bilmediğini varsayalım.

API'lerinizi mevcut izinlere, iznin semantiğini değiştirecek şekilde eklemekten kaçının. Mevcut izinlerin aşırı yüklenmesi, istemcilerin daha önce izin verdiği gerekçeyi seyreltir.

Uygulama izinlerini tanımlama

Kullanıcı dışı uygulamalar oluştururken, kullanıcı adı ve parola veya Çok Faktörlü Kimlik Doğrulaması (MFA) sorabileceğiniz bir kullanıcınız yoktur. Kullanıcıları olmayan uygulamalar (iş yükleri, hizmetler ve daemon'lar gibi) API'nizi çağırırsa, API'niz için uygulama izinlerini tanımlayın. Uygulama izni tanımlarken kapsamları kullanmak yerine bir uygulama rolü kullanın.

Temsilci izinlerinde olduğu gibi, API'nizi çağıran iş yüklerinin en az ayrıcalık erişimini izleyebilmesi ve Sıfır Güven ilkeleriyle uyumlu olabilmesi için ayrıntılı uygulama izinleri sağlarsınız. Yalnızca bir uygulama rolü (uygulama izni) ve bir kapsam (temsilci izni) yayımlamaktan veya tüm işlemleri her istemciye ifşa etmekten kaçının.

İş yükleri istemci kimlik bilgileriyle kimlik doğrulaması yapar ve aşağıdaki örnek kodda gösterildiği gibi kapsamına sahip.default bir belirteç isteyebilir.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

İzinler, uygulamanın önünde kullanıcı olmadığında ve uygulama izni çok çeşitli işlemleri etkinleştirdiğinde yönetici onayı gerektirir.

Erişimi zorunlu kılma

Çağıran uygulamaların isteğin yetkilendirme üst bilgisinde https taşıyıcı belirteçler olarak sağladığı erişim belirteçlerini doğrulayarak ve yorumlayarak API'lerinizin erişimi zorunlu kılmasını sağlayın. Aşağıdaki bölümlerde açıklandığı gibi belirteçleri doğrulayarak, meta veri yenilemeyi yöneterek ve kapsamları ve rolleri zorlayarak erişimi zorunlu kılın.

Belirteçleri doğrulama

API'niz bir belirteç aldıktan sonra belirteci doğruladığından emin olun. Doğrulama, belirtecin uygun verenden tasdiksiz ve değiştirilmemiş olarak gelmesini sağlar. Kimlik belirteçlerinde olduğu gibi belirteci doğrudan Microsoft Entra Id'den almadığınızdan imzayı denetleyin. API'niz ağdaki güvenilmeyen bir kaynaktan belirteç aldıktan sonra imzayı doğrulayın.

JSON web belirteci imza doğrulamasıyla ilgili bilinen güvenlik açıkları olduğundan, iyi korunan ve oluşturulmuş bir standart belirteç doğrulama kitaplığı kullanın. Kimlik doğrulama kitaplıkları ( Microsoft.Identity.Web gibi) doğru adımları kullanır ve bilinen güvenlik açıkları için azaltma gerçekleştirir.

İsteğe bağlı olarak, belirteç doğrulamasını genişletin. Kiracı kimliğini (tid) kullanarak, API'nizin belirteç alabileceği kiracıları kısıtlayın. API'nizi çağırabilen uygulamaları filtrelemek için azp ve appid taleplerini kullanın. Tek tek kullanıcılara erişimi daha da daraltmak için nesne kimliği (oid) talebi kullanın.

Meta veri yenilemeyi yönetme

Belirteç doğrulama kitaplığınızın gerekli meta verileri etkili bir şekilde yönettiğinden emin olun. Bu durumda meta veriler, Microsoft'un Microsoft Entra belirteçlerini imzalamak için kullandığı ortak anahtarlar, özel anahtar çiftidir. Kütüphaneleriniz bu belirteçleri doğruladığında, iyi bilinen bir internet adresinden yayımlanmış genel imzalama anahtarları listemizi alır. Barındırma ortamının bu anahtarları almak için doğru zamanlamaya sahip olduğundan emin olun.

Örneğin, eski kitaplıklar zaman zaman bu ortak imzalama anahtarlarını 24 saatte bir güncelleştirmek için sabit kodlandı. Microsoft Entra Id'nin bu anahtarları hızlı bir şekilde döndürmesi gerektiğinde ve indirdiğiniz anahtarların yeni döndürülmüş anahtarları içermediğini göz önünde bulundurun. API'niz meta veri yenileme döngüsünü beklerken bir gün çevrimdışı olabilir. Meta verileri düzgün bir şekilde aldığınızdan emin olmak için belirli meta veri yenileme kılavuzuna başvurun. Kitaplık kullanıyorsanız, bu meta verilerin makul bir zamanlama içinde ele alındığından emin olun.

Kapsamları ve rolleri zorunlu kılma

Belirtecinizi doğruladıktan sonra, API'niz nasıl çalışması gerektiğini belirlemek için belirteçteki taleplere bakar.

Temsilci izin belirteçleri için, API'nizin uygulamanın ne yapmaya onay verdiğinizi görmek için kapsam (scp) iddiasını incelemesini sağlayın. Uygulama adına çalışan kullanıcıyı görmek için nesne kimliğini (oid) veya konu anahtarını (sub) inceleyin.

Ardından, kullanıcının istenen işleme de erişimi olduğundan emin olmak için API'nizi denetleyin. API'niz kullanıcılara ve gruplara atanacak rolleri tanımlıyorsa, API'nizin belirteçteki rol taleplerini denetlemesini ve uygun şekilde davranmasını sağlayın. Uygulama izin belirteçlerinin kapsam (scp) talebi yoktur. Bunun yerine API'nizin iş yükünün hangi uygulama izinlerini aldığını saptamak için rol iddiasını incelemesini sağlayın.

API'niz belirteci ve kapsamları doğruladıktan ve nesne kimliğini (), konu anahtarını (oidsub ) ve rol taleplerini işledikten sonra, API'niz sonuçları döndürebilir.

Sonraki Adımlar

  • Last updated on