Koşullu Erişim kimlik doğrulaması bağlamı için geliştirici kılavuzu

Şunlar için geçerlidir: İş gücü kiracıları Dış kiracılar (daha fazla bilgi edinin)

Koşullu Erişim, eski veya yeni, özel ya da genel, şirket içi veya çoklu bulut gibi tüm uygulamalarınıza erişim için ilkeleri hedeflemenizi sağlayan Sıfır Güven kontrol düzlemidir. Koşullu Erişim kimlik doğrulaması bağlamı ile bu uygulamalar içinde farklı ilkeler uygulayabilirsiniz.

Koşullu Erişim kimlik doğrulaması bağlamı (kimlik doğrulama bağlamı), hassas verilere ve eylemlere yalnızca uygulama düzeyinde değil ayrıntılı ilkeler uygulamanıza olanak tanır. En az ayrıcalıklı erişim için Sıfır Güven ilkelerinizi iyileştirebilir, kullanıcı sürtünmesini en aza indirirken kullanıcıların daha üretken ve kaynaklarınızın daha güvenli kalmasını sağlayabilirsiniz. Günümüzde, şirketiniz tarafından geliştirilen ve kimlik doğrulama için OpenId Connect kullanan uygulamalar tarafından, yüksek değerli işlemler veya çalışanların kişisel verilerinin görüntülenmesi gibi hassas kaynakları korumak için kullanılmaktadır.

Uygulamalarınızın ve hizmetlerinizin içinden adımlı kimlik doğrulamayı tetiklemek için Microsoft Entra Koşullu Erişim altyapısının kimlik doğrulama bağlamı özelliğini kullanın. Geliştiriciler artık uygulamalarının içinden son kullanıcılarından seçimli olarak MFA gibi güçlendirilmiş daha güçlü kimlik doğrulama talep etme gücüne sahiptir. Bu özellik, geliştiricilerin uygulamalarının çoğu bölümü için daha sorunsuz kullanıcı deneyimleri oluşturmasına yardımcı olurken, daha güvenli işlemlere ve verilere erişim daha güçlü kimlik doğrulama denetimlerinin arkasında kalır.

Sorun tanımı

BT yöneticileri ve düzenleyiciler, uygulamalar için yeterli güvenlik ve ilkelere uygunluk sağlamayla kullanıcılardan ek kimlik doğrulama faktörleri istemek arasında denge kurmakta çoğu zaman zorlanır. Kullanıcıların üretkenliğini etkileyen güçlü bir ilke ile hassas kaynaklar için yeterince güçlü olmayan bir ilke arasında seçim yapılabilir.

Peki ya uygulamalar ikisini de karıştırabildiyse? Daha düşük bir güvenlik düzeyiyle ve çoğu senaryo için daha az istemle çalışır. Daha hassas verilere erişilirken güvenlik gereksinimleri koşullu olarak artırılıyor mu?

Genel senaryolar

Örneğin, kullanıcılar çok faktörlü kimlik doğrulaması kullanarak SharePoint'te oturum açabilirken, SharePoint'te hassas belgeler içeren site koleksiyonuna erişmek uyumlu bir cihaz gerektirebilir ve yalnızca güvenilen IP aralıklarından erişilebilir.

Önkoşullar

İlk olarak, uygulamanız kimlik doğrulaması ve yetkilendirme için OpenID Connect ve OAuth 2.0 protokollerini kullanarak Microsoft kimlik platformuyla tümleştirilmelidir. Uygulamanızı Microsoft Entra ID ile tümleştirmek ve güvenliğini sağlamak için Microsoft kimlik platformu kimlik doğrulama kitaplıklarını kullanmanızı öneririz. Microsoft kimlik platformu belgeleri, uygulamalarınızı Microsoft kimlik platformu ile tümleştirmeyi öğrenmeye başlamak için iyi bir yerdir. Koşullu Erişim Kimlik Doğrulama Bağlamı özellik desteği, endüstri standardı OpenID Connect protokolü tarafından sağlanan protokol uzantılarının üzerine kurulmuştur. Geliştiriciler, uygulamalara ilkeyi tetikleme ve ilke gereksinimlerini karşılama olanağı sağlamak için Claims Request parametresiyle bir Koşullu Erişim Kimlik Doğrulama Bağlamı başvurudeğeri kullanır.

İkinci olarak, Koşullu Erişim için Microsoft Entra Id P1 lisansı gerekir. Lisanslama hakkında daha fazla bilgi Microsoft Entra fiyatlandırma sayfasında bulunabilir.

Üçüncüsü, bugün yalnızca kullanıcıların oturum açmasını sağlayan uygulamalarda kullanılabilir. Kendileri olarak kimlik doğrulayan uygulamalar desteklenmez. Microsoft kimlik platformunda desteklenen kimlik doğrulama uygulaması türleri ve akışları hakkında bilgi edinmek için Kimlik doğrulama akışları ve uygulama senaryoları kılavuzunu kullanın.

Entegrasyon adımları

Desteklenen kimlik doğrulama protokolleri kullanılarak tümleştirildikten ve Koşullu Erişim özelliğinin kullanılabildiği bir Microsoft Entra kiracısında kaydedildikten sonra bu özelliği uygulamalarınızla tümleştirmeye başlayabilirsiniz.

Not:

Bu özelliğin ayrıntılı bir kılavuzu, Ek doğrulama için uygulamanızda Koşullu Erişim Kimlik Doğrulama Bağlamını Kullanma başlıklı kayıtlı oturum olarak da sunulmaktadır.

İlk olarak, kimlik doğrulama bağlamlarını bildirin ve kiracınız için kullanılabilir hale getirin. Daha fazla bilgi için bkz. Kimlik doğrulama bağlamlarını yapılandırma.

C1-C99 değerleri, bir tenant içinde Kimlik Doğrulama Bağlamı Kimlikleri olarak kullanılabilir. Kimlik doğrulama bağlamı örnekleri şunlar olabilir:

• C1 - Güçlü kimlik doğrulaması gerektirir
• C2 – Uyumlu cihazlar gerektirir
• C3 – Güvenilen konumları zorunlu kıl

Koşullu Erişim Kimlik Doğrulama Bağlamlarını kullanmak için Koşullu Erişim ilkelerinizi oluşturun veya değiştirin. Örnek politikalar şunlar olabilir:

• Bu web uygulamasında oturum açmış olan tüm kullanıcıların C1 kimlik doğrulaması bağlam kimliği için 2FA'yı başarıyla tamamlaması gerekir.
• Bu web uygulamasında oturum açmış tüm kullanıcıların 2FA'yı başarıyla tamamlaması ve ayrıca C3 kimlik doğrulaması bağlam kimliği için tanımlanmış bir IP adresi aralığından uygulamaya erişmesi gerekir.

Not:

Koşullu Erişim kimlik doğrulama bağlamı değerleri uygulamalardan ayrı olarak tanımlanır ve korunur. Uygulamaların kimlik doğrulama bağlamı kimliklerine sıkı bağımlı olması önerilmez. BT Yöneticileri, kullanılabilir kaynakları daha iyi anladıkları için genellikle Koşullu Erişim ilkeleri oluşturur. Benzer şekilde, uygulama birden çok kiracıda kullanılıyorsa, kullanılan kimlik doğrulama bağlamı kimlikleri farklı olabilir ve bazı durumlarda hiç mevcut olmayabilir.

İkincisi: Koşullu Erişim kimlik doğrulaması bağlamını kullanmayı planlayan bir uygulamanın geliştiricilerinin önce uygulama yöneticilerine veya BT yöneticilerine olası hassas eylemleri auth context kimliklerine eşlemek için bir araç sağlamaları önerilir. Adımlar kabaca şu şekildedir:

1. Koddaki, auth context ID’leriyle eşleme için kullanılabilir hale getirilebilecek eylemleri belirleyin.
2. Bt yöneticilerinin hassas eylemleri kullanılabilir bir kimlik doğrulama bağlam kimliğiyle eşlemek için kullanabileceği uygulamanın yönetim portalında (veya eşdeğer bir işlevde) bir ekran oluşturun.
3. Kod örneğine bakın, örnek için adım adım kimlik doğrulama gerçekleştirmek için Koşullu Erişim Kimlik Doğrulama Bağlamını kullanma.

Bu adımlar, kod tabanınızda yapmanız gereken değişikliklerdir. Adımlar genel olarak oluşur

• kullanılabilir tüm Kimlik Doğrulama Bağlamlarını listele için MS Graph'ı sorgula.
• BT yöneticilerinin hassas/yüksek ayrıcalıklı işlemleri seçmesine ve Koşullu Erişim ilkelerini kullanarak bunları kullanılabilir Kimlik Doğrulama Bağlamlarına atamasına izin verin.
• Bu eşleme bilgilerini veritabanınıza/yerel deponuza kaydedin.

Üçüncü: Uygulamanız ve bu örnekte bunun bir web API'si olduğunu varsayarsak, ardından kaydedilen eşlemeye göre çağrıları değerlendirmesi ve buna göre istemci uygulamaları için claim challenge'lar oluşturması gerekir. Bu eyleme hazırlanmak için aşağıdaki adımlar atılmalıdır:

1. Kimlik doğrulama ile korunan hassas bir bağlam işleminde, acrs talebindeki değerleri daha önce kaydedilen Kimlik Doğrulama Bağlamı Kimliği eşlemelerine göre değerlendirin ve aşağıdaki kod parçacığında gösterildiği gibi bir Claims Challenge oluşturun.

2. Aşağıdaki diyagramda kullanıcı, istemci uygulaması ve web API'si arasındaki etkileşim gösterilmektedir.

   

   Aşağıdaki kod parçacığı, Ek kimlik doğrulama gerçekleştirmek için Koşullu Erişim kimlik doğrulama bağlamını kullanma kod örneğindendir. API'deki ilk yöntem, CheckForRequiredAuthContext()

   • Uygulamanın çağrılan eyleminin adım adım kimlik doğrulaması gerektip gerektirmediğini denetler. Bunu, bu yöntem için kaydedilmiş bir eşleme olup olmadığını kendi veritabanında denetleyerek yapar
   • Bu eylem gerçekten yükseltilmiş bir kimlik doğrulama bağlamı gerektiriyorsa, mevcut ve eşleşen bir Auth Context ID için acrs claim’ini denetler.
   • Eşleşen bir Kimlik Doğrulama Bağlam Kimliği bulunamazsa, bir claims challenge oluşturur.

   public void CheckForRequiredAuthContext(string method)
   {
       string authType = _commonDBContext.AuthContext.FirstOrDefault(x => x.Operation == method
                   && x.TenantId == _configuration["AzureAD:TenantId"])?.AuthContextId;
   
       if (!string.IsNullOrEmpty(authType))
       {
           HttpContext context = this.HttpContext;
           string authenticationContextClassReferencesClaim = "acrs";
   
           if (context == null || context.User == null || context.User.Claims == null
               || !context.User.Claims.Any())
           {
               throw new ArgumentNullException("No Usercontext is available to pick claims from");
           }
   
           Claim acrsClaim = context.User.FindAll(authenticationContextClassReferencesClaim).FirstOrDefault(x
               => x.Value == authType);
   
           if (acrsClaim == null || acrsClaim.Value != authType)
           {
               if (IsClientCapableofClaimsChallenge(context))
               {
                   string clientId = _configuration.GetSection("AzureAd").GetSection("ClientId").Value;
                   var base64str = Convert.ToBase64String(Encoding.UTF8.GetBytes("{\"access_token\":{\"acrs\":{\"essential\":true,\"value\":\"" + authType + "\"}}}"));
   
                   context.Response.Headers.Append("WWW-Authenticate", $"Bearer realm=\"\", authorization_uri=\"https://login.microsoftonline.com/common/oauth2/authorize\", client_id=\"" + clientId + "\", error=\"insufficient_claims\", claims=\"" + base64str + "\", cc_type=\"authcontext\"");
                   context.Response.StatusCode = (int)HttpStatusCode.Unauthorized;
                   string message = string.Format(CultureInfo.InvariantCulture, "The presented access tokens had insufficient claims. Please request for claims requested in the WWW-Authentication header and try again.");
                   context.Response.WriteAsync(message);
                   context.Response.CompleteAsync();
                   throw new UnauthorizedAccessException(message);
               }
               else
               {
                   throw new UnauthorizedAccessException("The caller does not meet the authentication  bar to carry our this operation. The service cannot allow this operation");
               }
           }
       }
   }
   

   Not:

   Claims challenge biçimi, Microsoft kimlik platformunda claims challenge makalesinde açıklanmıştır.

3. İstemci uygulamasında talep sorgulamasını yakalayın ve daha fazla ilke değerlendirmesi için kullanıcıyı Microsoft Entra ID'ye yeniden yönlendirin. Aşağıdaki kod parçacığı, Ek kimlik doğrulaması gerçekleştirmek için Koşullu Erişim kimlik doğrulama bağlamını kullanın kod örneğindendir.

   internal static string ExtractHeaderValues(WebApiMsalUiRequiredException response)
   {
       if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized && response.Headers.WwwAuthenticate.Any())
       {
           AuthenticationHeaderValue bearer = response.Headers.WwwAuthenticate.First(v => v.Scheme == "Bearer");
           IEnumerable<string> parameters = bearer.Parameter.Split(',').Select(v => v.Trim()).ToList();
           var errorValue = GetParameterValue(parameters, "error");
   
           try
           {
               // read the header and checks if it contains error with insufficient_claims value.
               if (null != errorValue && "insufficient_claims" == errorValue)
               {
                   var claimChallengeParameter = GetParameterValue(parameters, "claims");
                   if (null != claimChallengeParameter)
                   {
                       var claimChallenge = ConvertBase64String(claimChallengeParameter);
   
                       return claimChallenge;
                   }
               }
           }
           catch (Exception ex)
           {
               throw ex;
           }
       }
       return null;
   }
   

   Web API'sine yapılan çağrıda istisnayı işleyin. claims challenge sunulursa, daha fazla işlem için kullanıcıyı Microsoft Entra ID'ye yeniden yönlendirin.

   try
   {
       // Call the API
       await _todoListService.AddAsync(todo);
   }
   catch (WebApiMsalUiRequiredException hex)
   {
       // Challenges the user if exception is thrown from Web API.
       try
       {
           var claimChallenge =ExtractHeaderValues(hex);
           _consentHandler.ChallengeUser(new string[] { "user.read" }, claimChallenge);
   
           return new EmptyResult();
       }
       catch (Exception ex)
       {
           _consentHandler.HandleException(ex);
       }
   
       Console.WriteLine(hex.Message);
   }
   return RedirectToAction("Index");
   

4. (İsteğe bağlı) İstemci yeteneğini bildirin. İstemci özellikleri, Web API'miz gibi kaynak sağlayıcılarının (RP) istemci uygulamasının talep sınamasını anlayıp anlayamayacağını algılamasına ve ardından yanıtını buna göre özelleştirebilmesine yardımcı olur. Bu özellik, tüm API istemcilerinin claim doğrulama zorluklarını işleyemediği ve bazı eski istemcilerin hâlâ farklı bir yanıt beklediği durumlarda yararlı olabilir. Daha fazla bilgi için İstemci özellikleri bölümüne bakın.

Uyarılar ve öneriler

Uygulamanızda Kimlik Doğrulama Bağlamı değerlerini sabit kodlamayın. Uygulamaların kimlik doğrulama bağlamını MS Graph çağrılarını kullanarak okuması ve uygulaması gerekir. Bu uygulama, çok kiracılı uygulamalar için kritik öneme sahiptir. Kimlik Doğrulama Bağlamı değerleri Microsoft Entra kiracıları arasında farklılık gösterir ve Microsoft Entra ID Free sürümünde kullanılamaz. Bir uygulamanın kodunda kimlik doğrulama bağlamını nasıl sorgulaması, ayarlaması ve kullanması gerektiği hakkında daha fazla bilgi için, adım adım kimlik doğrulaması gerçekleştirmek için Koşullu Erişim kimlik doğrulaması bağlamını kullanma kod örneğine bakın.

Uygulamanın kendisinin Koşullu Erişim ilkelerinin hedefi olacağı durumlarda kimlik doğrulama bağlamı kullanmayın. Uygulamanın bazı bölümleri kullanıcının daha yüksek bir kimlik doğrulama düzeyine uymasını gerektirdiğinde bu özellik en iyi şekilde çalışır.

Kod örnekleri

• Bir web uygulamasında yüksek ayrıcalıklı işlemler için adım adım kimlik doğrulaması gerçekleştirmek için Koşullu Erişim kimlik doğrulaması bağlamını kullanın
• Bir web API'sinde yüksek ayrıcalıklı işlemler için ek kimlik doğrulama gerçekleştirmek amacıyla Koşullu Erişim kimlik doğrulama bağlamını kullanın
• Tek sayfalı React uygulamasında ve Express web API'sinde yüksek ayrıcalıklı işlemler için ek doğrulama gerçekleştirmek üzere Koşullu Erişim kimlik doğrulaması bağlamını kullanın

Koşullu Erişim'de kimlik doğrulama bağlamı [ACRs] beklenen davranış

İsteklerde açık kimlik doğrulama bağlamının karşılanması

İstemci, isteğin gövdesindeki claimler aracılığıyla Kimlik Doğrulama Bağlamı (ACRS) içeren bir token’ı açıkça isteyebilir. Bir ACRS istenirse, Koşullu Erişim tüm sınamalar tamamlandıysa istenen ACRS ile belirtecin verilmesine izin verir.

Kimlik doğrulama bağlamı kiracıda Koşullu Erişim tarafından korunmadığında beklenen davranış

Koşullu Erişim, ACRS değerine atanan tüm Koşullu Erişim politikaları karşılandığında, belirtecin taleplerinde bir ACRS değeri verebilir. Bir ACRS değerine koşullu erişim ilkesi atanmamışsa, tüm ilke gereksinimleri karşılandığından talep yine de verilmiş olabilir.

ACRS açıkça istendiğinde beklenen davranış için özet tablo

ACRS istendi	Politika uygulandı	Kontrol sağlandı	Taleplere ACRS eklendi
Evet	Hayır	Evet	Evet
Evet	Evet	Hayır	Hayır
Evet	Evet	Evet	Evet
Evet	ACRS ile yapılandırılan ilke yok	Evet	Evet

Fırsatçı değerlendirme ile örtük kimlik doğrulama bağlamının karşılanması

Bir kaynak sağlayıcısı, isteğe bağlı 'acrs' claim'ini etkinleştirmeyi seçebilir. Koşullu Erişim, Microsoft Entra ID'ye yeni belirteçler almak için gidiş dönüşlerden kaçınmak amacıyla belirteç claim'lerine fırsatçı olarak ACRS eklemeye çalışır. Bu değerlendirmede Koşullu Erişim, Auth Context sınamalarını koruyan ilkelerin zaten karşılanıp karşılanmadığını denetler ve varsa ACRS'yi belirteç claim'lerine ekler.

Not:

Her belirteç türünün tek tek kabul edilmesi gerekir (kimlik belirteci, Erişim belirteci).

Bir kaynak sağlayıcısı isteğe bağlı 'acrs' talebini kabul etmezse, belirteçte ACRS almanın tek yolu bunu açıkça belirteç isteğinde istemektir. Fırsatçı değerlendirme avantajlarından yararlanmaz, bu nedenle gereken ACRS belirteç taleplerinde her eksik olduğunda, kaynak sağlayıcısı istemciden taleplerde onu içeren yeni bir belirteç edinmesini talep eder.

Örtük ACRS fırsatçı değerlendirmesi için kimlik doğrulama bağlamı ve oturum denetimleriyle ilgili beklenen davranış

Aralığa göre oturum açma sıklığı

Koşullu Erişim, mevcut kimlik doğrulama faktörlerinin kimlik doğrulama anlarının tümü oturum açma sıklığı aralığı içinde olduğunda oportünistik ACRS değerlendirmesi için "zaman aralığına göre oturum açma sıklığını" karşılanmış sayar. Her iki kimlik doğrulama faktörünün de eski olması durumunda, oturum açma sıklığı zaman aralığına göre karşılanmayacak ve ACRS belirteçte fırsatçı olarak verilmeyecektir.

Bulut Uygulamaları Güvenliği (CAS)

Koşullu Erişim, bu istek sırasında bir CAS oturumu oluşturulduğunda fırsatçı ACRS değerlendirmesi için CAS oturum denetiminin uygun olduğunu kabul eder. Örneğin, bir istek geldiğinde ve herhangi bir Koşullu Erişim ilkesi CAS oturumunun uygulanmasını ve yürürlüğe konmasını gerektirdiğinde, ayrıca bir CAS oturumu gerektiren başka bir Koşullu Erişim ilkesi de varsa, CAS oturumu zorunlu kılındığından fırsatçı değerlendirme için CAS oturumu denetimi sağlanmış olur.

Kiracıda kimlik doğrulama bağlamını koruyan Koşullu Erişim ilkeleri bulunduğunda beklenen davranış

Aşağıdaki tabloda, ACRS'nin uygun koşullar altında belirtecin taleplerine eklendiği tüm uç durumlar gösterilmektedir.

İlke A: "c1" acrs istenirken, "Ariel" kullanıcısı hariç tüm kullanıcılardan MFA iste. İlke B: "c2" veya "c3" acrs istendiğinde, "Jay" kullanıcısı hariç tüm kullanıcıları engelleyin.

Akış	ACRS istendi	Politika uygulandı	Kontrol sağlandı	Taleplere ACRS eklendi
Ariel bir erişim belirteci ister	"c1"	Hiçbiri	"c1" için Evet. "c2" ve "c3" için hayır	"c1" (istenen)
Ariel erişim belirteci için istekte bulunur	"c2"	Politika B	B politikası tarafından engellendi	Hiçbiri
Ariel erişim belirteci için istekte bulunur	Hiçbiri	Hiçbiri	"c1" için Evet. "c2" ve "c3" için hayır	"c1" (A ilkesinden duruma bağlı olarak eklendi)
Jay erişim belirteci ister (MFA olmadan)	"c1"	Politika A	Hayır	Hiçbiri
Jay erişim belirteci için istekte bulunur (MFA ile)	"c1"	Politika A	Evet	"c1" (istenen), "c2" (B ilkesinden fırsatçı olarak eklendi), "c3" (B ilkesinden fırsatçı olarak eklendi)
Jay, erişim belirteci ister (MFA olmadan)	"c2"	Hiçbiri	"c2" ve "c3" için evet. "c1" için hayır	"c2" (istenen), "c3" (B ilkesinden uygun olduğunda eklendi)
Jay erişim belirteci ister (MFA ile)	"c2"	Hiçbiri	"c1", "c2" ve "c3" için evet	"c1" (A'dan en iyi çaba), "c2" (istenen), "c3" (uygun olduğunda B ilkesinden eklenmiş)
Jay erişim belirteci ister (MFA ile)	Hiçbiri	Hiçbiri	"c1", "c2" ve "c3" için evet	"c1", "c2", "c3" hepsi duruma göre eklendi
Jay, erişim belirteci ister (MFA olmadan)	Hiçbiri	Hiçbiri	"c2" ve "c3" için evet. "c1" için hayır	"c2", "c3" tümü uygun olduğunda eklendi

Sonraki adımlar

• Hassas veriler ve eylemler için Ayrıntılı Koşullu Erişim (Blog)
• Microsoft kimlik platformu ile sıfır güven
• Microsoft kimlik platformu ile Sıfır Güven’e hazır uygulamalar oluşturma
• Koşullu Erişim kimlik doğrulaması bağlamı
• authenticationContextClassReference kaynak türü - MS Graph
• Microsoft kimlik platformunda istem sınaması, istem isteği ve istemci özellikleri
• Microsoft Purview Bilgi Koruması ve SharePoint ile kimlik doğrulama bağlamını kullanma
• Uygulamalarınızda Sürekli Erişim Değerlendirmesi özellikli API'leri nasıl kullanacağınız