Visão geral da política personalizada AZURE AD B2CAzure AD B2C custom policy overview

As políticas personalizadas são ficheiros de configuração que definem o comportamento do inquilino do Azure Active Directory B2C (AAD B2C).Custom policies are configuration files that define the behavior of your Azure Active Directory B2C (Azure AD B2C) tenant. Embora os fluxos de utilizador estejam predefinidos no portal Azure AD B2C para as tarefas de identidade mais comuns, as políticas personalizadas podem ser totalmente editadas por um desenvolvedor de identidade para completar muitas tarefas diferentes.While user flows are predefined in the Azure AD B2C portal for the most common identity tasks, custom policies can be fully edited by an identity developer to complete many different tasks.

Uma política personalizada é totalmente configurável e orientada pela política.A custom policy is fully configurable and policy-driven. Uma política personalizada orquestra a confiança entre entidades em protocolos padrão.A custom policy orchestrates trust between entities in standard protocols. Por exemplo, OpenID Connect, OAuth, SAML e alguns não padrão, por exemplo, permutas de sistema-sistema baseadas em API.For example, OpenID Connect, OAuth, SAML, and a few non-standard ones, for example REST API-based system-to-system claims exchanges. A estrutura cria experiências fáceis de utilizar e etiquetas brancas.The framework creates user-friendly, white-labeled experiences.

Uma política personalizada é representada como um ou mais ficheiros com formato XML, que se referem uns aos outros numa cadeia hierárquica.A custom policy is represented as one or more XML-formatted files, which refer to each other in a hierarchical chain. Os elementos XML definem os blocos de construção, a interação com o utilizador, e outras partes, e a lógica de negócio.The XML elements define the building blocks, the interaction with the user, and other parties, and the business logic.

Pacote de arranque de política personalizadaCustom policy starter pack

O pacote de arranque de política personalizada Azure AD B2C vem com várias políticas pré-construídas para que você vá rapidamente.Azure AD B2C custom policy starter pack comes with several pre-built policies to get you going quickly. Cada um destes pacotes de arranque contém o menor número de perfis técnicos e viagens de utilizador necessárias para alcançar os cenários descritos:Each of these starter packs contains the smallest number of technical profiles and user journeys needed to achieve the scenarios described:

  • LocalAccounts - Permite a utilização apenas de contas locais.LocalAccounts - Enables the use of local accounts only.
  • SocialAccounts - Permite a utilização apenas de contas sociais (ou federadas).SocialAccounts - Enables the use of social (or federated) accounts only.
  • SocialAndLocalAccounts - Permite o uso de contas locais e sociais.SocialAndLocalAccounts - Enables the use of both local and social accounts. A maioria das nossas amostras referem-se a esta política.Most of our samples refer to this policy.
  • SocialAndLocalAccountsWithMFA - Permite opções de autenticação social, local e multi-fatores.SocialAndLocalAccountsWithMFA - Enables social, local, and multi-factor authentication options.

Compreender o básicoUnderstanding the basics

AfirmaçõesClaims

Uma reclamação fornece armazenamento temporário de dados durante uma execução política Azure AD B2C.A claim provides temporary storage of data during an Azure AD B2C policy execution. Pode armazenar informações sobre o utilizador, como o nome próprio, apelido ou qualquer outra reclamação obtida do utilizador ou de outros sistemas (trocas de reclamações).It can store information about the user, such as first name, last name, or any other claim obtained from the user or other systems (claims exchanges). O esquema de reclamações é o lugar onde declara as suas reivindicações.The claims schema is the place where you declare your claims.

Quando a apólice é executada, a Azure AD B2C envia e recebe reclamações de e de partidos internos e externos e, em seguida, envia um subconjunto destas reivindicações para a sua aplicação do partido dependente como parte do token.When the policy runs, Azure AD B2C sends and receives claims to and from internal and external parties and then sends a subset of these claims to your relying party application as part of the token. As reclamações são utilizadas desta forma:Claims are used in these ways:

  • Uma reclamação é guardada, lida ou atualizada contra o objeto do utilizador do diretório.A claim is saved, read, or updated against the directory user object.
  • Uma reclamação é recebida de um fornecedor de identidade externo.A claim is received from an external identity provider.
  • As reclamações são enviadas ou recebidas através de um serviço de API REST personalizado.Claims are sent or received using a custom REST API service.
  • Os dados são recolhidos como reclamações do utilizador durante os fluxos de perfis de inscrição ou de edição.Data is collected as claims from the user during the sign-up or edit profile flows.

Manipular as suas reivindicaçõesManipulating your claims

As transformações de sinistros são funções predefinidas que podem ser usadas para converter uma determinada reivindicação em outra, avaliar uma reclamação ou definir um valor de reclamação.The claims transformations are predefined functions that can be used to convert a given claim into another one, evaluate a claim, or set a claim value. Por exemplo, adicionar um item a uma coleção de cordas, alterar o caso de uma cadeia, ou avaliar uma data e uma reclamação de hora.For example adding an item to a string collection, changing the case of a string, or evaluate a date and time claim. Uma transformação de sinistros especifica um método de transformação.A claims transformation specifies a transform method.

Personalize e localize o seu UICustomize and localize your UI

Quando pretender recolher informações dos seus utilizadores apresentando uma página no seu navegador, utilize o perfil técnico autoafirmado.When you'd like to collect information from your users by presenting a page in their web browser, use the self-asserted technical profile. Pode editar o seu perfil técnico autoafirmado para adicionar reclamações e personalizar a entrada do utilizador.You can edit your self-asserted technical profile to add claims and customize user input.

Para personalizar a interface do utilizador para o seu perfil técnico autoafirmado, especifica um URL no elemento de definição de conteúdo com conteúdo HTML personalizado.To customize the user interface for your self-asserted technical profile, you specify a URL in the content definition element with customized HTML content. No perfil técnico autoafirmado, aponta-se para este ID de definição de conteúdo.In the self-asserted technical profile, you point to this content definition ID.

Para personalizar cordas específicas da linguagem, utilize o elemento de localização.To customize language-specific strings, use the localization element. Uma definição de conteúdo pode conter uma referência de localização que especifica uma lista de recursos localizados para carregar.A content definition may contain a localization reference that specifies a list of localized resources to load. O Azure AD B2C funde elementos de interface de utilizador com o conteúdo HTML que é carregado a partir do seu URL e, em seguida, exibe a página para o utilizador.Azure AD B2C merges user interface elements with the HTML content that's loaded from your URL and then displays the page to the user.

Visão geral da política partidária de confiarRelying party policy overview

Uma aplicação de partidos dependentes, que no protocolo SAML é conhecido como prestador de serviços, chama a política do partido dependente para executar uma viagem específica do utilizador.A relying party application, which in the SAML protocol is known as a service provider, calls the relying party policy to execute a specific user journey. A política do partido em gestão especifica a jornada do utilizador a executar, e a lista de reclamações que o símbolo inclui.The relying party policy specifies the user journey to be executed, and list of claims that the token includes.

Diagrama mostrando o fluxo de execução da política

Todas as aplicações de partes que usam a mesma política receberão as mesmas reclamações simbólicas, e o utilizador passa pela mesma viagem de utilizador.All relying party applications that use the same policy will receive the same token claims, and the user goes through the same user journey.

Viagens de utilizadorUser journeys

As viagens de utilizador permitem definir a lógica de negócio com o caminho pelo qual o utilizador seguirá para ter acesso à sua aplicação.User journeys allows you to define the business logic with path through which user will follow to gain access to your application. O utilizador é levado através da viagem do utilizador para recuperar as reclamações que devem ser apresentadas à sua aplicação.The user is taken through the user journey to retrieve the claims that are to be presented to your application. Uma viagem de utilizador é construída a partir de uma sequência de passos de orquestração.A user journey is built from a sequence of orchestration steps. Um utilizador deve chegar ao último passo para adquirir um token.A user must reach the last step to acquire a token.

As seguintes instruções descrevem como pode adicionar passos de orquestração à política de pacote de arranque de conta social e local.The following instructions describe how you can add orchestration steps to the social and local account starter pack policy. Aqui está um exemplo de uma chamada de API REST que foi adicionada.Here's an example of a REST API call that has been added.

viagem personalizada do utilizador

Etapas de orquestraçãoOrchestration steps

O passo de orquestração refere-se a um método que implementa o seu propósito ou funcionalidade pretendido.The orchestration step references to a method that implements its intended purpose or functionality. Este método chama-se perfil técnico.This method is called a technical profile. Quando a sua viagem de utilizador precisa de se ramificar para melhor representar a lógica do negócio, o passo de orquestração refere-se à sub-viagem.When your user journey needs branching to better represent the business logic, the orchestration step references to sub journey. Uma sub-jornada contém o seu próprio conjunto de passos de orquestração.A sub journey contains its own set of orchestration steps.

Um utilizador deve alcançar o último passo de orquestração na jornada do utilizador para adquirir um token.A user must reach the last orchestration step in the user journey to acquire a token. Mas os utilizadores podem não precisar de viajar por todos os passos de orquestração.But users may not need to travel through all of the orchestration steps. Os passos de orquestração podem ser executados condicionalmente com base em condições prévias definidas no passo de orquestração.Orchestration steps can be conditionally executed based on preconditions defined in the orchestration step.

Após a conclusão de um passo de orquestração, o Azure AD B2C armazena as reclamações outputted no saco de reclamações.After an orchestration step completes, Azure AD B2C stores the outputted claims in the claims bag. As reclamações no saco de reclamações podem ser utilizadas por quaisquer outras etapas de orquestração na viagem do utilizador.The claims in the claims bag can be utilized by any further orchestration steps in the user journey.

O diagrama que se segue mostra como os passos de orquestração da viagem do utilizador podem aceder ao saco de reclamações.The following diagram shows how the user journey's orchestration steps can access the claims bag.

Viagem de utilizador Azure AD B2C

Perfil técnicoTechnical profile

Um perfil técnico fornece uma interface para comunicar com diferentes tipos de partes.A technical profile provides an interface to communicate with different types of parties. Uma viagem de utilizador combina chamar perfis técnicos através de passos de orquestração para definir a sua lógica de negócio.A user journey combines calling technical profiles via orchestration steps to define your business logic.

Todos os tipos de perfis técnicos partilham o mesmo conceito.All types of technical profiles share the same concept. Envias pedidos de entrada, geres a transformação de reclamações e comunicas com a parte configurada.You send input claims, run claims transformation, and communicate with the configured party. Após o processo estar concluído, o perfil técnico devolve os pedidos de saída ao saco de reclamações.After the process is completed, the technical profile returns the output claims to claims bag. Para mais informações, consulte a visão geral dos perfis técnicos.For more information, see technical profiles overview.

Perfil técnico de validaçãoValidation technical profile

Quando um utilizador interage com a interface do utilizador, pode querer validar os dados recolhidos.When a user interacts with the user interface, you may want to validate the data that is collected. Para interagir com o utilizador, deve ser utilizado um perfil técnico autoafirmado.To interact with the user, a self-asserted technical profile must be used.

Para validar a entrada do utilizador, é chamado um perfil técnico de validação do perfil técnico autoafirmado.To validate the user input, a validation technical profile is called from the self-asserted technical profile. Um perfil técnico de validação é um método para chamar qualquer perfil técnico não interativo.A validation technical profile is a method to call any non-interactive technical profile. Neste caso, o perfil técnico pode devolver reclamações de saída ou uma mensagem de erro.In this case, the technical profile can return output claims, or an error message. A mensagem de erro é entregue ao utilizador no ecrã, permitindo que o utilizador redoça.The error message is rendered to the user on screen, allowing the user to retry.

O diagrama que se segue ilustra como o Azure AD B2C utiliza um perfil técnico de validação para validar as credenciais do utilizador.The following diagram illustrates how Azure AD B2C uses a validation technical profile to validate the user credentials.

Diagrama de perfil técnico de validação

Modelo de herançaInheritance model

Cada pacote de arranque inclui os seguintes ficheiros:Each starter pack includes the following files:

  • Um ficheiro Base que contém a maioria das definições.A Base file that contains most of the definitions. Para ajudar na resolução de problemas e na manutenção a longo prazo das suas políticas, tente minimizar o número de alterações que faz a este ficheiro.To help with troubleshooting and long-term maintenance of your policies, try to minimize the number of changes you make to this file.
  • Um ficheiro Extensões que contém as alterações de configuração únicas para o seu inquilino.An Extensions file that holds the unique configuration changes for your tenant. Este ficheiro de política é derivado do ficheiro Base.This policy file is derived from the Base file. Utilize este ficheiro para adicionar uma nova funcionalidade ou sobrepor-se à funcionalidade existente.Use this file to add new functionality or override existing functionality. Por exemplo, utilize este ficheiro para federar com novos fornecedores de identidade.For example, use this file to federate with new identity providers.
  • Um ficheiro Relying Party (RP) que é o único ficheiro focado em tarefas que é invocado diretamente pela aplicação do partido, como as aplicações web, mobile ou desktop.A Relying Party (RP) file that is the single task-focused file that is invoked directly by the relying party application, such as your web, mobile, or desktop applications. Cada tarefa única, como inscrição, inscrição, reset de password ou edição de perfil, requer o seu próprio ficheiro de política do partido.Each unique task, such as sign-up, sign-in, password reset, or profile edit, requires its own relying party policy file. Este ficheiro de política é derivado do ficheiro de extensões.This policy file is derived from the extensions file.

O modelo de herança é o seguinte:The inheritance model is as follows:

  • A política infantil a qualquer nível pode herdar da política dos pais e alargá-la adicionando novos elementos.The child policy at any level can inherit from the parent policy and extend it by adding new elements.
  • Para cenários mais complexos, pode adicionar mais níveis de herança (até 10 no total).For more complex scenarios, you can add more inheritance levels (up to 10 in total).
  • Pode adicionar mais políticas partidárias de dependência.You can add more relying party policies. Por exemplo, apagar a minha conta, alterar um número de telefone, a política do partido de singing SAML e muito mais.For example, delete my account, change a phone number, SAML relying party policy and more.

O diagrama que se segue mostra a relação entre os ficheiros políticos e as aplicações do partido em gestão.The following diagram shows the relationship between the policy files and the relying party applications.

Diagrama mostrando o modelo de herança de política de confiança

Documentação de orientação e melhores práticasGuidance and best practices

Melhores práticasBest practices

Dentro de uma política personalizada Azure AD B2C, pode integrar a sua própria lógica de negócio para construir as experiências de utilizador que necessita e alargar a funcionalidade do serviço.Within an Azure AD B2C custom policy, you can integrate your own business logic to build the user experiences you require and extend functionality of the service. Temos um conjunto de boas práticas e recomendações para começar.We have a set of best practices and recommendations to get started.

  • Crie a sua lógica dentro da política de extensão, ou baseando-se na política partidária.Create your logic within the extension policy, or relying party policy. Pode adicionar novos elementos, que irão sobrepor-se à política de base, fazendo referência ao mesmo ID.You can add new elements, which will override the base policy by referencing the same ID. Isto irá permitir-lhe escalar o seu projeto, facilitando o upgrade da política de base mais tarde se a Microsoft lançar novos packs de arranque.This will allow you to scale out your project while making it easier to upgrade base policy later on if Microsoft releases new starter packs.
  • Dentro da política de base, recomendamos vivamente evitar fazer quaisquer alterações.Within the base policy, we highly recommend avoiding making any changes. Quando necessário, faça comentários onde as alterações são feitas.When necessary, make comments where the changes are made.
  • Quando estiver a sobrevaver um elemento, como metadados de perfil técnico, evite copiar todo o perfil técnico da política base.When you're overriding an element, such as technical profile metadata, avoid copying the entire technical profile from the base policy. Em vez disso, copie apenas a secção necessária do elemento.Instead, copy only the required section of the element. Consulte a verificação de e-mail desativada para um exemplo de como fazer a alteração.See Disable email verification for an example of how to make the change.
  • Para reduzir a duplicação de perfis técnicos, onde a funcionalidade principal é partilhada, utilize a inclusão do perfil técnico.To reduce duplication of technical profiles, where core functionality is shared, use technical profile inclusion.
  • Evite escrever para o diretório AD Azure durante a entrada, o que pode levar a problemas de estrangulamento.Avoid writing to the Azure AD directory during sign-in, which may lead to throttling issues.
  • Se a sua política tiver dependências externas, como ASP de REST, certifique-se de que estão altamente disponíveis.If your policy has external dependencies, such as REST APIs, makes sure they're highly available.
  • Para uma melhor experiência do utilizador, certifique-se de que os seus modelos HTML personalizados são implantados globalmente usando a entrega de conteúdo on-line.For a better user experience, make sure your custom HTML templates, are globally deployed using online content delivery. A Azure Content Delivery Network (CDN) permite reduzir os tempos de carga, poupar largura de banda e melhorar a velocidade de resposta.Azure Content Delivery Network (CDN) lets you reduce load times, save bandwidth, and improve response speed.
  • Se pretender alterar a viagem do utilizador, copie toda a viagem do utilizador da política base para a política de extensão.If you want to make a change to user journey, copy the entire user journey from the base policy to the extension policy. Forneça um ID de viagem de utilizador único para a viagem de utilizador que copiou.Provide a unique user journey ID to the user journey you've copied. Em seguida, na política do partido em apoio,altere o elemento de viagem do utilizador predefinido para apontar para a nova jornada do utilizador.Then in the relying party policy, change the default user journey element to point to the new user journey.

Resolução de problemasTroubleshooting

Ao desenvolver-se com as políticas Azure AD B2C, poderá encontrar erros ou exceções durante a execução da sua viagem de utilizador.When developing with Azure AD B2C policies, you may run into errors or exceptions while executing your user journey. O pode ser investigado usando Insights de Aplicação.The can be investigated using Application Insights.

Integração contínuaContinuous integration

Utilizando um pipeline de integração e entrega contínua (CI/CD) que instalou em Azure Pipelines, pode incluir as suas políticas personalizadas Azure AD B2C na sua entrega de software e automatização de controlo de código.By using a continuous integration and delivery (CI/CD) pipeline that you set up in Azure Pipelines, you can include your Azure AD B2C custom policies in your software delivery and code control automation. À medida que se implanta em diferentes ambientes AD B2C Ad, por exemplo dev, teste e produção, recomendamos que remova os processos manuais e realize testes automatizados utilizando gasodutos Azure.As you deploy to different Azure AD B2C environments, for example dev, test, and production, we recommend that you remove manual processes and perform automated testing by using Azure Pipelines.

Preparar o ambientePrepare your environment

Você começa com a política personalizada Azure AD B2C:You get started with Azure AD B2C custom policy:

  1. Criar um inquilino do Azure AD B2CCreate an Azure AD B2C tenant
  2. Registe uma aplicação web utilizando o portal Azure para que possa testar a sua política.Register a web application using the Azure portal so you'll be able to test your policy.
  3. Adicione as chaves de política necessárias e registe as aplicações do Quadro de Experiência de Identidade.Add the necessary policy keys and register the Identity Experience Framework applications.
  4. Obtenha o pacote de arranque de política Azure AD B2C e faça o upload para o seu inquilino.Get the Azure AD B2C policy starter pack and upload to your tenant.
  5. Depois de fazer o upload do pacote inicial, teste a sua política de inscrição ou de inscrição.After you upload the starter pack, test your sign-up or sign-in policy.
  6. Recomendamos que descarregue e instale o Código do Estúdio Visual (Código VS).We recommend you to download and install Visual Studio Code (VS Code). Visual Studio Code é um editor de código fonte leve mas poderoso, que funciona no seu ambiente de trabalho e está disponível para Windows, macOS e Linux.Visual Studio Code is a lightweight but powerful source code editor, which runs on your desktop and is available for Windows, macOS, and Linux. Com o Código VS, pode navegar rapidamente e editar os seus ficheiros XML de política personalizada Azure AD B2C, instalando a extensão Azure AD B2C para o Código VSWith VS Code, you can quickly navigate through and edit your Azure AD B2C custom policy XML files by installing the Azure AD B2C extension for VS Code

Passos seguintesNext steps

Depois de configurar e testar a sua política Azure AD B2C, pode começar a personalizar a sua política.After you set up and test your Azure AD B2C policy, you can start customizing your policy. Veja os seguintes artigos para aprender a:Go through the following articles to learn how to:

  • Adicione reclamações e personalize a entrada do utilizador usando políticas personalizadas.Add claims and customize user input using custom policies. Saiba como definir uma reclamação e adicionar uma reclamação à interface do utilizador personalizando alguns dos perfis técnicos do pacote inicial.Learn how to define a claim and add a claim to the user interface by customizing some of the starter pack technical profiles.
  • Personalize a interface de utilizador da sua aplicação utilizando uma política personalizada.Customize the user interface of your application using a custom policy. Aprenda a criar o seu próprio conteúdo HTML e personalize a definição de conteúdo.Learn how to create your own HTML content, and customize the content definition.
  • Localize a interface de utilizador da sua aplicação utilizando uma política personalizada.Localize the user interface of your application using a custom policy. Aprenda a configurar a lista de línguas apoiadas e forneça rótulos específicos da linguagem, adicionando o elemento de recursos localizado.Learn how to set up the list of supported languages, and provide language-specific labels, by adding the localized resources element.
  • Durante o desenvolvimento e teste da sua política, pode desativar a verificação de e-mail.During your policy development and testing, you can disable email verification. Saiba como substituir um metadados de perfil técnico.Learn how to overwrite a technical profile metadata.
  • Instale o sôm-in com uma conta google utilizando políticas personalizadas.Set up sign-in with a Google account using custom policies. Saiba como criar um novo fornecedor de reclamações com perfil técnico OAuth2.Learn how to create a new claims provider with OAuth2 technical profile. Em seguida, personalize a viagem do utilizador para incluir a opção de inscrição no Google.Then customize the user journey to include the Google sign-in option.
  • Para diagnosticar problemas com as suas políticas personalizadas pode recolher registos B2C do Azure Ative Directory com Insights de Aplicação.To diagnose problems with your custom policies you can Collect Azure Active Directory B2C logs with Application Insights. Aprenda a adicionar novos perfis técnicos e configuure a sua política partidária.Learn how to add new technical profiles, and configure your relying party policy.