Ponto de extremidade UserInfo

Artigo
10/30/2024

Antes de começar, use o seletor Escolher um tipo de política na parte superior desta página 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.

O ponto de extremidade UserInfo faz parte da especificação do OIDC (OpenID Connect Standard) e foi projetado para retornar declarações sobre o usuário autenticado. O ponto de extremidade UserInfo é definido na política de terceira parte confiável usando o elemento EndPoint.

Esse recurso só está disponível para políticas personalizadas. Para obter as etapas de instalação, escolha Política personalizada no seletor anterior.

Pré-requisitos

Conclua as etapas em Introdução às políticas personalizadas no Active Directory B2C. Este tutorial orienta como atualizar arquivos de política personalizados para usar a configuração de locatário do Azure AD B2C.
Se você não registrou um aplicativo Web, registre um usando as etapas em Registrar um aplicativo Web.

Visão geral do ponto de extremidade UserInfo

As informações de usuário UserJourney especificam:

Autorização: o ponto de extremidade UserInfo é protegido com um token de portador. Um token de acesso emitido é apresentado no cabeçalho de autorização para o ponto de extremidade UserInfo. A política especifica o perfil técnico que valida o token de entrada e extrai declarações, como a objectId do usuário. A objectId do usuário é usada para recuperar as declarações a serem retornadas na resposta do percurso do ponto de extremidade UserInfo.
Etapas de orquestração:
- Uma etapa de orquestração é usada para coletar informações sobre o usuário. Com base nas declarações dentro do token de acesso de entrada, o percurso do usuário invoca um perfil técnico do Microsoft Entra ID para recuperar dados sobre o usuário, por exemplo, lendo o usuário pela objectId.
- Etapas de orquestração opcionais – Você pode adicionar mais etapas de orquestração, como um perfil técnico da API REST, para recuperar mais informações sobre o usuário.
- Emissor de UserInfo – especifica a lista de declarações que o ponto de extremidade UserInfo retorna.

Criar um ponto de extremidade UserInfo

1. Adicione o perfil técnico do emissor do token

Abra o arquivo TrustFrameworkExtensions.xml.
Se ele ainda não existir, adicione ClaimsProvider e seus elementos filho como o primeiro elemento sob o elemento BuildingBlocks.

Adicione o seguinte provedor de declarações:

<!-- 
<ClaimsProviders> -->
  <ClaimsProvider>
    <DisplayName>Token Issuer</DisplayName>
    <TechnicalProfiles>
      <TechnicalProfile Id="UserInfoIssuer">
        <DisplayName>JSON Issuer</DisplayName>
        <Protocol Name="None" />
        <OutputTokenFormat>JSON</OutputTokenFormat>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <!-- The Below claims are what will be returned on the UserInfo Endpoint if in the Claims Bag-->
        <InputClaims>
          <InputClaim ClaimTypeReferenceId="objectId"/>
          <InputClaim ClaimTypeReferenceId="givenName"/>
          <InputClaim ClaimTypeReferenceId="surname"/>
          <InputClaim ClaimTypeReferenceId="displayName"/>
          <InputClaim ClaimTypeReferenceId="signInNames.emailAddress"/>
        </InputClaims>
      </TechnicalProfile>
      <TechnicalProfile Id="UserInfoAuthorization">
        <DisplayName>UserInfo authorization</DisplayName>
        <Protocol Name="None" />
        <InputTokenFormat>JWT</InputTokenFormat>
        <Metadata>
          <!-- Update the Issuer and Audience below -->
          <!-- Audience is optional, Issuer is required-->
          <Item Key="issuer">https://yourtenant.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/</Item>
          <Item Key="audience">[ "00001111-aaaa-2222-bbbb-3333cccc4444", "11112222-bbbb-3333-cccc-4444dddd5555" ]</Item>
          <Item Key="client_assertion_type">urn:ietf:params:oauth:client-assertion-type:jwt-bearer</Item>
        </Metadata>
        <CryptographicKeys>
          <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
        </CryptographicKeys>
        <OutputClaims>
          <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
          <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email"/>
          <!-- Optional claims to read from the access token. -->
          <!-- <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="given_name"/>
             <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="family_name"/>
             <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name"/> -->
        </OutputClaims>
      </TechnicalProfile>
    </TechnicalProfiles>
  </ClaimsProvider>
<!-- 
</ClaimsProviders> -->

A seção InputClaims no perfil técnico UserInfoIssuer especifica os atributos que você deseja retornar. O perfil técnico UserInfoIssuer é chamado no final do percurso do usuário.
O perfil técnico UserInfoAuthorization valida a assinatura, o nome do emissor e o público do token e extrai a declaração do token de entrada. Altere os seguintes metadados para refletir seu ambiente:
1. emissor – esse valor deve ser idêntico à declaração iss dentro da declaração do token de acesso. Tokens emitidos pelo Azure AD B2C usam um emissor no formato https://yourtenant.b2clogin.com/your-tenant-id/v2.0/. Saiba mais sobre a personalização de tokens.
2. IdTokenAudience – deve ser idêntico à declaração aud dentro da declaração de token de acesso. No Azure AD B2C, a declaração aud é a ID do seu aplicativo de terceira parte confiável. Esse valor é uma coleção e dá suporte a vários valores usando um delimitador de vírgula.
  
  No token de acesso a seguir, o valor da declaração iss é https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/. O valor da declaração aud é 00001111-aaaa-2222-bbbb-3333cccc4444.
```
{
  "exp": 1605549468,
  "nbf": 1605545868,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/",
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1605545868,
  "auth_time": 1605545868,
  "name": "John Smith",
  "given_name": "John",
  "family_name": "Smith",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
```
O elemento OutputClaims do perfil técnico UserInfoAuthorization especifica os atributos que você deseja ler do token de acesso. ClaimTypeReferenceId é a referência a um tipo de declaração. O PartnerClaimType opcional é o nome da declaração definida no token de acesso.

2. Adicione o elemento UserJourney

O elemento UserJourney define o caminho usado pelo usuário ao interagir com seu aplicativo. Adicione o elemento UserJourneys se ele não existir com o UserJourney identificado como UserInfoJourney:

<!-- 
<UserJourneys> -->
  <UserJourney Id="UserInfoJourney" DefaultCpimIssuerTechnicalProfileReferenceId="UserInfoIssuer">
    <Authorization>
      <AuthorizationTechnicalProfiles>
        <AuthorizationTechnicalProfile ReferenceId="UserInfoAuthorization" />
      </AuthorizationTechnicalProfiles>
    </Authorization>
    <OrchestrationSteps >
      <OrchestrationStep Order="1" Type="ClaimsExchange">
        <Preconditions>
          <Precondition Type="ClaimsExist" ExecuteActionsIf="false">
            <Value>objectId</Value>
            <Action>SkipThisOrchestrationStep</Action>
          </Precondition>
        </Preconditions>
        <ClaimsExchanges UserIdentity="false">
          <ClaimsExchange Id="AADUserReadWithObjectId" TechnicalProfileReferenceId="AAD-UserReadUsingObjectId" />
        </ClaimsExchanges>
      </OrchestrationStep>
      <OrchestrationStep Order="2" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="UserInfoIssuer" />
    </OrchestrationSteps>
  </UserJourney>
<!-- 
</UserJourneys> -->

3. Inclua o ponto de extremidade na política de terceira parte confiável

Para incluir o ponto de extremidade UserInfo no aplicativo de terceira parte confiável, adicione um elemento EndPoint ao arquivo SocialAndLocalAccounts/SignUpOrSignIn.xml.

<!--
<RelyingParty> -->
  <Endpoints>
    <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
  </Endpoints>
<!-- 
</RelyingParty> -->

O elemento de terceira parte confiável concluído será o seguinte:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TrustFrameworkPolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns="http://schemas.microsoft.com/online/cpim/schemas/2013/06" PolicySchemaVersion="0.3.0.0" TenantId="yourtenant.onmicrosoft.com" PolicyId="B2C_1A_signup_signin" PublicPolicyUri="http://yourtenant.onmicrosoft.com/B2C_1A_signup_signin">
  <BasePolicy>
    <TenantId>yourtenant.onmicrosoft.com</TenantId>
    <PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>
  </BasePolicy>
  <RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <Endpoints>
      <Endpoint Id="UserInfo" UserJourneyReferenceId="UserInfoJourney" />
    </Endpoints>
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="OpenIdConnect" />
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
        <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>
</TrustFrameworkPolicy>

4. Carregue os arquivos

Entre no portal do Azure.
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.
Escolha Todos os serviços no canto superior esquerdo do Portal do Azure, pesquise Azure AD B2C e selecione-o.
Selecione Estrutura de Experiência de Identidade.
Na página Políticas personalizadas, escolha Carregar política personalizada.
Selecione Substituir a política personalizada se ela existir, depois procure o arquivo TrustFframeworkExtensions.xml e selecione-o.
Clique em Carregar.
Repita as etapas 5 a 7 para o arquivo de terceira parte confiável, como SignUpOrSignIn.xml.

Chamar o ponto de extremidade UserInfo

O ponto de extremidade UserInfo usa a API de token de portador OAuth2 padrão, chamada ao usar o token de acesso recebido ao obter um token para seu aplicativo. Ele retorna uma resposta JSON que contém declarações sobre o usuário. O ponto de extremidade UserInfo é hospedado no Azure AD B2C em:

https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/openid/v2.0/userinfo

O ponto de extremidade de configuração /.well-known (documento de descoberta do OpenID Connect) lista o campo userinfo_endpoint. Você pode descobrir programaticamente o ponto de extremidade UserInfo usando o ponto de extremidade de configuração /.well-known em:

https://yourtenant.b2clogin.com/yourtenant.onmicrosoft.com/policy-name/v2.0/.well-known/openid-configuration

Testar a política

Em Políticas personalizadas, selecione a política com a qual você integrou o ponto de extremidade UserInfo. Por exemplo, B2C_1A_SignUpOrSignIn.
Selecione Executar Agora.
Em Selecionar aplicativo, selecione o aplicativo que você registrou anteriormente. Para Selecionar URL de resposta, escolha https://jwt.ms. Para saber mais, confira Registrar um aplicativo Web no Azure Active Directory B2C.
Inscreva-se ou entre com um endereço de email ou uma conta social.
Copie o id_token em seu formato codificado do site https://jwt.ms. Você pode usar isso para enviar uma solicitação GET para o ponto de extremidade UserInfo e recuperar as informações do usuário.
Envie uma solicitação GET para o ponto de extremidade UserInfo e recupere as informações do usuário.

GET /yourtenant.onmicrosoft.com/b2c_1a_signup_signin/openid/v2.0/userinfo
Host: b2cninja.b2clogin.com
Authorization: Bearer <your access token>

Uma resposta bem-sucedida teria a seguinte aparência:

{
    "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "givenName": "John",
    "surname": "Smith",
    "displayName": "John Smith",
    "signInNames.emailAddress": "john.s@contoso.com"
}

Fornecer declarações opcionais

Para fornecer mais declarações ao seu aplicativo, siga estas etapas:

Adicione atributos de usuário e personalize a entrada do usuário.
Modifique o elemento OutputClaims do Perfil técnico da política da terceira parte confiável com as declarações que você deseja fornecer. Use o atributo DefaultValue para definir um valor padrão. Você também pode definir o valor padrão para um resolvedor de declaração, como o {Context:CorrelationId}. Para forçar o uso do valor padrão, defina o atributo AlwaysUseDefaultValue como true. O exemplo a seguir adiciona a declaração de cidade com um valor padrão.
```
<RelyingParty>
  ...
  <TechnicalProfile Id="PolicyProfile">
    ...
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="city" DefaultValue="Berlin" />
    </OutputClaims>
    ...
  </TechnicalProfile>
</RelyingParty>
```

Modifique o elemento InputClaims do perfil técnico UserInfoIssuer com as declarações que você deseja fornecer. Use o atributo PartnerClaimType para alterar o nome de retorno da declaração para seu aplicativo. O exemplo a seguir adiciona a declaração de cidade e altera o nome de algumas das declarações.

<TechnicalProfile Id="UserInfoIssuer">
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" />
    <InputClaim ClaimTypeReferenceId="city" />
    <InputClaim ClaimTypeReferenceId="givenName" />
    <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="familyName" />
    <InputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
    <InputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
  </InputClaims>
  ...
</TechnicalProfile>

Próximas etapas

Encontre um exemplo de política de ponto de extremidade UserInfo no GitHub.

Compartilhar via