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

Artigo
01/11/2024

Nota

No Azure Ative Directory B2C, as políticas personalizadas são projetadas principalmente para lidar com cenários complexos. Para a maioria dos cenários, recomendamos que você use fluxos de usuário internos. Se você não tiver feito isso, saiba mais sobre o pacote inicial de políticas personalizadas em Introdução às políticas personalizadas no Ative Directory B2C.

O Azure Ative Directory B2C (Azure AD B2C) fornece suporte para o gerenciamento de usuários do Microsoft Entra. Este artigo descreve as especificidades de um perfil técnico para interagir com um provedor de declarações que oferece suporte a esse protocolo padronizado.

Protocolo

O atributo Name do elemento Protocol precisa ser definido como Proprietary. O atributo handler deve conter o nome totalmente qualificado do assembly Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=nulldo manipulador de protocolo.

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

AAD-UserReadUsingAlternativeSecurityId e AAD-UserReadUsingAlternativeSecurityId-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 - Crie uma nova conta local.
AAD-UserWritePasswordUsingObjectId - Atualize uma senha de uma conta local.
AAD-UserWriteProfileUsingObjectId - Atualize um perfil de usuário de uma conta local ou social.
AAD-UserReadUsingObjectId - Leia um perfil de usuário de uma conta local ou social.
AAD-UserWritePhoneNumberUsingObjectId - Escreva 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 procurar uma conta no diretório ou criar uma nova. 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 definida em sua política para o nome definido no ID do Microsoft Entra.

Para ler, atualizar ou excluir uma conta de usuário existente, a declaração de entrada é uma chave que identifica exclusivamente a conta no diretório do Microsoft Entra. Por exemplo, objectId, userPrincipalName, signInNames.emailAddress, signInNames.userName ou alternativeSecurityId.

Para criar uma nova 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. Para uma conta federada: o 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 a declaração de entrada 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 definida em sua política para o nome definido no ID do Microsoft Entra. Você também pode incluir declarações que não são retornadas pela ID do Microsoft Entra, desde que você defina o DefaultValue atributo.

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

Por exemplo, o perfil técnico 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 principal do usuário da nova conta
signInNames.emailAddress, que é o nome de entrada da conta, semelhante à declaração de entrada de e-mail

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

Reivindicações persistentes

O elemento PersistedClaims contém todos os valores que devem ser persistidos pelo ID do Microsoft Entra 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 Microsoft Entra.

O perfil técnico AAD-UserWriteUsingLogonEmail , que cria uma nova conta local, persiste as seguintes declarações:

  <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 é o nome do atributo Microsoft Entra, a menos que o atributo PartnerClaimType seja especificado, que contém o nome do atributo Microsoft Entra.

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 de 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, declarações de saída e declarações 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

Lida

A operação Read lê dados sobre uma única conta de usuário. O perfil técnico a seguir lê 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>

Escrever

A operação Write cria ou atualiza uma única conta de usuário. 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 fornecida de declarações. O seguinte perfil técnico 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 principal do usuário:

<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 seguinte perfil técnico 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	Description
Operação	Sim	A operação a ser executada. Valores possíveis: `Read`, , `WriteDeleteClaims`, ou `DeleteClaimsPrincipal`.
RaiseErrorIfClaimsPrincipalDoesNotExist	Não	Gerar um erro se o objeto de usuário não existir no diretório. Valores possíveis: `true` ou `false`.
RaiseErrorIfClaimsPrincipalAlreadyExists	Não	Gerar um erro se o objeto de usuário já existir. Valores possíveis: `true` ou `false`. Esses metadados são aplicáveis somente para a operação Write.
ApplicationObjectId	Não	O identificador de objeto do aplicativo para atributos de extensão. Valor: ObjectId de um aplicativo. Para obter mais informações, consulte Usar atributos personalizados.
ClientId	Não	O identificador do cliente para acessar o locatário como um terceiro. Para obter mais informações, consulte Usar atributos personalizados em uma política de edição de perfil personalizada
IncludeClaimResolvingInClaimsHandling	Não	Para 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 você quiser usar um resolvedor de declarações no perfil técnico, defina isso como `true`.

Elementos da IU

As configurações a seguir podem ser usadas para configurar a mensagem de erro exibida em caso de falha. Os metadados devem ser configurados no perfil técnico autodeclarado . As mensagens de erro podem ser localizadas.

Atributo	Obrigatório	Description
UserMessageIfClaimsPrincipalAlreadyExists	Não	Se um erro for gerado (consulte a descrição do atributo RaiseErrorIfClaimsPrincipalAlreadyExists), especifique a mensagem a ser mostrada ao usuário se o objeto de usuário já existir.
UserMessageIfClaimsPrincipalDoesNotExist	Não	Se um erro for gerado (consulte a descrição do atributo RaiseErrorIfClaimsPrincipalDoesNotExist), especifique a mensagem a ser exibida ao usuário se o objeto do usuário não existir.

Próximos passos

Consulte o seguinte artigo, por exemplo, 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 Ative Directory B2C