Definir um perfil técnico do Microsoft Entra em uma política personalizada do Azure Active Directory B2C

Artigo
01/11/2024

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.

O Azure AD (Active Directory) B2C dá suporte ao gerenciamento de usuários do Microsoft Entra. Este artigo descreve as especificações de um perfil técnico para interagir com um provedor de declarações compatível com esse protocolo padronizado.

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 Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Os perfis técnicos do Microsoft Entra a seguir relativos ao pacote inicial de políticas personalizadas incluem o perfil técnico AAD-Common. Os perfis técnicos do Microsoft Entra não especificam o protocolo porque ele está configurado no perfil técnico AAD-Common:

AAD-UserReadUsingAlternativeSecurityId e UserReadUsingAlternativeSecurityId-AAD-NoError – procure uma conta social no diretório.
AAD-UserWriteUsingAlternativeSecurityId – crie uma nova conta social.
AAD-UserReadUsingEmailAddress – procure uma conta local no diretório.
AAD-UserWriteUsingLogonEmail – criar uma nova conta local.
AAD-UserWritePasswordUsingObjectId – atualize uma senha de uma conta local.
AAD-UserWriteProfileUsingObjectId – atualize um perfil do usuário de uma conta local ou social.
AAD-UserReadUsingObjectId – leia um perfil do usuário de uma conta local ou social.
AAD-UserWritePhoneNumberUsingObjectId – grave o número de telefone MFA de uma conta local ou social

O exemplo a seguir mostra o perfil técnico AAD-Common:

<TechnicalProfile Id="AAD-Common">
  <DisplayName>Azure Active Directory</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

  <CryptographicKeys>
    <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
  </CryptographicKeys>

  <!-- We need this here to suppress the SelfAsserted provider from invoking SSO on validation profiles. -->
  <IncludeInSso>false</IncludeInSso>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

InputClaims

O elemento InputClaims contém uma declaração que é usada para pesquisar uma conta no diretório ou criar uma. Deve haver exatamente um elemento InputClaim na coleção de declarações de entrada para todos os perfis técnicos do Microsoft Entra. Talvez seja necessário mapear o nome da declaração definido na política para o nome definido no Microsoft Entra ID.

A declaração de entrada é uma chave que identifica exclusivamente as contas de usuário existentes no diretório do Microsoft Entra quando você deseja ler, atualizar ou excluir uma delas. Por exemplo, objectId, userPrincipalName, signInNames.emailAddress, signInNames.userName ou alternativeSecurityId.

Para criar uma conta de usuário, a declaração de entrada é uma chave que identifica exclusivamente uma conta local ou federada. Por exemplo, conta local: signInNames.emailAddress ou signInNames.userName. No caso da conta federada: alternativeSecurityId.

O elemento InputClaimsTransformations pode conter uma coleção de elementos de transformação de declarações de entrada que são usados para modificar essa declaração ou gerar uma nova.

OutputClaims

O elemento OutputClaims contém uma lista de declarações retornadas pelo perfil técnico do Microsoft Entra. Talvez seja necessário mapear o nome da declaração definido na política para o nome definido no Microsoft Entra ID. Ao definir o atributo DefaultValue, também é possível incluir declarações que não são retornadas pelo Microsoft Entra ID.

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.

Por exemplo, o perfil técnico de AAD-UserWriteUsingLogonEmail cria uma conta local e retorna as seguintes declarações:

objectId, que é o identificador da nova conta
newUser, que indica se o usuário é novo
authenticationSource, que define a autenticação como localAccountAuthentication
userPrincipalName, que é o nome UPN da nova conta
signInNames.emailAddress, que é o nome de entrada na conta, semelhante à declaração de entrada de email

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="objectId" />
  <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="localAccountAuthentication" />
  <OutputClaim ClaimTypeReferenceId="userPrincipalName" />
  <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
</OutputClaims>

PersistedClaims

O elemento PersistedClaims contém todos os valores que devem ser persistidos pelo Microsoft Entra ID com possíveis informações de mapeamento entre um tipo de declaração já definido na seção ClaimsSchema da política e o nome do atributo do Microsoft Entra.

O perfil técnico do AAD-UserWriteUsingLogonEmail, que cria a nova conta local, mantém as declarações a seguir:

  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="email" PartnerClaimType="signInNames.emailAddress" />
    <PersistedClaim ClaimTypeReferenceId="newPassword" PartnerClaimType="password"/>
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="passwordPolicies" DefaultValue="DisablePasswordExpiration" />

    <!-- Optional claims. -->
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>

O nome da declaração será o nome do atributo do Microsoft Entra, a menos que o atributo PartnerClaimType, que contém o nome do atributo do Microsoft Entra, seja especificado.

Requisitos de uma operação

Deve haver exatamente um elemento InputClaim no pacote de declarações para todos os perfis técnicos do Microsoft Entra.
O artigo sobre atributos de perfil de usuário descreve os atributos de perfil de usuário do Azure AD B2C com suporte que você pode usar nas declarações de entrada, de saída e persistentes.
Se a operação for Write ou DeleteClaims, ela também deverá aparecer em um elemento PersistedClaims.
O valor da declaração userPrincipalName deve estar no formato de user@tenant.onmicrosoft.com.
A declaração displayName é necessária e não pode ser uma cadeia de caracteres vazia.

Operações de perfil técnico do Microsoft Entra

Leitura

A operação Ler os dados sobre uma conta de usuário único. O perfil técnico a seguir lê os dados sobre uma conta de usuário usando o objectId do usuário:

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
  <Metadata>
    <Item Key="Operation">Read</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">true</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims>

    <!-- Required claims -->
    <OutputClaim ClaimTypeReferenceId="strongAuthenticationPhoneNumber" />

    <!-- Optional claims -->
    <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
    <OutputClaim ClaimTypeReferenceId="displayName" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
    <OutputClaim ClaimTypeReferenceId="givenName" />
    <OutputClaim ClaimTypeReferenceId="surname" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Gravar

A operação Gravar cria ou atualiza uma conta de usuário único. O seguinte perfil técnico cria uma nova conta social:

<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">Write</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
    <Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CreateOtherMailsFromEmail" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="AlternativeSecurityId" PartnerClaimType="alternativeSecurityId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <PersistedClaim ClaimTypeReferenceId="userPrincipalName" />
    <PersistedClaim ClaimTypeReferenceId="mailNickName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />

    <!-- Optional claims -->
    <PersistedClaim ClaimTypeReferenceId="otherMails" />
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

DeleteClaims

A operação DeleteClaims limpa as informações de uma lista de declarações fornecida. O perfil técnico a seguir exclui declarações:

<TechnicalProfile Id="AAD-DeleteClaimsUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaims</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <PersistedClaim ClaimTypeReferenceId="objectId" />
    <PersistedClaim ClaimTypeReferenceId="Verified.strongAuthenticationPhoneNumber" PartnerClaimType="strongAuthenticationPhoneNumber" />
  </PersistedClaims>
  <OutputClaims />
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

DeleteClaimsPrincipal

A operação DeleteClaimsPrincipal exclui uma única conta de usuário do diretório. O perfil técnico a seguir exclui uma conta de usuário do diretório usando o nome UPN:

<TechnicalProfile Id="AAD-DeleteUserUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

O perfil técnico a seguir exclui uma conta de usuário social usando alternativeSecurityId:

<TechnicalProfile Id="AAD-DeleteUserUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

Metadados

Atributo	Obrigatório	Descrição
Operação	Sim	A operação a ser executada. Valores possíveis: `Read`, `Write`, `DeleteClaims` ou `DeleteClaimsPrincipal`.
RaiseErrorIfClaimsPrincipalDoesNotExist	Não	Gere um erro se o objeto de usuário não existe no diretório. Valores possíveis: `true` ou `false`.
RaiseErrorIfClaimsPrincipalAlreadyExists	Não	Gere um erro se o objeto de usuário já existe. Valores possíveis: `true` ou `false`. Esses metadados são aplicáveis somente para a operação de gravação.
ApplicationObjectId	Não	O identificador de objeto de aplicativo para atributos de extensão. Valor: ObjectId de um aplicativo. Para obter mais informações, confira Usar atributos personalizados.
ClientId	Não	O identificador de cliente para acessar o locatário como um terceiro. Para obter mais informações, veja Atributos personalizados de uso em uma política de edição de perfil personalizada
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). Para usar um resolvedor de declarações no perfil técnico, defina-o como `true`.

Elementos da interface do usuário

As configurações a seguir podem ser usadas para configurar a mensagem de erro exibida após a falha. Os metadados devem ser configurados no perfil técnico autodeclarado. A mensagem de erro pode ser localizada.

Atributo	Obrigatório	Descrição
UserMessageIfClaimsPrincipalAlreadyExists	Não	Se um erro for gerado (veja a descrição do atributo RaiseErrorIfClaimsPrincipalAlreadyExists), especifique a mensagem a mostrar ao usuário se o objeto de usuário já existe.
UserMessageIfClaimsPrincipalDoesNotExist	Não	Caso um erro deva ser gerado (veja a descrição do atributo RaiseErrorIfClaimsPrincipalDoesNotExist), especifique a mensagem para mostrar ao usuário se o objeto de usuário não existe.

Próximas etapas

Confira o seguinte artigo, por exemplo, para saber como usar o perfil técnico do Microsoft Entra:

Adicionar declarações e personalizar a entrada do usuário usando políticas personalizadas no Azure Active Directory B2C