Guia do desenvolvedor para contexto de autenticação do acesso condicional

  • Artigo

O Acesso Condicional é o painel de controle de Confiança Zero que permite direcionar políticas para acesso a todos os seus aplicativos, sejam antigos ou novos, privados ou públicos, locais ou em várias nuvens. Com o contexto de autenticação de Acesso Condicional, você pode aplicar políticas diferentes dentro desses aplicativos.

O contexto de autenticação de Acesso Condicional permite aplicar políticas granulares a ações e dados confidenciais em vez de apenas no nível do aplicativo. Você pode refinar suas políticas de Confiança Zero para acesso com privilégios mínimos, minimizando o atrito do usuário e mantendo os usuários mais produtivos e seus recursos mais seguros. Atualmente, 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 exibição de dados pessoais do funcionário.

Para disparar uma autenticação passo a passo 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 a capacidade de exigir autenticação avançada mais forte, seletivamente, como a MFA de seus usuários finais em 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 atrás de controles de autenticação mais fortes.

Problema declarado

Os administradores e regulamentadores de TI geralmente têm dificuldades para balancear a solicitação de seus usuários com fatores extra de autenticação com muita frequência e alcançar a adesão adequada à segurança e à política para aplicativos e serviços em que partes deles contêm operações e dados confidenciais. Pode ser necessário escolher entre uma política forte que afeta a produtividade dos usuários quando eles acessam a maioria dos dados e das ações ou uma política que não seja forte o suficiente para recursos confidenciais.

Portanto, o que aconteceria se os aplicativos pudessem combinar ambos, podendo funcionar com uma segurança relativamente menor e solicitações menos frequentes para a maioria dos usuários e operações e, ainda assim, impulsionar condicionalmente o requisito de segurança quando os usuários acessarem partes mais confidenciais?

Cenários comuns

Por exemplo, embora os usuários possam entrar no SharePoint usando a autenticação multifator, acessar a coleção de sites no SharePoint contendo documentos confidenciais pode exigir um dispositivo em conformidade e ser acessível somente de intervalos de IP confiáveis.

Pré-requisitos

Primeiro, seu aplicativo deve estar 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 a integrar seus aplicativos à Plataforma de Identidade da Microsoft. O suporte ao recurso Contexto de Autenticação de Acesso Condicional é criado com base nas extensões de protocolo fornecidas pelo protocolo OpenID Connect padrão do setor. Os desenvolvedores usam um valor de referência de contexto de autenticação de acesso condicional com o parâmetro de Solicitação de Declarações para fornecer aos aplicativos uma forma de disparar a política e atender a ela.

Em segundo lugar, o Acesso Condicional requer o licenciamento do Microsoft Entra ID P1. É possível encontrar mais informações sobre o licenciamento na página de preços do Microsoft Entra.

Em terceiro lugar, hoje ele está disponível somente para aplicativos que fazem login de 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 aplicativo de autenticação com suporte na Plataforma de Identidade da Microsoft.

Etapas de integração

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

Observação

Uma explicação detalhada desse recurso também está disponível como uma sessão registrada em Usar o contexto de autenticação de acesso condicional em seu aplicativo para a autenticação de step-up.

Primeiro, declare e disponibilize os contextos de autenticação em seu locatário. Para obter mais informações, confira Configurar os 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 – Exigir dispositivos em conformidade
  • C3 – Exigir locais confiáveis

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

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

Observação

Os valores de contexto de autenticação do Acesso Condicional são declarados e mantidos separadamente dos aplicativos. Não é aconselhável que os aplicativos aproveitem a dependência rígida de IDs de contexto de autenticação. As políticas de Acesso Condicional geralmente são feitas pelos administradores de TI, pois eles têm uma melhor compreensão dos recursos disponíveis para a aplicação de políticas. Por exemplo, para um locatário do Microsoft Entra, os administradores de TI saberiam quantos usuários do locatário estão equipados para usar 2FA para MFA e, portanto, poderiam 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 planejam usar o contexto de autenticação de Acesso Condicional são aconselhados a fornecer primeiro 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 aproximadamente:

  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 uma ID de contexto de autenticação disponível.
  3. Confira o exemplo de código Usar o Contexto de Autenticação de Acesso Condicional para executar a autenticação de step-up a fim de obter um exemplo de como isso é feito.

Essas etapas são as alterações que você precisa realizar em sua base de código. As etapas abrangem amplamente

  • a Consulta do MS Graph para listar todos os Contextos de Autenticação disponíveis.
  • Permita que os administradores de TI selecionem operações confidenciais/de alto privilégio e as atribuam 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: o seu aplicativo, que, para fins ilustrativos, é uma API Web, precisa comparar as chamadas com o mapeamento salvo e aumentar os desafios de declaração para os aplicativos cliente. Para se preparar para essa ação, as seguintes etapas devem ser realizadas:

  1. Em uma operação de contexto de autenticação confidencial e protegida, avalie os valores na declaração acrs em relação aos mapeamentos de ID de Contexto de Autenticação salvos anteriormente e eleve um Desafio de Declarações, conforme fornecido no snippet de código a seguir.

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

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

    O snippet de código a seguir é do exemplo de código Usar o contexto de autenticação de Acesso Condicional para executar a autenticação de step-up. O primeiro método, CheckForRequiredAuthContext() na API

    • Verifica se a ação do aplicativo que está sendo chamada requer autenticação de 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 declaração acrs para uma ID de Contexto de Autenticação existente e correspondente.
    • Se uma ID de Contexto de Autenticação correspondente não for encontrada, ela gerará um desafio de declarações.
    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");
            }
        }
    }
}

    Observação

    O formato do desafio de declarações é descrito no artigo Desafio de declarações na Plataforma de Identidade da Microsoft.

  3. No aplicativo cliente, intercepte o desafio de declarações e redirecione o usuário de volta para o Microsoft Entra ID para uma avaliação mais detalhada da política. O snippet de código a seguir é do exemplo de código Usar o contexto de autenticação de Acesso Condicional para executar a autenticação de step-up.

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

    Trate a exceção na chamada à API Web e, se um desafio de declarações for apresentado, ele redirecionará 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 funcionalidade do cliente. As funcionalidades do cliente ajudam os RP (provedores de recursos), como nossa API Web acima, a detectar se o aplicativo cliente de chamada entende o desafio de declarações, que então pode personalizar sua resposta adequadamente. Essa funcionalidade pode ser útil quando nem todos os clientes de APIs conseguem lidar com desafios de declaração e alguns mais antigos ainda esperam uma resposta diferente. Para obter mais informações, confira a seção Funcionalidades do cliente.

Advertências e recomendações

Não codifique os valores de Contexto de Autenticação em seu aplicativo. Os aplicativos devem ler e aplicar o contexto de autenticação usando chamadas do MS Graph. Essa prática é essencial para aplicativos multi-locatário. Os valores de Contexto de Autenticação variará entre Microsoft Entra locatários e não estará 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, confira o exemplo de código Usar o contexto de autenticação de Acesso Condicional para executar a autenticação de step-up.

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

Exemplos de código

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

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

Um cliente pode solicitar explicitamente um token com um Contexto de Autenticação (ACRS) por meio das declarações no corpo da solicitação. Se um ACRS tiver sido 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 do ACRS for atendida. Se nenhuma política de Acesso Condicional for atribuída a um valor do ACRS, a declaração ainda poderá ser emitida, pois todos os requisitos de política foram atendidos.

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

ACRS solicitado Política aplicada Controle atendido ACRS adicionado às declarações
Sim Não Sim Sim
Sim Sim Não No
Sim Sim Sim Sim
Sim Nenhuma política configurada com o ACRS Sim Sim

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

Um provedor de recursos pode optar pela declaração "acrs" opcional. 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 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 adiciona o ACRS às declarações de token, se for o caso.

Observação

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

Se um provedor de recursos não aceitar a declaração "acrs" opcional, a única maneira de obter um ACRS no token será por meio de solicitação explicita por ele em uma solicitação de token. Ele não obterá os benefícios da avaliação oportunista, portanto, sempre que o ACRS necessário estiver ausente das declarações de token, o provedor de recursos desafiará o cliente a adquirir um novo token que esteja 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 entrada por intervalo

O Acesso Condicional considerará a "frequência de entrada por intervalo" como atendida para a avaliação de ACRS oportunista quando todos os fatores de autenticação atuais de autenticação instantânea estiverem dentro do intervalo de frequência de entrada. Caso o primeiro fator de autenticação instantânea esteja obsoleto ou se o segundo fator (MFA) estiver presente e sua autenticação instantânea estiver obsoleta, a frequência de entrada por intervalo não será atendida e o ACRS não será emitido no token de forma oportunista.

CAS (Segurança de Aplicativo de Nuvem)

O Acesso Condicional considerará o controle de sessão da CAS como atendido para avaliação de ACRS oportunista, quando uma sessão da CAS for estabelecida durante aquela solicitação. Por exemplo, quando uma solicitação entrar e qualquer política de Acesso Condicional é aplicada e impõe uma sessão CAS. Além disso, há uma política de Acesso Condicional que também requer uma sessão CAS, pois a sessão CAS será imposta e isso atenderá ao controle de sessão da CAS para a avaliação oportunista.

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

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

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

Flow ACRS solicitado Política aplicada Controle atendido ACRS adicionado às declarações
Ariel solicita um token de acesso "c1" Nenhum 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 Nenhum
Ariel solicita um token de acesso Nenhum Nenhum Sim para "c1". Não para "c2" e "c3" "c1" (adicionado oportunistamente a partir da política A)
Jay solicita um token de acesso (sem MFA) "c1" Política A Não Nenhum
Jay solicita um token de acesso (com MFA) "c1" Política A Sim "c1" (solicitado), "c2" (adicionado oportunistamente a partir da política B), "c3" (adicionado oportunistamente a partir da política B)
Jay solicita um token de acesso (sem MFA) "c2" Nenhum Sim para "c2" e "c3". Não para "c1" "c2" (solicitado), "c3" (adicionado oportunistamente a partir da política B)
Jay solicita um token de acesso (com MFA) "c2" Nenhum Sim para "c1", "c2" e "c3" "c1" (melhor esforço de A), "c2" (solicitado), "c3" (adicionado oportunistamente a partir da política B)
Jay solicita um token de acesso (com MFA) Nenhum Nenhum Sim para "c1", "c2" e "c3" "c1", "c2", "c3" todos adicionados oportunistamente
Jay solicita um token de acesso (sem MFA) Nenhum Nenhum Sim para "c2" e "c3". Não para "c1" "c2", "c3" todos adicionados oportunistamente

Próximas etapas