Guia para programadores do contexto de autenticação de Conditional Access

Aplica-se a: Locatários da força de trabalho Inquilinos externos (saiba mais)

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

O contexto de autenticação de Acesso Condicional (contexto de autenticação) permite-lhe aplicar políticas granulares a dados e ações confidenciais em vez de apenas ao nível da aplicação. Pode refinar as suas políticas de Confiança Zero para acesso de privilégio mínimo, minimizando o atrito do utilizador e mantendo os utilizadores mais produtivos e os seus recursos mais seguros. Hoje, ele é usado por aplicações desenvolvidas pela sua empresa que utilizam o OpenId Connect para autenticação para proteger recursos confidenciais, como transações de alto valor ou a 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 reforçada, seletivamente, como MFA, dos seus utilizadores finais nas suas aplicações. Este recurso ajuda os desenvolvedores a criar experiências de utilizador mais suaves para a maioria das partes das suas aplicações, enquanto o acesso a operações e dados continua protegido por controlos de autenticação mais fortes.

Descrição do problema

Os administradores e reguladores de TI muitas vezes têm dificuldade em equilibrar o pedido aos utilizadores de fatores adicionais de autenticação e em alcançar segurança adequada e adesão às políticas para as aplicações. 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 sensíveis.

Então, e se os aplicativos fossem capazes de misturar ambos? Funcionando com um nível mais baixo de segurança e menos prompts para a maioria dos cenários. Depois, reforçar condicionalmente os requisitos de segurança quando se acede a dados 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, a sua aplicação deve ser integrada na plataforma de identidade da Microsoft usando os protocolos OpenID Connect/ OAuth 2.0 para autenticação e autorização. Recomendamos que utilize bibliotecas de autenticação da plataforma de identidade da Microsoft para integrar e proteger a sua aplicação com o Microsoft Entra ID. Documentação da plataforma de identidade da Microsoft é um bom lugar para começar a aprender como integrar as suas aplicações à 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 padrão da indústria OpenID Connect. Os desenvolvedores usam um valor de referência do Contexto de Autenticação de Acesso Condicionalvalor com o parâmetro pedido de afirmações para dar às aplicações uma forma de acionar e satisfazer a política.

Em segundo lugar, 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 aplicações que iniciam sessão dos utilizadores. Não há suporte para aplicativos que se autenticam como eles mesmos. Use o guia Fluxos de autenticação e cenários de aplicações para saber mais sobre os tipos e fluxos de aplicações de autenticação suportados na plataforma de identidade da Microsoft.

Etapas de integração

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

Primeiro, declare e disponibilize os contextos de autenticação no seu inquilino. 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 num inquilino. Exemplos de contexto de autenticação podem ser:

• C1 - Exigir autenticação forte
• C2 – Exigir dispositivos compatíveis
• C3 – Exigir localizações fidedignas

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

• Todos os utilizadores que fizerem login nesta aplicação web devem concluir a autenticação de dois fatores com êxito para o ID de contexto de autenticação C1.
• Todos os usuários que entrarem neste aplicativo Web devem concluir com êxito o 2FA e também acessar o aplicativo a partir de um intervalo de endereços IP definido para o ID de contexto de autenticação C3.

Segundo: Os desenvolvedores de uma aplicação que planeiem usar o contexto de autenticação de Acesso Condicional são aconselhados a primeiro fornecer aos administradores de aplicações 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 para 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 o Conditional Access Auth Context para efetuar uma autenticação reforçada como exemplo.

Estas etapas são as alterações que precisa de aplicar na sua base de código. As etapas compreendem, em termos gerais, o seguinte:

• Consulte o MS Graph para listar todos os Auth Contexts disponíveis.
• Permita que os administradores de TI selecionem operações confidenciais/com privilégios elevados 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.

Terceiro: A sua aplicação e, para este exemplo, assumimos que é uma API Web, precisa de avaliar as chamadas em relação ao mapeamento guardado e, consequentemente, emitir pedidos de reivindicação para as suas aplicações cliente. Para preparar esta ação, devem ser tomadas as seguintes medidas:

1. Numa operação sensível e protegida por um contexto de autenticação, avalie os valores no claim acrs em relação aos mapeamentos de ID do contexto de autenticação guardados anteriormente e apresente um Claims Challenge, conforme mostrado no trecho de código seguinte.

2. O diagrama a seguir mostra a interação entre o utilizador, a aplicação cliente e a API da Web.

   

   O trecho de código a seguir é do exemplo de código, Utilizar o contexto de autenticação do Acesso Condicional para realizar a autenticação step-up. 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 a sua base de dados para um mapeamento guardado para este método
   • Se essa ação realmente exigir um contexto de autenticação elevado, ela verificará a alegação acrs para um ID de contexto de autenticação existente e correspondente.
   • Se não for encontrado um ID de contexto de autenticação correspondente, é gerado um claims challenge.

   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 afirmações é descrito no artigo Desafio de Afirmações na plataforma de identidades da Microsoft.

3. Na aplicação cliente, intercepte o pedido de afirmações e redirecione o utilizador 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, Utilizar o contexto de autenticação do Acesso Condicional para realizar autenticação 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;
   }
   

   Manipule a exceção na chamada para API da Web, se um desafio de declarações for apresentado, redirecione o utilizador 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. As capacidades do cliente ajudam os provedores de recursos (RP), como a nossa API Web, a detectar se a aplicação cliente entende o desafio de reivindicações e pode personalizar a sua resposta de acordo. Esse recurso pode ser útil quando nem todos os clientes de APIs são capazes de lidar com desafios de claims e alguns mais antigos ainda esperam uma resposta diferente. Para obter mais informações, consulte a secção Recursos do cliente.

Advertências e recomendações

Não codifique de forma fixa valores de Contexto de Autenticação na sua aplicação. Os aplicativos devem ler e aplicar contexto de autenticação usando chamadas do MS Graph. Essa prática é crítica para aplicações multilocatário. Os valores de Auth Context 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 the Conditional Access auth context to perform step-up authentication.

Não use o contexto de autenticação quando o próprio aplicativo for um destino das políticas de Acesso Condicional. A funcionalidade funciona melhor quando partes da aplicação exigem que o utilizador atinja um nível mais elevado de autenticação.

Amostras de código

• Use o contexto de autenticação de Acesso Condicional para executar autenticação step-up para operações de alto privilégio numa aplicação Web
• Use o contexto de autenticação de Acesso Condicional para executar a autenticação step-up para operações de alto privilégio numa API Web
• Utilize o contexto de autenticação de Acesso Condicional para executar a autenticação step-up para operações de alto privilégio numa aplicação de página única do React e numa API Web Express

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

Satisfação explícita do contexto de autenticação nos pedidos

Um cliente pode pedir explicitamente um token com um contexto de autenticação (ACRS) através das declarações no corpo do pedido. Se um ACRS foi solicitado, o Acesso Condicional permite emitir o 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 todas as políticas de Acesso Condicional atribuídas ao valor ACRS forem satisfeitas. 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 serão atendidos.

Tabela de resumo do comportamento esperado quando os ACRS são explicitamente solicitados

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

Um provedor de recursos pode optar pela claim opcional 'acrs'. O Acesso Condicional tenta adicionar o ACRS às declarações de token de forma oportunista, a fim de evitar idas e voltas 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.

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 instantes de autenticação dos fatores de autenticação presentes se situam dentro do intervalo de frequência de início de sessão. Caso o fator de autenticação esteja obsoleto, a frequência de entrada por intervalo não será satisfeita e o ACRS não será emitido no token de forma oportunista.

Segurança de aplicativos na nuvem (CAS)

O Acesso Condicional considera o controle de sessão CAS como satisfeito para uma avaliação ACRS oportunista, 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 impõe uma sessão CAS, e além disso há uma política de Acesso Condicional que também requer uma sessão CAS, como a sessão CAS será imposta, o que satisfaz o controlo de sessão 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 especiais em que o ACRS é adicionado às afirmações do token através de uma avaliação oportunista.

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

Próximos passos

• Acesso condicional granular para dados e ações confidenciais (Blog)
• Zero Trust com a plataforma de identidade da Microsoft
• Criação de aplicativos prontos para Confiança Zero com a plataforma de identidade da Microsoft
• Contexto de autenticação de Acesso Condicional
• authenticationContextClassReference tipo de recurso - MS Graph
• Contestação de afirmações, solicitação de afirmações e capacidades do cliente na plataforma de identidade da Microsoft
• Usando o contexto de autenticação com o Proteção de Informações do Microsoft Purview e o SharePoint
• Como usar APIs habilitadas para Avaliação Contínua de Acesso nas suas aplicações