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

Şunlar için geçerlidir: Aşağıdaki içeriğin iş gücü kiracıları için geçerli olduğunu gösteren beyaz onay işareti simgesine sahip yeşil daire. İş gücü kiracıları Aşağıdaki içeriğin dış kiracılar için geçerli olduğunu gösteren beyaz onay işareti simgesine sahip yeşil daire. 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 denetim 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 daraltabilir, kullanıcı uyuşmalarını en aza indirir ve kullanıcıların daha üretken ve kaynaklarınızın daha güvenli kalmasını sağlayabilirsiniz. Günümüzde, yüksek değerli işlemler veya çalışan kişisel verilerini görüntüleme gibi hassas kaynakları korumak amacıyla şirketiniz tarafından geliştirilen kimlik doğrulaması için OpenId Connect kullanan uygulamalar tarafından kullanılmaktadır.

Uygulamalarınızın ve hizmetlerinizin içinden bir adım adım kimlik doğrulaması tetikleme 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ının MFA'sı gibi daha güçlü kimlik doğrulaması isteme 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 bildirimi

BT yöneticileri ve düzenleyicileri genellikle kullanıcılara ek kimlik doğrulama faktörleriyle dengelemek ve uygulamalar için yeterli güvenlik ve ilkeye uygunluk sağlamakta zorlanmaktadı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 ConnectMicrosoft kimlik platformu ile 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 tetiklemenin ve karşılamanın bir yolunu sunmak için Talep İsteği 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 oturum açma kullanıcıları tarafından kullanılabilir. Kendi kimliklerini doğrulayan uygulamalar desteklenmez. Microsoft kimlik platformu 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.

Tümleştirme 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, adım adım kimlik doğrulaması için uygulamanızda Koşullu Erişim Kimlik Doğrulama Bağlamını kullanma başlığında kayıtlı oturum olarak da kullanılabilir.

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

C1-C99 değerleri bir kiracıda Kimlik Doğrulama Bağlamı Kimlikleri olarak kullanılabilir. Kimlik doğrulama bağlamı örnekleri şunlar olabilir:

C1 - Güçlü kimlik doğrulaması gerektir
C2 – Uyumlu cihazlar gerektir
C3 – Güvenilen konumlar gerektir

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 ilkeler ş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ğrulaması bağlam değerleri uygulamalardan ayrı olarak bildirilir ve korunur. Uygulamaların kimlik doğrulama bağlamı kimliklerine sıkı bağımlılık alması ö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ç kullanılamayabilir.

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

Koddaki kimlik eylemleri, kimlik doğrulama bağlamı kimlikleriyle eşlenecek şekilde kullanılabilir hale getirilebilir.
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.
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 taşımanız gereken değişikliklerdir. Adımlar genel olarak

Kullanılabilir tüm Kimlik Doğrulama Bağlamlarını listelemek 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 göre atamasına izin verin.
Bu eşleme bilgilerini veritabanınıza/yerel deponuza kaydedin.

Kimlik doğrulama bağlamı oluşturmak için kurulum akışı

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

Hassas ve kimlik doğrulama bağlamı ile korunan bir işlemde, 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 Talep Sınaması oluşturun.

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

Kullanıcı, web uygulaması, API ve Microsoft Entra Id etkileşimini gösteren diyagram

Aşağıdaki kod parçacığı, adım adım kimlik doğrulaması gerçekleştirmek için Koşullu Erişim kimlik doğrulaması bağlamını kullanın kod örneğinden alınmalıdır. API'deki ilk yöntem CheckForRequiredAuthContext()

Uygulamanın çağrılan eyleminin adım adım kimlik doğrulaması gerektip gerektirmediğini denetler. Bu yöntem için veritabanını kaydedilmiş eşleme için denetleyerek bunu yapar
Bu eylem gerçekten yükseltilmiş bir kimlik doğrulama bağlamı gerektiriyorsa, mevcut, eşleşen kimlik doğrulama bağlamı kimliği için acrs talebi denetler.
Eşleşen bir Kimlik Doğrulama Bağlam Kimliği bulunamazsa, bir talep sınaması 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

Talep sınamasının biçimi, Microsoft kimlik platformu Talep Sınaması makalesinde açıklanmıştır.

İstemci uygulamasında talep sınamasını engelleyin ve daha fazla ilke değerlendirmesi için kullanıcıyı Microsoft Entra Id'ye yeniden yönlendirin. Aşağıdaki kod parçacığı, adım adım kimlik doğrulaması gerçekleştirmek için Koşullu Erişim kimlik doğrulaması bağlamını kullanın kod örneğinden alınmalıdır.

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 özel durumu işleyin. Talep sınaması sunulursa, daha fazla işlem için kullanıcıyı Microsoft Entra Kimliği'ne 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");

(İsteğe bağlı) İstemci özelliğ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 talep sınamalarını işleyemediği ve bazı eski istemcilerin 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 MS Graph çağrılarını kullanarak kimlik doğrulama bağlamını 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 kendisi Koşullu Erişim ilkelerinin hedefi olacak kimlik doğrulama bağlamını kullanmayın. Uygulamanın bazı bölümleri kullanıcının daha yüksek bir kimlik doğrulama çubuğuna uymasını gerektirdiğinde bu özellik en iyi şekilde çalışır.

Kod örnekleri

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

İsteklerde açık kimlik doğrulama bağlamı memnuniyeti

İstemci, isteğin gövdesindeki talepler aracılığıyla kimlik doğrulama bağlamı (ACRS) içeren bir belirteci 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	İlke uygulandı	Denetim karşılandı	Taleplere ACRS eklendi
Evet	Hayı	Evet	Evet
Evet	Evet	Hayı	Hayı
Evet	Evet	Evet	Evet
Evet	ACRS ile yapılandırılmış ilke yok	Evet	Evet

Fırsatçı değerlendirme ile örtük kimlik doğrulama bağlamı memnuniyeti

Bir kaynak sağlayıcısı isteğe bağlı 'acrs' talebine kabul edebilir. Koşullu Erişim, Microsoft Entra Id'ye yeni belirteçler almak için gidiş dönüşlerden kaçınmak için belirteç taleplerine fırsatçı olarak ACRS eklemeye çalışır. Bu değerlendirmede Koşullu Erişim, Kimlik Doğrulama Bağlamı sınamalarını koruyan ilkelerin zaten karşılanıp karşılanmadığını denetler ve varsa ACRS'yi belirteç taleplerine 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ğerlendirme için kimlik doğrulama bağlamı ve oturum denetimleriyle beklenen davranış

Koşullu Erişim, mevcut kimlik doğrulama faktörlerinin kimlik doğrulama anlık değerlerinin tümü oturum açma sıklığı aralığı içinde olduğunda fırsatçı ACRS değerlendirmesi için "zaman aralığına göre oturum açma sıklığını" kabul eder. 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ı kimlik doğrulama bağlamı koruyan Koşullu Erişim ilkeleri içerdiğinde 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 isterken "Ariel" kullanıcısı hariç tüm kullanıcılardan MFA iste. İlke B: "c2" veya "c3" acrs isterken "Jay" kullanıcısı hariç tüm kullanıcıları engelleyin.

Akış	ACRS istendi	İlke uygulandı	Denetim karşılandı	Taleplere ACRS eklendi
Ariel erişim belirteci için istekte bulunma	"c1"	Hiçbiri	"C1" için evet. "c2" ve "c3" için hayır	"c1" (istenen)
Ariel erişim belirteci için istekte bulunma	"c2"	İlke B	İlke B tarafından engellendi	Hiçbiri
Ariel erişim belirteci için istekte bulunma	Hiçbiri	Hiçbiri	"C1" için evet. "c2" ve "c3" için hayır	"c1" (A ilkesinden fırsatçı olarak eklendi)
Jay erişim belirteci için istekte bulunma (MFA olmadan)	"c1"	İlke A	Hayı	Hiçbiri
Jay erişim belirteci için istekte bulunma (MFA ile)	"c1"	İlke A	Evet	"c1" (istenen), "c2" (B ilkesinden fırsatçı olarak eklendi), "c3" (B ilkesinden fırsatçı olarak eklendi)
Jay erişim belirteci için istekte bulunma (MFA olmadan)	"c2"	Hiçbiri	"c2" ve "c3" için evet. "c1" için hayır	"c2" (istenen), "c3" (B ilkesinden fırsatçı olarak eklendi)
Jay erişim belirteci için istekte bulunma (MFA ile)	"c2"	Hiçbiri	"c1", "c2" ve "c3" için evet	"c1" (A'dan en iyi çaba), "c2" (istenen), "c3" (B ilkesinden fırsatçı olarak eklendi)
Jay erişim belirteci için istekte bulunma (MFA ile)	Hiçbiri	Hiçbiri	"c1", "c2" ve "c3" için evet	"c1", "c2", "c3" tüm fırsatçı olarak eklendi
Jay erişim belirteci için istekte bulunma (MFA olmadan)	Hiçbiri	Hiçbiri	"c2" ve "c3" için evet. "c1" için hayır	"c2", "c3" tüm fırsatçı olarak eklendi

Sonraki adımlar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-09-11