Przewodnik dla deweloperów dotyczący kontekstu uwierzytelniania dostępu warunkowego

Dotyczy: Zielone koło z białym symbolem zaznaczenia, które wskazuje, że następująca treść dotyczy najemców pracowników. Najemcy pracowników Zielone koło z białym symbolem zaznaczenia, które wskazuje, że następująca treść dotyczy najemców zewnętrznych. Najemcy zewnętrzni (dowiedz się więcej)

Conditional Access to płaszczyzna sterowania Zero Trust, która umożliwia określanie zasad dostępu do wszystkich aplikacji — starych lub nowych, prywatnych lub publicznych, lokalnych lub wielochmurowych. Dzięki kontekstowi uwierzytelniania funkcji Dostęp warunkowy można zastosować różne zasady w tych aplikacjach.

Kontekst uwierzytelniania dostępu warunkowego (kontekst uwierzytelniania) umożliwia stosowanie szczegółowych zasad do poufnych danych i akcji zamiast tylko na poziomie aplikacji. Zasady zerowego zaufania można uściślić w celu uzyskania dostępu z najmniejszymi uprawnieniami, jednocześnie minimalizując utrudnienia dla użytkowników i zapewniając użytkownikom większą produktywność i bezpieczeństwo zasobów. Obecnie jest ona używana przez aplikacje opracowane przez Twoją firmę, korzystające z OpenId Connect do uwierzytelniania, w celu ochrony poufnych zasobów, takich jak transakcje o wysokiej wartości lub wyświetlanie danych osobowych pracowników.

Aby wyzwolić uwierzytelnianie podwyższonego poziomu z poziomu aplikacji i usług, użyj funkcji kontekstu uwierzytelniania mechanizmu dostępu warunkowego Microsoft Entra. Deweloperzy mogą teraz wymagać ulepszonego, silniejszego uwierzytelniania, w sposób wybiórczy, na przykład uwierzytelniania wieloskładnikowego od użytkowników końcowych z poziomu swoich aplikacji. Ta funkcja ułatwia deweloperom tworzenie bardziej płynnej obsługi aplikacji w większości obszarów aplikacji, podczas gdy dostęp do bezpieczniejszych operacji i danych jest nadal chroniony silniejszymi mechanizmami uwierzytelniania.

Sformułowanie problemu

Administratorzy IT i organy regulacyjne często mają trudności z zachowaniem równowagi między monitowaniem użytkowników o dodatkowe czynniki uwierzytelniania a osiągnięciem odpowiednich zabezpieczeń i przestrzegania zasad dla aplikacji. Może to być wybór między silnymi zasadami, które wpływają na wydajność użytkowników lub zasady, które nie są wystarczająco silne dla poufnych zasobów.

A co, gdyby aplikacje mogły połączyć oba te elementy? Działanie z niższym poziomem zabezpieczeń i mniejszą liczbą monitów dotyczących większości scenariuszy. Następnie warunkowe zwiększenie wymagań dotyczących zabezpieczeń w przypadku uzyskiwania dostępu do bardziej poufnych danych?

Typowe scenariusze

Na przykład użytkownicy mogą logować się do programu SharePoint przy użyciu uwierzytelniania wieloskładnikowego, ale uzyskiwanie dostępu do kolekcji witryn w programie SharePoint zawierającej poufne dokumenty może wymagać zgodnego urządzenia i być dostępne tylko z zaufanych zakresów adresów IP.

Wymagania wstępne

Najpierw należy zintegrować aplikację z platformą tożsamości firmy Microsoft przy użyciu protokołów OpenID Connect/ i OAuth 2.0 na potrzeby uwierzytelniania i autoryzacji. Zalecamy używanie bibliotek uwierzytelniania platformy tożsamości Microsoft do integrowania i zabezpieczania aplikacji przy użyciu identyfikatora Entra firmy Microsoft. dokumentacja platformy tożsamości Microsoft to dobre miejsce, aby zacząć uczyć się integrować aplikacje z platformą tożsamości Microsoft. Obsługa funkcji kontekstu uwierzytelniania dostępu warunkowego jest oparta na rozszerzeniach protokołu udostępnianych przez branżowy standardowy protokół OpenID Connect . Deweloperzy używają wartości odwołania kontekstu uwierzytelniania dostępu warunkowego z parametrem żądania claims, aby umożliwić aplikacjom wyzwalanie i spełnianie zasad.

Po drugiedostęp warunkowy wymaga licencjonowania Microsoft Entra ID P1. Więcej informacji na temat licencjonowania można znaleźć na stronie cennika firmy Microsoft Entra.

Po trzecie, obecnie jest dostępna tylko dla aplikacji, które logują użytkowników. Aplikacje, które uwierzytelniają się samodzielnie, nie są obsługiwane. Skorzystaj z przewodnika Przepływy uwierzytelniania i scenariusze aplikacji, aby dowiedzieć się więcej o obsługiwanych typach i przepływach aplikacji uwierzytelniania na platformie tożsamości Microsoft.

Kroki integracji

Możesz rozpocząć integrowanie tej funkcji w aplikacjach po jej zintegrowaniu przy użyciu obsługiwanych protokołów uwierzytelniania i zarejestrowaniu w dzierżawie Microsoft Entra, gdzie dostępna jest funkcja Dostępu warunkowego.

Uwaga

Szczegółowy przewodnik po tej funkcji jest również dostępny jako zarejestrowana sesja pod adresem Używanie kontekstu uwierzytelniania dostępu warunkowego w swojej aplikacji do uwierzytelniania krokowego.

Najpierw zadeklaruj i udostępnij konteksty uwierzytelniania w dzierżawcy. Aby uzyskać więcej informacji, zobacz Konfigurowanie kontekstów uwierzytelniania.

Wartości C1-C99 są dostępne do użycia jako identyfikatory kontekstu uwierzytelniania u dzierżawcy. Przykłady kontekstu uwierzytelniania mogą być następujące:

  • C1 — Wymagaj silnego uwierzytelniania
  • C2 — Wymagaj zgodnych urządzeń
  • C3 — wymagaj zaufanych lokalizacji

Aby użyć kontekstów uwierzytelniania dostępu warunkowego, utwórz lub zmodyfikuj zasady dostępu warunkowego. Przykładowe zasady mogą być następujące:

  • Wszyscy użytkownicy logujący się do tej aplikacji internetowej muszą pomyślnie ukończyć uwierzytelnianie 2FA dla identyfikatora kontekstu uwierzytelniania C1.
  • Wszyscy użytkownicy logujący się do tej aplikacji internetowej muszą pomyślnie ukończyć uwierzytelnianie 2FA, a także uzyskać dostęp do aplikacji ze zdefiniowanego zakresu adresów IP dla identyfikatora kontekstu uwierzytelniania C3.

Uwaga

Wartości kontekstu uwierzytelniania (auth context) dostępu warunkowego są deklarowane i utrzymywane oddzielnie od aplikacji. Nie zaleca się, aby aplikacje były twardo zależne od identyfikatorów kontekstu uwierzytelniania. Administratorzy IT zwykle tworzą zasady dostępu warunkowego, ponieważ lepiej rozumieją dostępne zasoby. Podobnie, jeśli aplikacja jest używana w wielu dzierżawcach, identyfikatory kontekstu uwierzytelniania w użyciu mogą być różne i, w niektórych przypadkach, niedostępne w ogóle.

Po drugie: deweloperzy aplikacji planujący korzystanie z Conditional Access auth context powinni najpierw udostępnić administratorom aplikacji lub administratorom IT środki umożliwiające mapowanie potencjalnych poufnych akcji na identyfikatory kontekstu uwierzytelniania. Kroki w przybliżeniu są następujące:

  1. Akcje związane z tożsamością w kodzie, które można udostępnić do mapowania na identyfikatory kontekstu uwierzytelniania.
  2. Utwórz ekran w portalu administracyjnym aplikacji (lub równoważną funkcjonalność), którego administratorzy IT mogą używać do mapowania poufnych akcji względem dostępnego identyfikatora kontekstu uwierzytelniania.
  3. Zobacz przykładowy kod , użyj kontekstu uwierzytelniania dostępu warunkowego, aby wykonać na przykład uwierzytelnianie krokowe .

Te kroki to zmiany, które należy wprowadzić w bazie kodu. Kroki zasadniczo obejmują

  • Wykonaj zapytanie względem programu MS Graph, aby wyświetlić listę wszystkich dostępnych kontekstów uwierzytelniania.
  • Zezwalaj administratorom IT na wybieranie operacji poufnych/o wysokich uprawnieniach i przypisywanie ich do dostępnych kontekstów uwierzytelniania przy użyciu zasad dostępu warunkowego.
  • Zapisz te informacje o mapowaniu w magazynie lokalnym/bazie danych.

Przepływ konfiguracji na potrzeby tworzenia kontekstu uwierzytelniania

Po trzecie: Aplikacja, a w tym przykładzie zakładamy, że jest to internetowy interfejs API, musi następnie ocenić wywołania względem zapisanego mapowania i odpowiednio zgłaszać żądania dotyczące claims dla aplikacji klienckich. Aby przygotować się do tej akcji, należy wykonać następujące czynności:

  1. W operacji wrażliwego kontekstu chronionego przez uwierzytelnianie należy ocenić wartości w claimie acrs względem mapowań identyfikatora kontekstu uwierzytelniania zapisanych wcześniej i zgłosić Claims Challenge, jak podano w poniższym fragmencie kodu.

  2. Na poniższym diagramie przedstawiono interakcję między użytkownikiem, aplikacją kliencką i internetowym interfejsem API.

    Diagram przedstawiający interakcję użytkownika, aplikacji internetowej, interfejsu API i Microsoft Entra ID

    Poniższy fragment kodu pochodzi z przykładowego kodu, użyj kontekstu uwierzytelniania dostępu warunkowego, aby przeprowadzić uwierzytelnianie podwyższonego poziomu. Pierwsza metoda CheckForRequiredAuthContext() w interfejsie API

    • Sprawdza, czy wywoływana akcja aplikacji wymaga dodatkowego uwierzytelnienia. Robi to, sprawdzając bazę danych pod kątem zapisanego mapowania dla tej metody
    • Jeśli ta akcja rzeczywiście wymaga kontekstu uwierzytelniania z podwyższonym poziomem uprawnień, sprawdza claim acrs pod kątem istniejącego, zgodnego identyfikatora kontekstu uwierzytelniania.
    • Jeśli nie znaleziono zgodnego identyfikatora kontekstu uwierzytelniania, zgłasza ono wezwanie dotyczące oświadczeń.
    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");
            }
        }
    }
}

    Uwaga

    Format wyzwania roszczeń został opisany w artykule Claims Challenge na platformie tożsamości firmy Microsoft.

  3. W aplikacji klienckiej przechwyć żądanie claims i przekieruj użytkownika z powrotem do Microsoft Entra ID w celu dalszej oceny zasad. Poniższy fragment kodu pochodzi z przykładowego kodu, Użyj kontekstu uwierzytelniania dostępu warunkowego, aby przeprowadzić uwierzytelnianie skokowe.

    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;
}

    Obsłuż wyjątek w wywołaniu internetowego interfejsu API, a jeśli zostanie przedstawione żądanie dotyczące deklaracji, przekieruj użytkownika z powrotem do Microsoft Entra ID w celu dalszego przetwarzania.

    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. (Opcjonalnie) Zadeklaruj możliwość klienta. Możliwości klienta pomagają dostawcom zasobów (RP) w taki sposób, jak nasz internetowy interfejs API, wykryć, czy aplikacja kliencka rozumie wyzwanie dotyczące oświadczeń, a następnie odpowiednio dostosować odpowiedź. Ta funkcja może być przydatna, gdy nie wszyscy klienci interfejsów API są w stanie obsługiwać żądania claim, a niektórzy starsi nadal oczekują innej odpowiedzi. Aby uzyskać więcej informacji, zobacz sekcję Możliwości klienta.

Zastrzeżenia i zalecenia

Nie wpisuj na stałe wartości kontekstu uwierzytelniania w aplikacji. Aplikacje powinny odczytywać i stosować kontekst uwierzytelniania przy użyciu wywołań programu MS Graph. Ta praktyka ma kluczowe znaczenie dla aplikacji wielodzierżawnych. Wartości kontekstu uwierzytelniania różnią się w zależności od dzierżaw Microsoft Entra i nie są dostępne w edycji Microsoft Entra ID Free. Aby uzyskać więcej informacji o tym, jak aplikacja powinna wykonywać zapytania, ustawiać i używać kontekstu uwierzytelniania w kodzie, zobacz przykładowy kod , użyj kontekstu uwierzytelniania dostępu warunkowego, aby przeprowadzić uwierzytelnianie krokowe.

Nie używaj kontekstu uwierzytelniania, w którym sama aplikacja będzie celem zasad dostępu warunkowego. Funkcja działa najlepiej, gdy części aplikacji wymagają od użytkownika wyższego poziomu uwierzytelnienia.

Przykłady kodu

Kontekst uwierzytelniania [ACRs] w dostępie warunkowym — oczekiwane zachowanie

Jawne spełnienie kontekstu uwierzytelniania w żądaniach

Klient może jawnie poprosić o token z kontekstem uwierzytelniania (ACRS) za pośrednictwem claimów w treści żądania. Jeśli zażądano ACRS, dostęp warunkowy umożliwia wystawianie tokenu z zażądanym ACRS, po zakończeniu wszystkich wyzwań.

Oczekiwane zachowanie, gdy kontekst uwierzytelniania nie jest chroniony przez Dostęp warunkowy w dzierżawcy

Dostęp warunkowy może umieszczać ACRS w deklaracjach tokenu, gdy wszystkie zasady dostępu warunkowego przypisane do wartości ACRS są spełnione. Jeśli do wartości ACRS nie przypisano żadnej polityki dostępu warunkowego, oświadczenie może być nadal wystawiane, ponieważ wszystkie wymagania dotyczące polityki są spełnione.

Tabela podsumowania oczekiwanego zachowania, gdy ACRS są jawnie żądane

Zażądano ACRS Zastosowano politykę Kontrola zakończona powodzeniem Usługa ACRS dodana do roszczeń
Tak Nie Tak Tak
Tak Tak Nie Nie
Tak Tak Tak Tak
Tak Brak skonfigurowanych zasad w ACRS Tak Tak

Niejawne spełnienie kontekstu uwierzytelniania przez ocenę oportunistyczną

Dostawca zasobów może zdecydować się na opcjonalny claim „acrs”. Dostęp warunkowy próbuje oportunistycznie dodać usługę ACRS do oświadczeń w tokenie, aby uniknąć dodatkowych żądań w celu uzyskania nowych tokenów do usługi Microsoft Entra ID. W tej ocenie Dostęp warunkowy sprawdza, czy zasady chroniące wyzwania związane z kontekstem uwierzytelniania są już spełnione i dodaje ACRS do oświadczeń tokenu, jeśli tak.

Uwaga

Każdy typ tokenu musi być indywidualnie wybrany (token identyfikatora, token dostępu).

Jeśli dostawca zasobów nie wyrazi zgody na opcjonalne oświadczenie "acrs", jedynym sposobem uzyskania usługi ACRS w tokenie jest jawne zażądanie go w żądaniu tokenu. Nie uzyska korzyści z oceny oportunistycznej, dlatego za każdym razem, gdy w oświadczeniach tokenu brakuje wymaganych ACRS, dostawca zasobów wzywa klienta do uzyskania nowego tokenu zawierającego je w oświadczeniach.

Oczekiwane zachowanie z kontekstem uwierzytelniania i kontrolkami sesji dla niejawnej oceny oportunistycznej ACRS

Częstotliwość logowania według interwału

Dostęp warunkowy uznaje „częstotliwość logowania określoną interwałem” za spełnioną podczas oportunistycznej oceny ACRS, gdy momenty uwierzytelnienia wszystkich obecnych czynników uwierzytelniania mieszczą się w interwale częstotliwości logowania. W przypadku, gdy którykolwiek z czynników uwierzytelniania jest nieaktualny, częstotliwość logowania według interwału nie zostanie spełniona, a ACRS nie zostanie przyznane w tokenie w sposób oportunistyczny.

Cloud App Security (CAS)

Dostęp warunkowy uznaje kontrolę sesji CAS za zadowalającą dla oportunistycznej oceny ACRS, gdy sesja CAS została ustanowiona podczas danego żądania. Na przykład w sytuacji, gdy nadejdzie żądanie i zostanie zastosowana oraz wymuszona jakakolwiek zasada dostępu warunkowego dotyczącą sesji CAS, a dodatkowo istnieje zasada dostępu warunkowego, która również wymaga sesji CAS, ponieważ sesja CAS zostanie wymuszona, co spełnia kontrolę sesji CAS dla oceny oportunistycznej.

Oczekiwane zachowanie, gdy dzierżawa zawiera zasady dostępu warunkowego chroniące kontekst uwierzytelniania

W poniższej tabeli przedstawiono wszystkie przypadki brzegowe, w których ACRS jest dodawane do roszczeń tokenu podczas oportunistycznej oceny.

Polityka A: Wymagaj uwierzytelniania wieloskładnikowego od wszystkich użytkowników, z wyłączeniem użytkownika "Ariel", podczas żądania acrs "c1". Polityka B: Blokuj wszystkich użytkowników, z wyjątkiem użytkownika „Jay”, gdy proszą o akr „c2” lub „c3”.

Flow Zażądano ACRS Zastosowana zasada Kontrola zakończona pomyślnie Usługa ACRS dodana do roszczeń
Ariel prosi o token dostępu c1 Brak Tak dla "c1". Nie dla "c2" i "c3" "c1" (zażądano)
Ariel prosi o token dostępu c2 Polityka B Zablokowane przez politykę B Brak
Ariel żąda tokenu dostępu Brak Brak Tak dla "c1". Nie dla "c2" i "c3" "c1" (dodane oportunistycznie z zasady A)
Jay prosi o token dostępu (bez uwierzytelniania wieloskładnikowego) c1 Zasady A Nie Brak
Jay prosi o token dostępu (z uwierzytelnianiem wieloskładnikowym) c1 Polityka A Tak "c1" (żądane), "c2" (oportunistycznie dodane z polityki B), "c3" (oportunistycznie dodane z polityki B)
Jay żąda tokenu dostępu (bez uwierzytelniania wieloskładnikowego) c2 Brak Tak dla "c2" i "c3". Nie dla "c1" "c2" (żądane), "c3" (dodane oportunistycznie z zasad B)
Jay żąda tokenu dostępu (z uwierzytelnianiem wieloskładnikowym) c2 Brak Tak dla "c1", "c2" i "c3" "c1" (w miarę możliwości przez A), "c2" (na żądanie), "c3" (dodane oportunistycznie z polityki B)
Jay żąda tokenu dostępu (z uwierzytelnianiem wieloskładnikowym) Brak Brak Tak dla "c1", "c2" i "c3" "c1", "c2", "c3" wszystkie dodane oportunistycznie
Jay żąda tokenu dostępu (bez uwierzytelniania wieloskładnikowego) Brak Brak Tak dla "c2" i "c3". Nie dla "c1" "c2", "c3" wszystkie dodane oportunistycznie

Następne kroki

  • Ostatnia aktualizacja o