Guia do desenvolvedor para o contexto de autenticação de Acesso Condicional

  • Artigo

O Acesso Condicional é o plano de controlo Zero Trust que lhe permite direcionar políticas de acesso a todas as suas aplicações – antigas ou novas, privadas ou públicas, no local ou multicloud. Com o contexto de autenticação de Acesso Condicional, você pode aplicar políticas diferentes nesses aplicativos.

O contexto de autenticação de Acesso Condicional (contexto de autenticação) permite que você aplique políticas granulares a dados e ações confidenciais em vez de apenas no nível do aplicativo. Você pode refinar suas políticas de Zero Trust para acesso menos privilegiado, minimizando o atrito do usuário e mantendo os usuários mais produtivos e seus recursos mais seguros. Hoje, ele é usado por aplicativos que usam o OpenId Connect para autenticação desenvolvida pela sua empresa para proteger recursos confidenciais, como transações de alto valor ou visualização de dados pessoais de funcionários.

Para acionar uma autenticação step-up de dentro de seus aplicativos e serviços, use o recurso de contexto de autenticação do mecanismo de Acesso Condicional do Microsoft Entra. Os desenvolvedores agora têm o poder de exigir autenticação mais forte aprimorada, seletivamente, como MFA, de seus usuários finais de dentro de seus aplicativos. Esse recurso ajuda os desenvolvedores a criar experiências de usuário mais suaves para a maioria das partes de seus aplicativos, enquanto o acesso a operações e dados mais seguros permanece por trás de controles de autenticação mais fortes.

Declaração do problema

Os administradores e reguladores de TI muitas vezes lutam entre equilibrar a solicitação de seus usuários com fatores extras de autenticação com muita frequência e alcançar segurança adequada e adesão à política para aplicativos e serviços em que partes deles contêm dados e operações confidenciais. Pode ser uma escolha entre uma política forte que afeta a produtividade dos usuários quando eles acessam a maioria dos dados e ações ou uma política que não é forte o suficiente para recursos confidenciais.

Então, e se os aplicativos fossem capazes de misturar ambos, onde eles podem funcionar com uma segurança relativamente menor e prompts menos frequentes para a maioria dos usuários e operações e, ainda assim, aumentar condicionalmente o requisito de segurança quando os usuários acessam partes mais sensíveis?

Cenários comuns

Por exemplo, embora os usuários possam entrar no SharePoint usando a autenticação multifator, o acesso ao conjunto de sites no SharePoint contendo documentos confidenciais pode exigir um dispositivo compatível e só ser acessível a partir de intervalos de IP confiáveis.

Pré-requisitos

Primeiro, seu aplicativo deve ser integrado à plataforma de identidade da Microsoft usando os protocolos OpenID Connect/ OAuth 2.0 para autenticação e autorização. Recomendamos que você use as bibliotecas de autenticação da plataforma de identidade da Microsoft para integrar e proteger seu aplicativo com o Microsoft Entra ID. A documentação da plataforma de identidade da Microsoft é um bom lugar para começar a aprender como integrar seus aplicativos à plataforma de identidade da Microsoft. O suporte ao recurso Conditional Access Auth Context é construído com base nas extensões de protocolo fornecidas pelo protocolo OpenID Connect padrão da indústria. Os desenvolvedores usam um valor de referênciade Contexto de Autenticação de Acesso Condicional com o parâmetro Solicitação de Declarações para dar aos aplicativos uma maneira de acionar e satisfazer a política.

Em segundo lugar, o Acesso Condicional requer o licenciamento do Microsoft Entra ID P1. Mais informações sobre licenciamento podem ser encontradas na página de preços do Microsoft Entra.

Em terceiro lugar, hoje ele só está disponível para aplicativos que fazem login em usuários. Não há suporte para aplicativos que se autenticam como eles mesmos. Use o guia Fluxos de autenticação e cenários de aplicativos para saber mais sobre os tipos e fluxos de aplicativos de autenticação com suporte na plataforma de identidade da Microsoft.

Etapas de integração

Depois que seu aplicativo estiver integrado usando os protocolos de autenticação suportados e registrado em um locatário do Microsoft Entra que tenha o recurso Acesso Condicional disponível para uso, você poderá iniciar o processo para integrar esse recurso em seus aplicativos que entram usuários.

Nota

Um passo a passo detalhado desse recurso também está disponível como uma sessão gravada em Usar contexto de autenticação de acesso condicional em seu aplicativo para autenticação gradual.

Primeiro, declare e disponibilize os contextos de autenticação em seu locatário. Para obter mais informações, consulte Configurar contextos de autenticação.

Os valores C1-C99 estão disponíveis para uso como IDs de contexto de autenticação em um locatário. Exemplos de contexto de autenticação podem ser:

  • C1 - Exigir autenticação forte
  • C2 – Requer dispositivos compatíveis
  • C3 – Requer locais confiáveis

Crie ou modifique suas políticas de Acesso Condicional para usar os Contextos de Autenticação de Acesso Condicional. Exemplos de políticas poderiam ser:

  • Todos os usuários que entrarem neste aplicativo Web devem ter concluído com êxito 2FA para o ID de contexto de autenticação C1.
  • Todos os usuários que entrarem neste aplicativo Web devem ter concluído com êxito o 2FA e também acessar o aplicativo Web a partir de um determinado intervalo de endereços IP para o ID de contexto de autenticação C3.

Nota

Os valores de contexto de autenticação de Acesso Condicional são declarados e mantidos separadamente dos aplicativos. Não é aconselhável que os aplicativos dependam fortemente de ids de contexto de autenticação. As políticas de Acesso Condicional geralmente são criadas por administradores de TI, pois eles têm uma melhor compreensão dos recursos disponíveis para aplicar políticas. Por exemplo, para um locatário do Microsoft Entra, os administradores de TI teriam o conhecimento de quantos usuários do locatário estão equipados para usar 2FA para MFA e, portanto, podem garantir que as políticas de Acesso Condicional que exigem 2FA tenham escopo para esses usuários equipados. Da mesma forma, se o aplicativo for usado em vários locatários, as ids de contexto de autenticação em uso poderão ser diferentes e, em alguns casos, não estarão disponíveis.

Segundo: Os desenvolvedores de um aplicativo que planeja usar o contexto de autenticação de Acesso Condicional são aconselhados a primeiro fornecer aos administradores de aplicativos ou administradores de TI um meio de mapear possíveis ações confidenciais para IDs de contexto de autenticação. As etapas são, grosso modo:

  1. Ações de identidade no código que podem ser disponibilizadas para mapear em relação a IDs de contexto de autenticação.
  2. Crie uma tela no portal de administração do aplicativo (ou uma funcionalidade equivalente) que os administradores de TI possam usar para mapear ações confidenciais em relação a um ID de contexto de autenticação disponível.
  3. Consulte o exemplo de código, Use the Conditional Access Auth Context to perform step-up authentication para obter um exemplo de como isso é feito.

Essas etapas são as alterações que você precisa carregar em sua base de código. As etapas compreendem, em termos gerais,

  • Consulte o MS Graph para listar todos os contextos de autenticação disponíveis.
  • Permita que os administradores de TI selecionem operações confidenciais/com privilégios elevados e as atribuam em relação aos contextos de autenticação disponíveis usando políticas de acesso condicional.
  • Salve essas informações de mapeamento em seu banco de dados/armazenamento local.

Fluxo de configuração para criar um contexto de autenticação

Terceiro: Seu aplicativo e, para este exemplo, assumimos que é uma API da Web, precisa avaliar as chamadas em relação ao mapeamento salvo e, consequentemente, levantar desafios de reivindicação para seus aplicativos cliente. Para preparar esta ação, devem ser tomadas as seguintes medidas:

  1. Em uma operação sensível e protegida por contexto de autenticação, avalie os valores na declaração acrs em relação aos mapeamentos de ID de contexto de autenticação salvos anteriormente e gere um desafio de reivindicações , conforme previsto no trecho de código a seguir.

  2. O diagrama a seguir mostra a interação entre o usuário, o aplicativo cliente e a API da Web.

    Diagrama mostrando a interação do usuário, aplicativo Web, API e ID do Microsoft Entra

    O trecho de código a seguir é do exemplo de código, Use the Conditional Access auth context to perform step-up authentication. O primeiro método, CheckForRequiredAuthContext() na API

    • Verifica se a ação do aplicativo que está sendo chamada requer autenticação step-up. Ele faz isso verificando seu banco de dados para um mapeamento salvo para esse método
    • Se essa ação realmente exigir um contexto de autenticação elevado, ela verificará a reivindicação acrs para um ID de contexto de autenticação existente e correspondente.
    • Se um ID de contexto de autenticação correspondente não for encontrado, ele levantará um desafio de reivindicação.
    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");
            }
        }
    }
}

    Nota

    O formato do desafio de declarações é descrito no artigo, Claims Challenge in the Microsoft identity platform.

  3. No aplicativo cliente, intercete o desafio de declarações e redirecione o usuário de volta para o Microsoft Entra ID para avaliação adicional da política. O trecho de código a seguir é do exemplo de código, Use the Conditional Access auth context to perform step-up authentication.

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

    Manipule a exceção na chamada para API da Web, se um desafio de declarações for apresentado, redirecione o usuário de volta para o Microsoft Entra ID para processamento posterior.

    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. (Opcional) Declare a capacidade do cliente. Os recursos do cliente ajudam os provedores de recursos (RP), como nossa API da Web acima, a detetar se o aplicativo cliente chamador entende o desafio de declarações e pode personalizar sua resposta de acordo. Esse recurso pode ser útil quando nem todos os clientes de APIs são capazes de lidar com desafios de sinistro e alguns mais antigos ainda esperam uma resposta diferente. Para obter mais informações, consulte a seção Recursos do cliente.

Advertências e recomendações

Não codifice valores de contexto de autenticação em seu aplicativo. Os aplicativos devem ler e aplicar contexto de autenticação usando chamadas do MS Graph. Essa prática é crítica para aplicativos multilocatário. Os valores de Contexto de Autenticação variam entre os locatários do Microsoft Entra e não estarão disponíveis na edição gratuita do Microsoft Entra ID. Para obter mais informações sobre como um aplicativo deve consultar, definir e usar o contexto de autenticação em seu código, consulte o exemplo de código, Use the Conditional Access auth context to perform step-up authentication como um aplicativo deve consultar, definir e usar o contexto de autenticação em seu código.

Não use o contexto de autenticação em que o próprio aplicativo será um destino das políticas de Acesso Condicional. O recurso funciona melhor quando partes do aplicativo exigem que o usuário atenda a uma barra de autenticação mais alta.

Amostras de código

Contexto de autenticação [ACRs] no comportamento esperado de Acesso Condicional

Satisfação explícita do contexto de autenticação em solicitações

Um cliente pode pedir explicitamente um token com um contexto de autenticação (ACRS) através das declarações no corpo da solicitação. Se um ACRS foi solicitado, o Acesso Condicional permitirá a emissão do token com o ACRS solicitado se todos os desafios forem concluídos.

Comportamento esperado quando um contexto de autenticação não é protegido pelo Acesso Condicional no locatário

O Acesso Condicional pode emitir um ACRS nas declarações de um token quando toda a política de Acesso Condicional atribuída ao valor ACRS tiver sido satisfeita. Se nenhuma política de Acesso Condicional for atribuída a um valor ACRS, a declaração ainda poderá ser emitida, porque todos os requisitos de política foram atendidos.

Tabela de resumo do comportamento esperado quando o ACRS é explicitamente solicitado

ACRS solicitado Política aplicada Controle satisfeito ACRS adicionado às reivindicações
Sim No Sim Sim
Sim Sim No No
Sim Sim Sim Sim
Sim Nenhuma política configurada com o ACRS Sim Sim

Satisfação implícita do contexto auth por avaliação oportunista

Um provedor de recursos pode optar pela reivindicação opcional 'acrs'. O Acesso Condicional tenta adicionar o ACRS às declarações de token de forma oportunista, a fim de evitar viagens de ida e volta para adquirir novos tokens para o Microsoft Entra ID. Nessa avaliação, o Acesso Condicional verifica se as políticas que protegem os desafios do Contexto de Autenticação já estão satisfeitas e, em caso afirmativo, adiciona o ACRS às declarações de token.

Nota

Cada tipo de token precisará ser aceito individualmente (token de ID, token de acesso).

Se um provedor de recursos não optar pela declaração opcional 'acrs', a única maneira de obter um ACRS no token será solicitá-lo explicitamente em uma solicitação de token. Ele não obterá os benefícios da avaliação oportunista, portanto, toda vez que o ACRS necessário estiver ausente das declarações de token, o provedor de recursos desafiará o cliente a adquirir um novo token contendo ele nas declarações.

Comportamento esperado com contexto de autenticação e controles de sessão para avaliação oportunista implícita do ACRS

Frequência de início de sessão por intervalo

O Acesso Condicional considera a "frequência de início de sessão por intervalo" como satisfeita para uma avaliação ACRS oportunista quando todos os fatores de autenticação presentes estão dentro do intervalo de frequência de início de sessão. Caso o primeiro fator auth instant esteja obsoleto, ou se o segundo fator (MFA) estiver presente e seu auth instant estiver obsoleto, a frequência de login por intervalo não será satisfeita e o ACRS não será emitido no token oportunisticamente.

Segurança de aplicativos na nuvem (CAS)

O Acesso Condicional considerará o controle de sessão CAS como satisfeito para avaliação oportunista do ACRS, quando uma sessão CAS foi estabelecida durante essa solicitação. Por exemplo, quando uma solicitação chega e qualquer política de Acesso Condicional é aplicada e imposta uma sessão CAS, e além disso há uma política de Acesso Condicional que também requer uma sessão CAS, uma vez que a sessão CAS será imposta, que satisfará o controle de sessão CAS para a avaliação oportunista.

Comportamento esperado quando um locatário contém políticas de Acesso Condicional protegendo o contexto de autenticação

A tabela abaixo mostrará todos os casos de canto em que o ACRS é adicionado às reivindicações do token por avaliação oportunista.

Política A: Exigir MFA de todos os usuários, excluindo o usuário "Ariel", ao solicitar acrs "c1". Política B: Bloqueie todos os usuários, excluindo o usuário "Jay", ao pedir acrs "c2" ou "c3".

Fluxo ACRS solicitado Política aplicada Controle satisfeito ACRS adicionado às reivindicações
Ariel solicita um token de acesso "C1" Nenhuma Sim para "c1". Não para "c2" e "c3" "c1" (solicitado)
Ariel solicita um token de acesso "C2" Política B Bloqueado pela política B Nenhuma
Ariel solicita um token de acesso Nenhuma Nenhuma Sim para "c1". Não para "c2" e "c3" "c1" (adicionado oportunisticamente da política A)
Jay solicita um token de acesso (sem MFA) "C1" Política A Não Nenhuma
Jay solicita um token de acesso (com MFA) "C1" Política A Sim "c1" (solicitado), "c2" (adicionado oportunisticamente da política B), "c3" (adicionado oportunisticamente da política B)
Jay solicita um token de acesso (sem MFA) "C2" Nenhuma Sim para "c2" e "c3". Não para "c1" "c2" (solicitado), "c3" (adicionado oportunisticamente da política B)
Jay solicita um token de acesso (com MFA) "C2" Nenhuma Sim para "c1", "c2" e "c3" "c1" (melhor esforço de A), "c2" (solicitado), "c3" (adicionado oportunisticamente da política B)
Jay solicita um token de acesso (com MFA) Nenhuma Nenhuma Sim para "c1", "c2" e "c3" "C1", "C2", "C3" todos oportunisticamente adicionados
Jay solicita um token de acesso (sem MFA) Nenhuma Nenhuma Sim para "c2" e "c3". Não para "c1" "C2", "C3" todos oportunisticamente adicionados

Próximos passos