Compartilhar via

Defina um perfil técnico autodeclarado em uma política personalizada do Azure Active Directory B2C

  • Artigo

Observação

No Azure Active Directory B2C, as políticas personalizadas são projetadas principalmente para tratar de cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuários predefinidos. Se você ainda não fez isso, saiba mais sobre o pacote de início de política personalizado em Introdução às políticas personalizadas no Active Directory B2C.

Todas as interações no Azure Active Directory B2C (Azure AD B2C) em que o usuário precisa fornecer uma entrada são perfis técnicos autodeclarados. Por exemplo, uma página de inscrição, entrada ou redefinição de senha.

Protocolo

O atributo Name do elemento Protocol precisa ser definido como Proprietary. O atributo manipulador deve conter o nome totalmente qualificado do assembly do manipulador de protocolo usado pelo Azure AD B2C, para autodeclaração: Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null

O exemplo a seguir mostra um perfil técnico autodeclarado para email de inscrição:

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

Declarações de entrada

Em um perfil técnico autodeclarado, é possível usar os elementos InputClaims e InputClaimsTransformations para preencher previamente o valor das declarações que aparecem na página autodeclarada (exibir declarações). Por exemplo, na política de edição de perfil, o percurso do usuário primeiro lê o perfil do usuário do serviço de diretório do Azure AD B2C. Em seguida, o perfil técnico autodeclarado define as declarações de entrada com os dados do usuário armazenados no perfil do usuário. Essas declarações são coletadas do perfil do usuário e, em seguida, apresentadas a ele, que poderá editar os dados existentes.

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <InputClaim ClaimTypeReferenceId="userPrincipalName" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" />
  </InputClaims>

Exibir declarações

O elemento DisplayClaims contém uma lista de declarações que são apresentadas na tela para coletar dados do usuário. Para preencher previamente os valores das declarações de exibição, use as declarações de entrada descritas anteriormente. O elemento também pode conter um valor padrão.

A ordem das declarações em DisplayClaims especifica a ordem na qual o Azure AD B2C renderiza as declarações na tela. Para forçar o usuário a fornecer um valor para uma declaração específica, defina o atributo Required do elemento DisplayClaim como true.

O elemento ClaimType da coleção DisplayClaims precisa ser definir o elemento UserInputType como qualquer tipo de entrada do usuário compatível com o Azure AD B2C. Por exemplo, TextBox ou DropdownSingleSelect.

Adicionar uma referência a um DisplayControl

Na coleção de declarações de exibição, é possível incluir uma referência ao DisplayControl que você criou. Um controle de exibição é um elemento de interface do usuário que tem funcionalidade especial e interage com o serviço de back-end do Azure AD B2C. Ele permite que o usuário execute ações na página que invocam um perfil técnico de validação no back-end. Por exemplo, a verificação de um endereço de email, número de telefone ou número de fidelidade do cliente.

O exemplo de TechnicalProfile a seguir ilustra o uso de declarações de exibição com controles de exibição.

  • A primeira declaração de exibição faz referência ao emailVerificationControl controle de exibição, que coleta e verifica o endereço de email.
  • A segunda declaração de exibição faz uma referência ao controle de exibição, que gera e verifica o captchaChallengeControl código CAPTCHA.
  • A sexta declaração de exibição faz uma referência ao phoneVerificationControl controle de exibição, que coleta e verifica um número de telefone.
  • As outras declarações de exibição são ClaimType a serem coletados do usuário.
<TechnicalProfile Id="Id">
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="captchaChallengeControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim DisplayControlReferenceId="phoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
</TechnicalProfile>

Como mencionado, uma declaração de exibição com uma referência a um controle de exibição pode executar a própria validação, por exemplo, confirmar o endereço de email. Além disso, a página autodeclarada permite o uso de um perfil técnico de validação para validar a página inteira, inclusive qualquer entrada do usuário (tipos de declaração ou controles de exibição), antes de passar para a próxima etapa de orquestração.

Combine o uso de declarações de exibição e de saída com cuidado

Se você especificar um ou mais elementos DisplayClaim em um perfil técnico autodeclarado, precisará usar um DisplayClaim para cada declaração que quer exibir na tela e coletar do usuário. Nenhuma declaração de saída será exibida por um perfil técnico autodeclarado que contenha pelo menos uma declaração de exibição.

Considere o exemplo a seguir no qual uma declaração age é definida como uma declaração de saída em uma política de base. Antes de adicionar qualquer declaração de exibição ao perfil técnico autodeclarado, a declaração age é exibida na tela de coleta de dados do usuário:

<TechnicalProfile Id="id">
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="age" />
  </OutputClaims>
</TechnicalProfile>

Se uma política de folha que herda essa base a seguir especificar officeNumber como uma declaração de exibição:

<TechnicalProfile Id="id">
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="officeNumber" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="officeNumber" />
  </OutputClaims>
</TechnicalProfile>

A age declaração na política básica não é mais apresentada na tela para o usuário - ela está efetivamente "oculta". Para exibir a age declaração e coletar o valor de idade do usuário, você deve adicionar um age DisplayClaim.

Declarações de saída

O elemento OutputClaims contém uma lista de declarações a serem retornadas para a próxima etapa de orquestração. O atributo DefaultValue entra em vigor somente se a declaração nunca tiver sido definida. Se ela foi definida em uma etapa anterior da orquestração, o valor padrão não entra em vigor mesmo se o usuário deixar o valor vazio. Para forçar o uso de um valor padrão, defina o atributo AlwaysUseDefaultValue como true.

Por motivos de segurança, um valor de declaração de senha (UserInputType definido como Password) está disponível somente para perfis técnicos de validação do perfil técnico autodeclarado. Você não pode usar a declaração de senha nas próximas etapas de orquestração.

Observação

Nas versões anteriores do Identity Experience Framework (IEF), as declarações de saída eram usadas para coletar dados do usuário. Para coletar dados do usuário, use uma coleção DisplayClaims.

O elemento OutputClaimsTransformations pode conter uma coleção de elementos OutputClaimsTransformation usados para modificar as declarações de saída ou gerar novas declarações.

Quando você deve usar declarações de saída

Em um perfil técnico autodeclarado, a coleção de declarações de saída retorna as declarações para a próxima etapa de orquestração.

Use declarações de saída quando:

  • As declarações são enviadas pela transformação declarações de saída.
  • Definir um valor padrão em uma declaração de saída: sem coletar de dados do usuário ou retornar os dados do perfil técnico de validação. O perfil técnico autodeclarado LocalAccountSignUpWithLogonEmail define a declaração executed-SelfAsserted-Input como true.
  • Um perfil técnico de validação retorna as declarações de saída: seu perfil técnico pode chamar um perfil técnico de validação que retorna algumas declarações. Talvez você queira juntar as declarações e retorná-las para as próximas etapas de orquestração no percurso do usuário. Por exemplo, ao entrar com uma conta local, o perfil técnico autodeclarado de nome SelfAsserted-LocalAccountSignin-Email chama o perfil técnico de validação chamado login-NonInteractive. Esse perfil técnico valida as credenciais do usuário e também retorna o perfil do usuário. Como 'userPrincipalName', 'displayName', 'givenName' e 'surName'.
  • Um controle de exibição retorna as declarações de saída - Seu perfil técnico pode ter uma referência a um controle de exibição. O controle de exibição retorna algumas declarações, como o endereço de email verificado. Talvez você queira juntar as declarações e retorná-las para as próximas etapas de orquestração no percurso do usuário.

O exemplo a seguir demonstra o uso de um perfil técnico autodeclarado que usa declarações de exibição e de saída.

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="IpAddressClaimReferenceId">IpAddress</Item>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    <Item Key="language.button_continue">Create</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="email" />
  </InputClaims>
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="SecondaryEmailVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="newPassword" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="reenterPassword" Required="true" />
  </DisplayClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="email" Required="true" />
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="executed-SelfAsserted-Input" DefaultValue="true" />
    <OutputClaim ClaimTypeReferenceId="authenticationSource" />
    <OutputClaim ClaimTypeReferenceId="newUser" />
  </OutputClaims>
  <ValidationTechnicalProfiles>
    <ValidationTechnicalProfile ReferenceId="AAD-UserWriteUsingLogonEmail" />
  </ValidationTechnicalProfiles>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

Observação

Quando você coleta o valor da declaração de senha no perfil técnico autodeclarado, esse valor só fica disponível dentro do mesmo perfil técnico ou dentro de perfis técnicos de validação referenciados por esse mesmo perfil técnico autodeclarado. Quando a execução desse perfil técnico autodeclarado é concluída e movida para outro perfil técnico, o valor da senha é perdido. Consequentemente, a declaração de senha só pode ser armazenada na etapa de orquestração na qual ela é coletada.

Página de inscrição ou entrada de declarações de saída

Em uma página de inscrição e entrada combinada, observe o seguinte ao usar um elemento DataUri de definição de conteúdo, que especifica um tipo de página unifiedssp ou unifiedssd:

  • Somente as declarações de nome de usuário e senha são renderizadas.
  • As duas primeiras declarações de saída precisam ser o nome de usuário e a senha (nesta ordem).
  • Nenhuma outra declaração é renderizada. Nessas declarações, você precisará definir defaultValue ou invocar um perfil técnico de validação de formulário de declarações.

Declarações de persistência

O elemento PersistedClaims não é usado. O perfil técnico autodeclarado não persiste os dados para o Azure AD B2C. Em vez disso, é feita uma chamada para um perfil técnico de validação responsável por persistir os dados. Por exemplo, a política de inscrição usa o perfil técnico autodeclarado LocalAccountSignUpWithLogonEmail para coletar o novo perfil do usuário. O perfil técnico LocalAccountSignUpWithLogonEmail chama o perfil técnico de validação para criar a conta no Azure AD B2C.

Perfis técnicos de validação

Um perfil técnico de validação é usado para validar algumas ou todas as declarações de saída do perfil técnico de referência. As declarações de entrada do perfil técnico de validação precisam aparecer nas declarações de saída do perfil técnico autodeclarado. O perfil técnico de validação valida a entrada do usuário e pode retornar um erro ao usuário.

O perfil técnico de validação pode ser qualquer perfil técnico na política, como perfis técnicos da ID do Microsoft Entra ou API REST. No exemplo anterior, o perfil técnico LocalAccountSignUpWithLogonEmail valida que o signinName não existe no diretório. Caso contrário, o perfil técnico de validação cria uma conta local e retorna objectId, authenticationSource e newUser. O perfil técnico SelfAsserted-LocalAccountSignin-Email chama o perfil técnico de validação login-NonInteractive para validar as credenciais do usuário.

Também é possível chamar um perfil técnico da API REST com a lógica de negócios, substituir as declarações de entrada ou aprimorar os dados do usuário integrando ainda mais com aplicativos de linha de negócios corporativos. Para saber mais, confira Perfil técnico de validação

Observação

Um perfil técnico de validação só é disparado quando há uma entrada do usuário. Você não pode criar um perfil técnico autodeclarado vazio para chamar um perfil técnico de validação apenas para aproveitar o atributo ContinueOnError de um elemento ValidationTechnicalProfile. Você só pode chamar um perfil técnico de validação de um perfil técnico autodeclarado que solicita uma entrada do usuário ou de uma etapa de orquestração em um percurso do usuário.

Metadados

Atributo Obrigatório Descrição
setting.operatingMode 1 Não Em uma página de entrada, essa propriedade controla o comportamento do campo nome de usuário, como validação de entradas e mensagens de erro. Valores esperados: Username ou Email. Confira a Demonstração ao vivo desses metadados.
AllowGenerationOfClaimsWithNullValues Não Permitir a geração de uma declaração com valor nulo. Por exemplo, caso o usuário não marque uma caixa de seleção.
ContentDefinitionReferenceId Sim O identificador da definição de conteúdo associada com este perfil técnico.
EnforceEmailVerification Não Na inscrição ou edição de perfil, reforça a verificação de email. Valores possíveis: true (padrão) ou false.
setting.retryLimit Não Controla a quantidade de vezes que um usuário pode tentar fornecer os dados verificados pelo perfil técnico de validação. Por exemplo, um usuário tenta se inscrever com uma conta que já existe e continua tentando até que o limite seja atingido. Confira a Demonstração ao vivo desses metadados.
SignUpTarget 1 Não O identificador de troca do destino da inscrição. Quando o usuário clica no botão de inscrição, o Azure AD B2C executa o identificador de troca especificado.
setting.showCancelButton Não Mostra o botão cancelar. Valores possíveis: true (padrão) ou false. Confira a Demonstração ao vivo desses metadados.
setting.showContinueButton Não Mostra o botão continuar. Valores possíveis: true (padrão) ou false. Confira a Demonstração ao vivo desses metadados.
setting.showSignupLink 2 Não Mostra o botão de inscrição. Valores possíveis: true (padrão) ou false. Confira a Demonstração ao vivo desses metadados.
setting.forgotPasswordLinkLocation 2 Não Exibe o link de esquecimento de senha. Valores possíveis: AfterLabel (padrão) exibe o link diretamente após o rótulo ou depois do campo de entrada de senha quando não há nenhum rótulo, AfterInput exibe o link após o campo de entrada de senha, AfterButtons exibe o link na parte inferior do formulário após os botões ou None remove o link de senha esquecida. Confira a Demonstração ao vivo desses metadados.
setting.enableRememberMe 2 Não Exibe a caixa de seleção Manter-me conectado. Valores possíveis: true ou false (padrão). Demonstração ao vivo desses metadados.
setting.inputVerificationDelayTimeInMilliseconds 3 Não Melhora a experiência do usuário, aguardando que o usuário pare de digitar e, em seguida, valida o valor. Valor padrão de 2.000 milissegundos. Confira a Demonstração ao vivo desses metadados.
IncludeClaimResolvingInClaimsHandling Não Em declarações de entrada e saída, especifica se a resolução de declarações está incluída no perfil técnico. Valores possíveis: true ou false (padrão). Se quiser usar um resolvedor de declarações no perfil técnico, defina como true.
setting.forgotPasswordLinkOverride 4 Não Uma troca de declarações de redefinição de senha a ser executada. Para obter mais informações, confira Redefinição de senha self-service.
setting.enableCaptchaChallenge Não Especifica se o código de desafio CAPTCHA deve ser exibido. Valores possíveis: true ou false (padrão). Para que essa configuração funcione, o controle de exibição CAPTCHA deve ser referenciado nas declarações de exibição do perfil técnico autodeclarado. O recurso CAPTCHA está em visualização pública.
setting.showHeading Não Especifica se o elemento de cabeçalho Detalhes do Usuário deve estar visível. Valores possíveis: true (padrão) ou false.

Observações:

  1. Disponível para o tipo DataUri da definição de conteúdo de unifiedssp ou unifiedssd.
  2. Disponível para o tipo DataUri da definição de conteúdo de unifiedssp ou unifiedssd. Layout de página versão 1.1.0 e posterior.
  3. Disponível para o layout de página versão 1.2.0 e superiores.
  4. Disponível para o tipo DataUri da definição de conteúdo de unifiedssp. Layout de página versão 2.1.2 e posterior.

Chaves criptográficas

O elemento CryptographicKeys não será usado.