Visão geral da política personalizada do Azure AD B2C

As políticas personalizadas são arquivos de configuração que definem o comportamento do locatário do Azure AD B2C (Azure Active Directory B2C). Embora os fluxos de usuário sejam predefinidos no portal do Azure AD B2C para as tarefas de identidade mais comuns, um desenvolvedor de identidade pode editar políticas personalizadas para concluir muitas tarefas diferentes.

Uma política personalizada é totalmente configurável e orientada por políticas. Uma política personalizada orquestra a confiança entre entidades em protocolos padrão. Por exemplo, OpenID Connect, OAuth, SAML e alguns não padronizados, como trocas de declarações entre sistemas baseadas em API REST. A estrutura cria experiências de fácil uso e com rotulagem branca.

Uma política personalizada é representada como um ou mais arquivos formatados por XML, que se referem uns aos outros em uma cadeia hierárquica. Os elementos XML definem os blocos de construção, a interação com o usuário e outras partes e a lógica de negócios.

Pacote de inicialização de política personalizado

O pacote inicial de política personalizada do Azure AD B2C vem com várias políticas predefinidas para que você comece rapidamente. Cada um desses pacotes de início contém o menor número de perfis técnicos e percursos do usuário necessários para alcançar os cenários descritos:

• LocalAccounts – Habilita apenas o uso de contas locais.
• SocialAccounts – Habilita apenas o uso de contas sociais (ou federadas).
• SocialAndLocalAccounts – Habilita o uso de contas locais e sociais. A maioria dos nossos exemplos refere-se a essa política.
• SocialAndLocalAccountsWithMFA – Habilita opções de autenticação social, local e multifator.

No repositório gitHub de exemplos do Azure AD B2C, você encontra exemplos para vários cenários e percursos de usuário personalizados do CIAM do Azure AD B2C aprimorados. Por exemplo, aprimoramentos de política de conta local, aprimoramentos de política de conta social, aprimoramentos de MFA, aprimoramentos de interface do usuário, aprimoramentos genéricos, migração de aplicativo, migração do usuário, acesso condicional, teste web e CI/CD.

Noções básicas

Declarações

Uma declaração fornece armazenamento temporário de dados durante uma execução de política do Azure AD B2C. As declarações são mais como variáveis em uma linguagem de programação. Ele pode armazenar informações sobre o usuário, como nome, nome da família ou qualquer outra declaração obtida do usuário ou de outros sistemas (trocas de declarações). O esquema de declarações é o local onde você declara suas declarações.

Quando a política é executada, o Azure AD B2C envia e recebe declarações de e para partes internas e externas e envia um subconjunto dessas declarações para seu aplicativo de terceira parte confiável como parte do token. As declarações são usadas das seguintes maneiras:

• Uma declaração é salva, lida ou atualizada no objeto de usuário do diretório.
• Uma declaração é recebida de um provedor de identidade externo.
• As declarações são enviadas ou recebidas usando um serviço de API REST personalizado.
• Os dados são coletados como declarações do usuário durante os fluxos de perfil de inscrição ou edição.

Manipulando suas declarações

As transformações de declarações são funções predefinidas que podem ser usadas para converter uma determinada declaração em outra, avaliar uma declaração ou definir um valor de declaração. Por exemplo, adicionar um item a uma coleção de cadeias de caracteres, alterar o caso de uma cadeia de caracteres ou avaliar uma declaração de data e hora. Uma transformação de declarações especifica um método de transformação, que também é predefinido.

Personalizar e regionalizar sua interface de usuário

Para coletar informações de seus usuários apresentando uma página no navegador da Web, use o perfil técnico autodeclarado. Você pode editar seu perfil técnico autodeclarado para adicionar declarações e personalizar a entrada do usuário.

Para personalizar a interface do usuário para seu perfil técnico autodeclarado, especifique uma URL no elemento de definição de conteúdo com conteúdo HTML personalizado. No perfil técnico autodeclarado, você indica este ID de definição de conteúdo.

Para personalizar cadeias de caracteres específicas do idioma, use o elemento de localização . Uma definição de conteúdo pode conter uma referência de localização que especifica uma lista de recursos localizados a serem carregados. O Azure AD B2C mescla elementos de interface do usuário com o conteúdo HTML carregado da URL e, em seguida, exibe a página para o usuário.

Visão geral da política de terceira parte confiável

Um aplicativo de terceira parte confiável, que no protocolo SAML é conhecido como um provedor de serviços, chama a política de terceira parte confiável para executar um percurso de usuário específico. A política de terceira parte confiável especifica o percurso do usuário a ser executado e a lista de declarações que o token inclui.

Todos os aplicativos de terceira parte confiável que usam a mesma política recebem as mesmas declarações de token e o usuário passa pelo mesmo percurso do usuário.

Percursos do usuário

Os percursos do usuário permitem que você defina a lógica de negócios com o caminho pelo qual o usuário segue para obter acesso ao seu aplicativo. O usuário é levado ao percurso do usuário para recuperar as declarações que serão apresentadas ao seu aplicativo. Um percurso do usuário é criado a partir de uma sequência de etapas de orquestração. Um usuário deve chegar à última etapa para adquirir um token.

As instruções a seguir descrevem como adicionar etapas de orquestração à política do pacote de início de conta social e local. Aqui está um exemplo de uma chamada à API REST que foi adicionada.

Etapas de orquestração

A etapa de orquestração faz referência a um método que implementa sua finalidade ou funcionalidade pretendida. Esse método é chamado de perfil técnico. Quando o percurso do usuário precisa se ramificar para representar melhor a lógica de negócios, a etapa de orquestração faz referência ao sub-percurso. Um subpercurso contém seu próprio conjunto de etapas de orquestração.

Um usuário deve alcançar a última etapa de orquestração no percurso do usuário para adquirir um token. Mas os usuários podem não precisar percorrer todas as etapas de orquestração. As etapas de orquestração podem ser executadas condicionalmente com base em pré-condições definidas na etapa de orquestração.

Após a conclusão de uma etapa de orquestração, o Azure AD B2C armazenará as declarações de saída na bolsa de declarações. As declarações no recipiente de declarações podem ser utilizadas por outras etapas de orquestração no percurso do usuário.

O diagrama a seguir mostra como as etapas de orquestração do percurso do usuário podem acessar o repositório de reivindicações.

Perfil técnico

Um perfil técnico fornece uma interface para se comunicar com diferentes tipos de partes. Um percurso do usuário combina a chamada de perfis técnicos por meio de etapas de orquestração para definir sua lógica de negócios.

Todos os tipos de perfis técnicos compartilham o mesmo conceito. Você envia declarações de entrada, executa a transformação de declarações e se comunica com a parte configurada. Depois que o processo for concluído, o perfil técnico retornará as declarações de saída para o recipiente de declarações. Para obter mais informações, consulte a visão geral dos perfis técnicos.

Perfil técnico de validação

Quando um usuário interage com a interface do usuário, convém validar os dados coletados. Para interagir com o usuário, um perfil técnico autodeclarado deve ser usado.

Para validar a entrada do usuário, um perfil técnico de validação é chamado do perfil técnico autodeclarado. Um perfil técnico de validação é um método para chamar qualquer perfil técnico não interativo. Nesse caso, o perfil técnico pode retornar declarações de saída ou uma mensagem de erro. A mensagem de erro é renderizada para o usuário na tela, permitindo que o usuário tente novamente.

O diagrama a seguir ilustra como o Azure AD B2C usa um perfil técnico de validação para validar as credenciais do usuário.

Modelo de herança

Cada pacote inicial inclui os seguintes arquivos:

• Um arquivo base que contém a maioria das definições. Para ajudar na solução de problemas e na manutenção de longo prazo de suas políticas, tente minimizar o número de alterações feitas nesse arquivo.
• Um arquivo de localização que contém as cadeias de caracteres de localização. Esse arquivo de política é derivado do arquivo base. Use esse arquivo para acomodar idiomas diferentes para atender às suas necessidades do cliente.
• Um arquivo extensões que contém as alterações de configuração exclusivas para seu locatário. Esse arquivo de política é derivado do arquivo de localização. Use esse arquivo para adicionar novas funcionalidades ou substituir a funcionalidade existente. Por exemplo, use esse arquivo para federar com novos provedores de identidade.
• Um arquivo de Terceira Parte Confiável (RP) que é o único arquivo voltado para tarefas que é invocado diretamente pelo aplicativo de terceira parte confiável, como seus aplicativos Web, móveis ou de área de trabalho. Cada tarefa exclusiva, como inscrição, entrada ou edição de perfil, exige o próprio arquivo de política de terceira parte confiável. Esse arquivo de política é derivado do arquivo de extensões.

O modelo de herança é o seguinte:

• A política filho em qualquer nível pode herdar de política pai e estendê-la adicionando novos elementos.
• Para cenários mais complexos, você pode adicionar mais níveis de herança (até 10 no total).
• Você pode adicionar mais políticas de terceira parte confiável. Por exemplo, excluir minha conta, alterar um número de telefone, política de terceira parte confiável SAML e muito mais.

O diagrama a seguir mostra a relação entre os arquivos de política e os aplicativos de terceira parte confiável.

Diretrizes e melhores práticas

Práticas recomendadas

Em uma política personalizada do Azure AD B2C, você pode integrar sua própria lógica de negócios para criar as experiências de usuário necessárias e estender a funcionalidade do serviço. Temos um conjunto de práticas recomendadas e recomendações para começar.

• Crie sua lógica na política de extensão ou na política de terceira parte confiável. Você pode adicionar novos elementos, que substituem a política base fazendo referência à mesma ID. Essa abordagem permite que você escale seu projeto, tornando mais fácil atualizar a política base posteriormente, caso a Microsoft lance novos pacotes iniciais.
• Dentro da política base, é altamente recomendável evitar fazer alterações. Quando necessário, faça comentários sobre as alterações feitas.
• Ao substituir um elemento, como metadados de perfil técnico, evite copiar o perfil técnico inteiro da política de base. Em vez disso, copie apenas a seção necessária do elemento. Consulte Desabilitar a verificação de email para obter um exemplo de como fazer a alteração.
• Para reduzir a duplicação de perfis técnicos, em que a funcionalidade principal é compartilhada, use a inclusão de perfil técnico.
• Evite gravação no diretório do Microsoft Entra durante a entrada, o que pode causar problemas de limitação.
• Se sua política tiver dependências externas, como APIs REST, verifique se elas estão altamente disponíveis.
• Para uma melhor experiência do usuário, verifique se seus modelos HTML personalizados são implantados globalmente usando a entrega de conteúdo online. A CDN (Rede de Distribuição de Conteúdo) do Azure permite reduzir os tempos de carga, salvar a largura de banda e melhorar a velocidade da resposta.
• Se você quiser fazer uma alteração no percurso do usuário, copie todo o percurso do usuário da política base para a política de extensão. Forneça uma ID exclusiva para o percurso do usuário que você copiou. Depois, na política de terceira parte confiável, altere o elemento do percurso do usuário padrão para apontar para o novo percurso do usuário.

Resolução de problemas

Ao desenvolver com políticas do Azure AD B2C, você pode encontrar erros ou exceções durante a execução do percurso do usuário. Pode ser investigado usando o Application Insights.

• Integre o Application Insights ao Azure AD B2C para diagnosticar exceções.
• A extensão do Azure AD B2C para Visual Studio Code pode ajudá-lo a acessar e visualizar os logs com base em um nome de política e hora.
• O erro mais comum na configuração de políticas personalizadas é XML formatado incorretamente. Use a validação de esquema XML para identificar erros antes de carregar seu arquivo XML.

Integração contínua

Usando um pipeline de CI/CD (integração e entrega contínua) que você configurou no Azure Pipelines, você pode incluir suas políticas personalizadas do Azure AD B2C na automação de distribuição de software e controle de código. À medida que você implanta em diferentes ambientes do Azure AD B2C, por exemplo, desenvolvimento, teste e produção, recomendamos remover processos manuais e executar testes automatizados usando o Azure Pipelines.

Prepare o seu ambiente

Você começa a usar a política personalizada do Azure AD B2C:

1. Criar um tenant do Azure AD B2C
2. Registre um aplicativo Web usando o portal do Azure para que você possa testar sua política.
3. Adicione as chaves de política necessárias e registre os aplicativos do Identity Experience Framework.
4. Obtenha o pacote inicial de política do Azure AD B2C e envie para o seu locatário de nuvem.
5. Depois de carregar o pacote inicial, teste sua política de inscrição ou entrada.
6. Recomendamos que você baixe e instale o VS Code (Visual Studio Code ). O Visual Studio Code é um editor de código-fonte leve, mas poderoso, que é executado em sua área de trabalho e está disponível para Windows, macOS e Linux. Com o VS Code, você pode navegar rapidamente e editar seus arquivos XML de política personalizada do Azure AD B2C instalando a extensão do Azure AD B2C para VS Code

Conteúdo relacionado

Depois de configurar e testar sua política do Azure AD B2C, você poderá começar a personalizar sua política. Confira os seguintes artigos para saber como:

• Adicione declarações e personalize a entrada do usuário usando políticas personalizadas. Saiba como definir uma declaração e adicionar uma declaração à interface do usuário personalizando alguns dos perfis técnicos do pacote inicial.
• Personalize a interface do usuário do aplicativo usando uma política personalizada. Saiba como criar seu próprio conteúdo HTML e personalizar a definição de conteúdo.
• Localize a interface do usuário do aplicativo usando uma política personalizada. Saiba como configurar a lista de idiomas com suporte e fornecer rótulos específicos ao idioma, adicionando o elemento de recursos localizados.
• Durante o desenvolvimento e teste de política, você pode desabilitar a verificação de email. Saiba como sobrescrever metadados de um perfil técnico.
• Configure o login com uma conta do Google usando políticas personalizadas. Saiba como criar um novo provedor de declarações com o perfil técnico OAuth2. Em seguida, personalize o percurso do usuário para incluir a opção de entrada do Google.
• Para diagnosticar problemas com suas políticas personalizadas, você pode coletar logs do Azure Active Directory B2C com o Application Insights. Saiba como adicionar novos perfis técnicos e configurar sua política de parte confiável.
• Se você quiser entender como a política personalizada é criada do zero, saiba como criar e executar suas próprias políticas personalizadas na série de guias de instruções do Azure Active Directory B2C.