Compartilhar via

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

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica aos locatários da força de trabalho. Locatários da força de trabalho Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

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.

Instrução do problema

Os administradores e reguladores de TI frequentemente enfrentam dificuldades para equilibrar a exigência de fatores extras de autenticação para os usuários e alcançar a conformidade adequada com as políticas de segurança e para aplicativos. Pode ser uma escolha entre uma política forte que afeta a produtividade dos usuários ou uma política que não é forte o suficiente para recursos confidenciais.

Então, e se os aplicativos fossem capazes de misturar ambos? Funcionando com um nível mais baixo de segurança e menos solicitações para a maioria dos cenários. Em seguida, intensificando condicionalmente os requisitos de segurança quando dados mais confidenciais estão sendo acessados?

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

Você pode começar a integrar esse recurso em seus aplicativos depois que ele 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.

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

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

  • Todos os usuários que entrarem neste aplicativo Web devem concluir com êxito a 2FA para a ID de contexto de autenticação C1.
  • Todos os usuários que entrarem nesta aplicação web devem concluir com êxito a autenticação em dois fatores (2FA) e também acessar o aplicativo a partir de um intervalo de endereços IP definido 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. Os administradores de TI geralmente criam políticas de Acesso Condicional, pois têm uma melhor compreensão dos recursos disponíveis. 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. Consulte 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.

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: seu aplicativo e, neste exemplo, vamos supor que ele seja uma API Web, então precisa avaliar as chamadas em relação ao mapeamento salvo e, portanto, aumentar os desafios de declaração para seus 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. Os recursos do cliente ajudam os provedores de recursos (RP), como nossa API da Web, a detectar se o aplicativo cliente entende o desafio das reivindicações e pode então 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 variam entre os locatários do Microsoft Entra e não estã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 o contexto de autenticação de Acesso Condicional para executar a autenticação de etapas.

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 foi solicitado, o Acesso Condicional permite emitir o token com o ACRS solicitado se todos os desafios foram 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 serão 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 Não
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 precisa ser optado individualmente (token de ID, token de acesso).

Se um provedor de recursos não aceitar a declaração opcional 'acrs', a única maneira de obter um ACRS no token é solicitá-lo explicitamente 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 qualquer dos fatores de autenticação esteja obsoleto, a frequência de entrada por intervalo não poderá ser satisfeita e o ACRS não será emitido no token de forma oportunista.

CAS (Segurança de Aplicativo de Nuvem)

O Acesso Condicional considera 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: bloquear 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

  • Last updated on