Endpoint UserInfo

Articolo
01/11/2024

Prima di iniziare, usare il selettore Scegli un tipo di criterio nella parte superiore di questa pagina per scegliere il tipo di criterio che si sta configurando. Azure Active Directory B2C offre due metodi per definire il modo in cui gli utenti interagiscono con le applicazioni: tramite flussi utente predefiniti o tramite criteri personalizzati completamente configurabili. I passaggi necessari in questo articolo sono diversi per ogni metodo.

L'endpoint UserInfo fa parte della specifica OpenID Connessione standard (OIDC) ed è progettato per restituire attestazioni relative all'utente autenticato. L'endpoint UserInfo viene definito nei criteri della relying party usando l'elemento EndPoint .

Questa funzionalità è disponibile solo per i criteri personalizzati. Per i passaggi di installazione, selezionare Criteri personalizzati nel selettore precedente.

Prerequisiti

Completare le procedure illustrate in Introduzione ai criteri personalizzati in Azure Active Directory B2C. Questa esercitazione illustra come aggiornare i file di criteri personalizzati per usare la configurazione del tenant di Azure AD B2C.
Se non è stata registrata un'app Web, registrare una usando la procedura descritta in Registrare un'applicazione Web.

Panoramica dell'endpoint UserInfo

Le informazioni utente UserJourney specificano:

Autorizzazione: l'endpoint UserInfo è protetto con un token di connessione. Un token di accesso rilasciato viene presentato nell'intestazione di autorizzazione all'endpoint UserInfo. Il criterio specifica il profilo tecnico che convalida il token in ingresso ed estrae attestazioni, ad esempio objectId dell'utente. L'objectId dell'utente viene usato per recuperare le attestazioni da restituire nella risposta del percorso dell'endpoint UserInfo.
Passaggio di orchestrazione:
- Viene usato un passaggio di orchestrazione per raccogliere informazioni sull'utente. In base alle attestazioni all'interno del token di accesso in ingresso, il percorso utente richiama un profilo tecnico microsoft Entra ID per recuperare i dati relativi all'utente, ad esempio leggendo l'utente in base all'objectId.
- Passaggi di orchestrazione facoltativi: è possibile aggiungere altri passaggi di orchestrazione, ad esempio un profilo tecnico dell'API REST per recuperare altre informazioni sull'utente.
- Autorità di certificazione UserInfo: specifica l'elenco di attestazioni restituite dall'endpoint UserInfo.

Creare un endpoint UserInfo

1. Aggiungere il profilo tecnico dell'autorità di certificazione token

Aprire il file TrustFrameworkExtensions.xml.
Se non esiste già, aggiungere un elemento ClaimsProvider e i relativi elementi figlio come primo elemento nell'elemento BuildingBlocks.

Aggiungere il provider di attestazioni seguente:

<!-- 
<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/11111111-1111-1111-1111-111111111111/v2.0/</Item>
          <Item Key="audience">[ "22222222-2222-2222-2222-222222222222", "33333333-3333-3333-3333-333333333333" ]</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> -->

La sezione InputClaims all'interno del profilo tecnico UserInfoIssuer specifica gli attributi da restituire. Il profilo tecnico UserInfoIssuer viene chiamato alla fine del percorso utente.
Il profilo tecnico UserInfoAuthorization convalida la firma, il nome dell'autorità emittente e il gruppo di destinatari del token ed estrae l'attestazione dal token in ingresso. Modificare i metadati seguenti per riflettere l'ambiente:
1. issuer : questo valore deve essere identico all'attestazione iss all'interno dell'attestazione del token di accesso. I token emessi da Azure AD B2C usano un'autorità emittente nel formato https://yourtenant.b2clogin.com/your-tenant-id/v2.0/. Altre informazioni sulla personalizzazione dei token.
2. IdTokenAudience : deve essere identico all'attestazione aud all'interno dell'attestazione del token di accesso. In Azure AD B2C l'attestazione aud è l'ID dell'applicazione relying party. Questo valore è una raccolta e supporta più valori usando un delimitatore da virgole.
  
  Nel token di accesso seguente il valore dell'attestazione iss è https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/. Il valore dell'attestazione aud è 22222222-2222-2222-2222-222222222222.
```
{
  "exp": 1605549468,
  "nbf": 1605545868,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/11111111-1111-1111-1111-111111111111/v2.0/",
  "sub": "44444444-4444-4444-4444-444444444444",
  "aud": "22222222-2222-2222-2222-222222222222",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1605545868,
  "auth_time": 1605545868,
  "name": "John Smith",
  "given_name": "John",
  "family_name": "Smith",
  "tid": "11111111-1111-1111-1111-111111111111"
}
```
L'elemento OutputClaims del profilo tecnico UserInfoAuthorization specifica gli attributi da leggere dal token di accesso. ClaimTypeReferenceId è il riferimento a un tipo di attestazione. PartnerClaimType facoltativo è il nome dell'attestazione definita nel token di accesso.

2. Aggiungere l'elemento UserJourney

L'elemento UserJourney definisce il percorso dell'utente durante l'interazione con l'applicazione. Aggiungere l'elemento UserJourneys, se non esiste, con UserJourney identificato come 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. Includere l'endpoint nei criteri della relying party

Per includere l'endpoint UserInfo nell'applicazione relying party, aggiungere un elemento Endpoint al file SocialAndLocalAccounts/SignUpOrSignIn.xml .

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

L'elemento relying party completato sarà il seguente:

<?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. Caricare i file

Accedere al portale di Azure.
Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant di Azure AD B2C dal menu Directory e sottoscrizioni.
Scegliere Tutti i servizi nell'angolo in alto a sinistra nel portale di Azure e quindi cercare e selezionare Azure AD B2C.
Fare clic su Framework dell'esperienza di gestione delle identità.
Nella pagina Criteri personalizzati selezionare Carica i criteri personalizzati.
Selezionare Sovrascrivi i criteri personalizzati, se già esistente, quindi cercare e selezionare il file TrustframeworkExtensions.xml .
Fare clic su Carica.
Ripetere i passaggi da 5 a 7 per il file relying party, ad esempio SignUpOrSignIn.xml.

Chiamata dell'endpoint UserInfo

L'endpoint UserInfo usa l'API token bearer OAuth2 standard, chiamata usando il token di accesso ricevuto quando si ottiene un token per l'applicazione. Restituisce una risposta JSON contenente attestazioni relative all'utente. L'endpoint UserInfo è ospitato in Azure AD B2C all'indirizzo:

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

Il documento di configurazione di /.well-known configure (OpenID Connessione discovery document) elenca il userinfo_endpoint campo . È possibile individuare l'endpoint UserInfo a livello di codice usando l'endpoint di configurazione /.well-known in:

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

Testare il criterio

In Criteri personalizzati selezionare i criteri con cui si è integrato l'endpoint UserInfo. Ad esempio, B2C_1A_SignUpOrSignIn.
Selezionare Esegui ora.
In Seleziona applicazione selezionare l'applicazione registrata in precedenza. Per Selezionare l'URL di risposta scegliere https://jwt.ms. Per altre informazioni, vedere Registrare un'applicazione Web in Azure Active Directory B2C.
Iscriversi o accedere con un indirizzo di posta elettronica o un account di social networking.
Copiare il id_token nel formato codificato dal https://jwt.ms sito Web. È possibile usarlo per inviare una richiesta GET all'endpoint UserInfo e recuperare le informazioni utente.
Inviare una richiesta GET all'endpoint UserInfo e recuperare le informazioni utente.

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

Una risposta con esito positivo sarà simile alla seguente:

{
    "objectId": "44444444-4444-4444-4444-444444444444",
    "givenName": "John",
    "surname": "Smith",
    "displayName": "John Smith",
    "signInNames.emailAddress": "john.s@contoso.com"
}

Fornire attestazioni facoltative

Per fornire più attestazioni all'app, seguire questa procedura:

Aggiungere attributi utente e personalizzare l'input dell'utente.
Modificare l'elemento OutputClaims del profilo tecnico dei criteri relying party con le attestazioni da fornire. Usare l'attributo DefaultValue per impostare un valore predefinito. È anche possibile impostare il valore predefinito su un resolver di attestazioni, ad esempio {Context:CorrelationId}. Per forzare l'uso del valore predefinito, impostare l'attributo AlwaysUseDefaultValue su true. Nell'esempio seguente viene aggiunta l'attestazione city con un valore predefinito.
```
<RelyingParty>
  ...
  <TechnicalProfile Id="PolicyProfile">
    ...
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="city" DefaultValue="Berlin" />
    </OutputClaims>
    ...
  </TechnicalProfile>
</RelyingParty>
```

Modificare l'elemento InputClaims del profilo tecnico UserInfoIssuer con le attestazioni da fornire. Usare l'attributo PartnerClaimType per modificare il nome dell'attestazione restituita all'app. Nell'esempio seguente viene aggiunta l'attestazione city e viene modificato il nome di alcune attestazioni.

<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>

Passaggi successivi

È possibile trovare un esempio di criteri di endpoint UserInfo in GitHub.

Share via