Compartilhar via


Definir atributos personalizados no Azure Active Directory B2C

Antes de começar, use o seletor Escolher um tipo de política para escolher o tipo de política que você está configurando. O Azure Active Directory B2C oferece dois métodos para definir como os usuários interagem com seus aplicativos: por meio de fluxos dos usuários predefinidos ou de políticas personalizadas totalmente configuráveis. As etapas necessárias neste artigo são diferentes para cada método.

No artigo Adicionar declarações e personalizar a entrada de usuário usando políticas personalizadas, você aprenderá a usar os atributos de perfil do usuário internos. Neste artigo, você pode habilitar um atributo personalizado no seu diretório do Azure AD B2C (Azure Active Directory B2C). Posteriormente, você pode usar o novo atributo como uma declaração personalizada em fluxos dos usuários ou políticas personalizadas simultaneamente.

Seu diretório do Microsoft Azure Active Directory B2C é fornecido com um conjunto interno de atributos. No entanto, geralmente você precisa criar os próprios atributos para gerenciar o seu cenário específico, por exemplo, quando:

  • Um aplicativo voltado ao cliente precisa manter um atributo loyaltyId.
  • Um provedor de identidade tem um identificador de usuário único, uniqueUserGUID, que precisa ser persistido.
  • Um percurso do usuário personalizado precisa persistir o estado do usuário, migrationStatus, para que outra lógica opere.

Os termos propriedade de extensão, atributo personalizado e declaração personalizada, se referem à mesma coisa no contexto deste artigo. O nome varia dependendo do contexto, como o aplicativo, objeto ou política.

O Azure AD B2C permite que você estenda o conjunto de atributos armazenados em cada conta de usuário. Você também pode ler e gravar esses atributos usando a API do Microsoft Graph.

Pré-requisitos

Como criar um atributo personalizado

  1. Entre no portal do Azure como administrador global do locatário Azure AD B2C.
  2. Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para o seu locatário do Azure Active Directory B2C no menu Diretórios + assinaturas.
  3. Escolha Todos os serviços no canto superior esquerdo do portal do Azure, procure e selecione Azure AD B2C.
  4. Selecione Atributos de usuário e, em seguida, selecione Adicionar.
  5. Forneça um Nome para o atributo personalizado (por exemplo, "ShoeSize")
  6. Escolha um Tipo de Dados. Somente Cadeia de Caracteres, Booliano e Int estão disponíveis.
  7. Opcionalmente, insira uma Descrição para fins informativos.
  8. Selecione Criar.

O atributo personalizado agora está disponível na lista de Atributos do usuário e para uso nos fluxos dos usuários. Um atributo personalizado só é criado na primeira vez que é usado em qualquer fluxo do usuário, não quando você o adiciona à lista de Atributos do usuário.

Usar um atributo personalizado em sua política

  1. No locatário do Azure AD B2C, selecione Fluxos dos usuários.
  2. Selecione sua política (por exemplo, "B2C_1_SignupSignin") para abri-la.
  3. Selecione Atributos de inscrição e, em seguida, selecione o atributo personalizado (por exemplo, "ShoeSize"). Clique em Salvar.
  4. Selecione Declarações de aplicativo e selecione o atributo personalizado.
  5. Clique em Salvar.

Depois de criar um novo usuário usando o fluxo de usuário, você pode usar o recurso Executar fluxo de usuário no fluxo do usuário para verificar a experiência do cliente. Agora você deve ver ShoeSize na lista de atributos coletados durante a jornada de inscrição, e vê-lo no token enviado de volta ao seu aplicativo.

Aplicativo de extensões do Azure AD B2C

Os atributos de extensão só podem ser registrados em um objeto de aplicativo, mesmo que possam conter dados de um usuário. O atributo de extensão é anexado ao aplicativo chamado b2c-extensions-app. Não modifique esse aplicativo, pois ele é usado pelo Azure AD B2C para armazenar dados do usuário. Você pode encontrar esse aplicativo em registros de aplicativo no Azure AD B2C.

Obter a ID de aplicativo do aplicativo de extensões

  1. Entre no portal do Azure.
  2. Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para o locatário do Azure AD B2C no menu Diretórios + assinaturas.
  3. No menu à esquerda, selecione Azure AD B2C. Ou selecione Todos os serviços e pesquise e selecione Azure AD B2C.
  4. Selecione Registros de aplicativo e selecione o Todos os aplicativos.
  5. Selecione o aplicativo b2c-extensions-app. Do not modify. Used by AADB2C for storing user data..
  6. Copie a ID do aplicativo. Exemplo: 11111111-1111-1111-1111-111111111111.

Obter as propriedades de aplicativo do aplicativo de extensões

  1. Entre no portal do Azure.
  2. Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para o seu locatário do Azure Active Directory B2C no menu Diretórios + assinaturas.
  3. No menu à esquerda, selecione Azure AD B2C. Ou selecione Todos os serviços e pesquise e selecione Azure AD B2C.
  4. Selecione Registros de aplicativo e selecione o Todos os aplicativos.
  5. Selecione o b2c-extensions-app. Não modifique. Usado pelo AADB2C para armazenar dados do usuário. Aplicativo .
  6. Copiar os identificadores a seguir para a sua área de transferência e salve-os:
    • ID do aplicativo. Exemplo: 11111111-1111-1111-1111-111111111111.
    • ID de objeto. Exemplo: 22222222-2222-2222-2222-222222222222.

Modificar a sua política personalizada

Para habilitar atributos personalizados na sua política, forneça a ID do aplicativo e a ID de objeto do aplicativo nos metadados do perfil técnico AAD-Common. O perfil técnico AAD-Common* está localizado no perfil técnico base do Microsoft Entra ID e dá suporte ao gerenciamento de usuários do Microsoft Entra. Outros perfis técnicos do Microsoft Entra ID incluem o AAD-Common para usar sua configuração. Substitua esse perfil técnico do AAD-Common no arquivo de extensão.

  1. Abra o arquivo de extensões da sua política. Por exemplo, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.

  2. Localize o elemento ClaimsProviders. Adicione um novo ClaimsProvider ao elemento ClaimsProviders.

  3. Insira a ID do Aplicativo que você registrou anteriormente, entre os elementos de abertura <Item Key="ClientId"> e de fechamento </Item>.

  4. Insira a ID do Objeto do Aplicativo que você registrou anteriormente, entre os elementos de abertura <Item Key="ApplicationObjectId"> e de fechamento </Item>.

    <!-- 
    <ClaimsProviders> -->
      <ClaimsProvider>
        <DisplayName>Azure Active Directory</DisplayName>
        <TechnicalProfiles>
          <TechnicalProfile Id="AAD-Common">
            <Metadata>
              <!--Insert b2c-extensions-app application ID here, for example: 11111111-1111-1111-1111-111111111111-->  
              <Item Key="ClientId"></Item>
              <!--Insert b2c-extensions-app application ObjectId here, for example: 22222222-2222-2222-2222-222222222222-->
              <Item Key="ApplicationObjectId"></Item>
            </Metadata>
          </TechnicalProfile>
        </TechnicalProfiles> 
      </ClaimsProvider>
    <!-- 
    </ClaimsProviders> -->
    

Carregar a sua política personalizada

  1. Entre no portal do Azure.
  2. Se você tiver acesso a vários locatários, selecione o ícone Configurações no menu superior para alternar para o seu locatário do Azure Active Directory B2C no menu Diretórios + assinaturas.
  3. Escolha Todos os serviços no canto superior esquerdo do portal do Azure e pesquise e selecione Registros de aplicativo.
  4. Selecione Estrutura de Experiência de Identidade.
  5. Selecione Carregar Política Personalizada e carregue os arquivos de política TrustFrameworkExtensions.xml que você alterou.

Observação

Na primeira vez que o perfil técnico do Microsoft Entra ID persiste a declaração para o diretório, ele verifica se o atributo personalizado existe. Caso contrário, ele criará o atributo personalizado.

Criar um atributo personalizado por meio portal do Azure

Os mesmos atributos de extensão são compartilhados entre políticas internas e personalizadas. Quando você adiciona atributos personalizados por meio da experiência do portal, esses atributos são registrados usando o b2c-extensions-app que existe em cada locatário B2C.

Você pode criar esses atributos usando a interface do usuário do portal antes ou depois de usá-los nas suas políticas personalizadas. Quando você cria um atributo loyaltyId no portal, é necessário fazer referência a ele da seguinte maneira:

Nome Usado em
extension_loyaltyId Política personalizada
extension_<b2c-extensions-app-guid>_loyaltyId API do Microsoft Graph

Observação

Ao usar um atributo personalizado em políticas personalizadas, você precisa prefixar a ID do tipo de declaração com extension_ para permitir que o mapeamento de dados correto ocorra no diretório do Azure AD B2C.

O exemplo a seguir demonstra o uso de atributos personalizados em uma definição de declaração de política personalizada do Azure AD B2C.

<BuildingBlocks>
  <ClaimsSchema>
    <ClaimType Id="extension_loyaltyId">
      <DisplayName>Loyalty Identification</DisplayName>
      <DataType>string</DataType>
      <UserHelpText>Your loyalty number from your membership card</UserHelpText>
      <UserInputType>TextBox</UserInputType>
    </ClaimType>
  </ClaimsSchema>
</BuildingBlocks>

O exemplo a seguir demonstra o uso de um atributo personalizado na política personalizada do Azure AD B2C em um perfil técnico, entrada, saída e declarações persistidas.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="extension_loyaltyId"  />
</InputClaims>
<PersistedClaims>
  <PersistedClaim ClaimTypeReferenceId="extension_loyaltyId" />
</PersistedClaims>
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
</OutputClaims>

Gerenciar atributos de extensão por meio do Microsoft Graph

Você pode usar o Microsoft Graph para criar e gerenciar atributos personalizados e, em seguida, definir os valores para um usuário. Os atributos de extensão também são chamados de diretório ou extensões do Microsoft Entra.

Os atributos personalizados (extensões de diretório) na API do Microsoft Graph são nomeados usando a convenção extension_{appId-without-hyphens}_{extensionProperty-name} em que {appId-without-hyphens} é a versão destituída de appId (chamada ID do cliente no portal Azure AD B2C) para b2c-extensions-app com apenas caracteres de 0 a 9 e de A a Z. Por exemplo, se a appID do aplicativo b2c-extensions-app for 25883231-668a-43a7-80b2-5685c3f874bc, e o nome do atributo for loyaltyId, o atributo personalizado será nomeado como extension_25883231668a43a780b25685c3f874bc_loyaltyId.

Saiba como gerenciar atributos de extensão em seu locatário do Azure AD B2C usando a API do Microsoft Graph.

Remover atributos de extensão

Ao contrário dos atributos internos, os atributos personalizados podem ser removidos. Os valores dos atributos de extensão também podem ser removidos.

Importante

Antes de remover o atributo personalizado, defina o valor do atributo de extensão como null para cada conta no diretório. Assim, você remove explicitamente os valores do atributo de extensão. Em seguida, continue a remover o próprio atributo de extensão. Atributos personalizados podem ser consultados usando a API do Microsoft Graph.

Use as etapas a seguir para remover um atributo personalizado de um fluxo de usuário em seu locatário:

  1. Entre no portal do Azure como administrador global do locatário Azure AD B2C.
  2. Verifique se você está usando o diretório que contenha seu locatário do Azure AD B2C:
    1. Selecione o ícone Diretórios + assinaturas na barra de ferramentas do portal.
    2. Na página Configurações do portal | Diretórios + assinaturas, encontre o diretório Azure AD B2C na lista Nome do diretório e selecione Alternar
  3. Escolha Todos os serviços no canto superior esquerdo do portal do Azure, procure e selecione Azure AD B2C.
  4. Selecione Atributos de inscrição e, em seguida, selecione o atributo que você deseja excluir.
  5. Selecione Excluir e, em seguida, selecione Sim para confirmar.

Use a API do Microsoft Graph para gerenciar os atributos personalizados.

Próximas etapas

Saiba como adicionar declarações e personalizar a entrada de usuário usando políticas personalizadas. Este exemplo usa uma declaração interna 'city'. Para usar um atributo personalizado, substitua 'city' pelos seus atributos personalizados.