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

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

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 para equilibrar entre incitar os utilizadores com fatores extra de autenticação e alcançar segurança e conformidade com políticas adequadas para 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, 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

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

Para usar os Contextos de Autenticação de Acesso Condicional, crie ou modifique suas políticas de Acesso Condicional. Exemplos de políticas 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 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 o Conditional Access Auth Context para efetuar uma autenticação reforçada como exemplo.

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.

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.

   

   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. 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 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 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 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

• Use o contexto de autenticação de Acesso Condicional para executar autenticação de etapa para operações de alto privilégio em um aplicativo Web
• Use o contexto de autenticação de Acesso Condicional para executar a autenticação de etapa para operações de alto privilégio em uma API da Web
• Use o contexto de autenticação de Acesso Condicional para executar a autenticação de etapa para operações de alto privilégio em um aplicativo de página única do React e em uma API da Web Express

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 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 o ACRS é explicitamente solicitado

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.

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 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 protegendo 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 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".

Próximos passos

• Acesso condicional granular para dados e ações confidenciais (Blog)
• Confiança zero com a plataforma de identidade da Microsoft
• Criação de aplicativos prontos para Zero Trust com a plataforma de identidade da Microsoft
• Contexto de autenticação de Acesso Condicional
• authenticationContextClassReference tipo de recurso - MS Graph
• Contestação de declarações, solicitação de declarações e recursos de cliente na plataforma de identidade da Microsoft
• Usando o contexto de autenticação com o Microsoft Purview Information Protection e o SharePoint
• Como usar APIs habilitadas para Avaliação Contínua de Acesso em seus aplicativos