API Koruması

Bir geliştirici olarak API'nizi koruduğunuzda, odaklanmanız yetkilendirmeye odaklanır. Kaynağınızın API'sini çağırmak için uygulamaların uygulama yetkilendirmesi alması gerekir. Kaynağın kendisi yetkilendirmeyi zorunlu kılmalıdır. Bu makalede kayıt, izin ve onay tanımlama ve Sıfır Güven hedeflerinize ulaşmak için erişimi zorlama yoluyla API'nizi korumaya yönelik en iyi yöntemleri öğreneceksiniz.

Korumalı API'nizi kaydetme

API'nizi Microsoft Entra Id (Microsoft Entra ID) ile korumak için önce API'nizi kaydedersiniz ve ardından kayıtlı API'lerinizi yönetebilirsiniz. Microsoft Entra Id'de API, başka bir uygulamanın erişim yetkisine sahip olabileceği bir kaynak veya API olarak tanımlayan belirli uygulama kayıt ayarlarına sahip bir uygulamadır. Microsoft Entra yönetim merkezinde Uygulama kayıtları Microsoft Identity Developer, kiracıda iş kolu API'leri veya Microsoft Entra ID'nin koruduğu API'lere sahip SaaS sağlayıcılarının hizmetleri olarak bulunan API'lerdir.

Kayıt sırasında, çağrı yapan uygulamaların API'nize, temsilci ve uygulama izinlerine nasıl başvuracağınızı 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 izni kaldırın User.Read .

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. Kayıtlı API'nizin Uygulama Kimliği olan <clientId> portaldaki varsayılan öneriyi kullanabilirsiniz api://<clientId> .

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, Microsoft Entra kiracınızda yapılandırılmış bir yayımcı etki alanı olması gereken yeri yourdomain.com kullanabilirsinizhttps://API.yourdomain.com. Microsoft, api'nizin benzersiz tanımlayıcısı olarak kullanabilmeniz için etki alanının sahipliğiniz olduğunu doğrular. Bu adreste kod olması gerekmez. API istediğiniz yerde olabilir, ancak API'nin HTTPS adresini Uygulama Kimliği URI'si olarak kullanmak iyi bir uygulamadır.

En az ayrıcalıkla temsilci izinleri tanımlama

API'niz kullanıcıları olan uygulamalar tarafından çağrılacaksa, en az bir temsilci izni tanımlamanız gerekir (bkz. Uygulama kaydında kapsam ekleme API'yi kullanıma sunma).

Kuruluş veri depolarına erişim sağlayan API'ler, bu verilere erişmek isteyen saldırganların dikkatini çekebilir. Yalnızca bir temsilci iznine sahip olmak yerine, izinlerinizi en az ayrıcalık erişim ilkesine sahip Sıfır Güven tasarlar. 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 genellikle "kullanıcı olarak erişim" veya "kullanıcı kimliğine bürünme" (teknik olarak yanlış olsa da yaygın bir ifadedir) gibi tek bir izin kullanma desenine girer. Bunlar gibi tek izinler yalnızca API'nize tam ve ayrıcalıklı erişim sağlar.

Uygulamalarınızın tehlikeye açık olmadığından veya hiç istemediğiniz bir görevi gerçekleştirmek için kullanılmaması için en az ayrıcalık kapsamları 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.

Kullanıcı onayı ve yönetici onayı tanımlama

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ı gerektirmesi için bir kiracı yapılandırabilir. 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 verirken iki önemli noktanız vardır:

1. İ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 (örneğin, diğer kullanıcıların tam kullanıcı profillerini görüntüleme), bu izni yönetici onayı gerektiren olarak tanımlayın.

2. İ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.

Muhafazakar tarafta err ve şüpheniz varsa yönetici onayı iste. İ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ı olmayan 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 izinleri tanımlamanız gerekir. Bir uygulama izni tanımlarken kapsamları kullanmak yerine bir uygulama rolü kullanırsınız.

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 ilkelerle 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ı kullanarak .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 HTTPS isteğinin yetkilendirme üst bilgisinde 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ılabilirsiniz.

Belirteçleri doğrulama

API'niz bir belirteç aldıktan sonra belirteci doğrulamalıdır. 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ğrulamayı genişletin. API'nizin belirteç alabildiği kiracıları kısıtlamak için kiracı kimliğini (tid) kullanın. API'nizi azp çağırabilen uygulamaları filtrelemek için 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. Kitaplıklarınız bu belirteçleri doğruladığında, iyi bilinen bir internet adresinden yayımlanan 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

• Microsoft kimlik onayı çerçevesi tarafından korunan API örneği, en iyi kullanıcı deneyimi için en az ayrıcalıklı uygulama izinleri stratejileri tasarlamanıza yardımcı olur.
• Başka bir API'den API çağırmak, başka bir API'yi çağırması gereken bir API'niz olduğunda Sıfır Güven sağlamanıza ve bir kullanıcı adına çalışırken uygulamanızı güvenli bir şekilde geliştirmenize yardımcı olur.
• Belirteçleri özelleştirme, Microsoft Entra belirteçlerinde alabileceğiniz bilgileri açıklar. En az ayrıcalıkla uygulama sıfır güven güvenliğini artırırken esnekliği ve denetimi geliştirmek için belirteçlerin nasıl özelleştirileceği açıklanır.
• Belirteçlerde grup taleplerini ve uygulama rollerini yapılandırma, uygulama rol tanımlarıyla uygulamalarınızı yapılandırmayı ve uygulama rollerine güvenlik grupları atamayı gösterir. Bu yöntemler, en az ayrıcalıkla uygulama sıfır güven güvenliğini artırırken esnekliği ve denetimi geliştirmeye yardımcı olur.
• Kaynaklara erişmek için yetkilendirme alma, uygulamanız için kaynak erişim izinleri alırken Sıfır Güven en iyi şekilde nasıl sağlayacağınızı anlamanıza yardımcı olur.
• Yönetici onayı gerektiren istek izinleri, uygulama izinleri yönetici onayı gerektirdiğinde izin ve onay deneyimini açıklar.
• Bu Hızlı Başlangıçta: Microsoft kimlik platformu ile bir web API'sini koruma, kaynaklarına erişimi yalnızca yetkili hesaplarla kısıtlayarak ASP.NET web API'sini korumayı öğrenin.
• Bu Öğretici - Azure API Management'ta API'nizi dönüştürüp koruyun. Teknoloji yığını bilgilerini veya API'nin HTTP yanıtında özgün URL'leri gizlemek için ortak ilkeleri yapılandırma hakkında bilgi edinin.