Arricchire i token con attestazioni da origini esterne usando connettori API

Articolo
11/08/2023

Prima di iniziare, usare il selettore Scegli un tipo di criterio 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.

Azure Active Directory B2C (Azure AD B2C) consente agli sviluppatori di identità di integrare un'interazione con un'API RESTful nel flusso utente usando i connettori API. Consente agli sviluppatori di recuperare in modo dinamico i dati da origini di identità esterne. Al termine di questa procedura dettagliata, sarà possibile creare un flusso utente di Azure AD B2C che interagisce con le API per arricchire i token con informazioni provenienti da origini esterne.

È possibile usare i connettori API applicati al passaggio Prima di inviare il token (anteprima) per arricchire i token per le applicazioni con informazioni provenienti da origini esterne. Quando un utente accede o effettua l'iscrizione, Azure AD B2C chiamerà l'endpoint API configurato nel connettore API, che può eseguire query su un utente in servizi downstream, ad esempio servizi cloud, archivi utente personalizzati, sistemi di autorizzazione personalizzati, sistemi di identità legacy e altro ancora.

Nota

Questa funzionalità è disponibile in anteprima pubblica.

È possibile creare un endpoint API usando uno degli esempi.

Prerequisiti

Creare un flusso utente in modo che gli utenti possano iscriversi e accedere all'applicazione.
Registrare un'applicazione Web.

Completare i passaggi descritti in Introduzione ai criteri personalizzati in Active Directory B2C
Registrare un'applicazione Web.

Endpoint API. È possibile creare un endpoint API usando uno degli esempi.

Creare un connettore API

Per usare un connettore API, creare prima il connettore API e quindi abilitarlo in un flusso utente.

Accedi al portale di Azure.
In Servizi di Azure selezionare Azure AD B2C.
Selezionare Connettori API e quindi Nuovo connettore API.
Specificare un nome visualizzato per la chiamata. Ad esempio, arricchire il token dall'origine esterna.
Specificare l'URL dell'endpoint per la chiamata API.
Scegliere il tipo di autenticazione e configurare le informazioni di autenticazione per chiamare l'API. Informazioni su come proteggere il Connessione or dell'API.
Seleziona Salva.

Abilitare il connettore API in un flusso utente

Seguire questa procedura per aggiungere un connettore API a un flusso utente di iscrizione.

Accedi al portale di Azure.
In Servizi di Azure selezionare Azure AD B2C.
Selezionare Flussi utente e quindi selezionare il flusso utente a cui si vuole aggiungere il connettore API.
Selezionare Connettori API e quindi selezionare l'endpoint API che si vuole richiamare nel passaggio Prima di inviare il token (anteprima) nel flusso utente:
Seleziona Salva.

Questo passaggio esiste solo per i flussi utente di iscrizione e accesso (scelta consigliata), iscrizione (scelta consigliata) e accesso (scelta consigliata).

Richiesta di esempio inviata all'API in questo passaggio

Un connettore API in questo passaggio viene richiamato quando un token sta per essere rilasciato durante l'accesso e l'iscrizione. Un connettore API si materializza come richiesta HTTP POST , inviando attributi utente ('claims') come coppie chiave-valore in un corpo JSON. Gli attributi vengono serializzati in modo analogo alle proprietà utente di Microsoft Graph .

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

Le attestazioni inviate all'API dipendono dalle informazioni definite per l'utente. Nella richiesta sono disponibili solo le proprietà utente e gli attributi personalizzati elencati nell'esperienza Attributi utente di Azure AD B2C>. Gli attributi personalizzati esistono nel formato extension_<extensions-app-id>_CustomAttribute nella directory. L'API dovrebbe aspettarsi di ricevere attestazioni nello stesso formato serializzato. Per altre informazioni sugli attributi personalizzati, vedere Definire attributi personalizzati in Azure AD B2C. Inoltre, queste attestazioni vengono in genere inviate in tutte le richieste per questo passaggio:

Impostazioni locali dell'interfaccia utente ('ui_locales'): impostazioni locali dell'utente finale configurate nel dispositivo. Questa operazione può essere usata dall'API per restituire risposte internazionalizzate.
Passaggio ('passaggio'): passaggio o punto nel flusso utente per cui è stato richiamato il connettore API. Il valore per questo passaggio è '
ID client ('client_id'): appId valore dell'applicazione a cui un utente finale esegue l'autenticazione in un flusso utente. Non si tratta dell'applicazione di risorse nei token di appId accesso.
objectId : identificatore dell'utente. È possibile usarlo per eseguire query sui servizi downstream per informazioni sull'utente.

Importante

Se un'attestazione non ha un valore al momento della chiamata dell'endpoint API, l'attestazione non verrà inviata all'API. L'API deve essere progettata per controllare e gestire in modo esplicito il caso in cui un'attestazione non si trova nella richiesta.

Tipi di risposta previsti dall'API Web in questo passaggio

Quando l'API Web riceve una richiesta HTTP da Microsoft Entra ID durante un flusso utente, può restituire una "risposta di continuazione".

Risposta di continuazione

Una risposta di continuazione indica che il flusso utente deve continuare con il passaggio successivo: emettere il token. In una risposta di continuazione, l'API può restituire attestazioni aggiuntive. Un'attestazione restituita dall'API che si desidera restituire nel token deve essere un'attestazione predefinita o definita come attributo personalizzato e deve essere selezionata nella configurazione delle attestazioni dell'applicazione del flusso utente. Il valore dell'attestazione nel token sarà quello restituito dall'API, non dal valore nella directory. Alcuni valori di attestazione non possono essere sovrascritti dalla risposta dell'API. Le attestazioni che possono essere restituite dall'API corrispondono al set trovato in Attributi utente, ad eccezione di email.

Nota

L'API viene richiamata solo durante un'autenticazione iniziale. Quando si usano i token di aggiornamento per ottenere automaticamente nuovi token di accesso o ID, il token includerà i valori valutati durante l'autenticazione iniziale.

Esempio di risposta

Esempio di risposta di continuazione

HTTP/1.1 200 OK
Content-type: application/json
{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parametro	Type	Richiesto	Descrizione
version	Stringa	Sì	Versione dell'API.
action	Stringa	Sì	Il valore deve essere `Continue`.
<builtInUserAttribute>	<tipo di attributo>	No	Possono essere restituiti nel token se selezionato come attestazione dell'applicazione.
<extension_{extensions-app-id}_CustomAttribute>	<tipo di attributo>	No	L'attestazione non deve contenere `_<extensions-app-id>_`, è facoltativa. Possono essere restituiti nel token se selezionato come attestazione dell'applicazione.

In questo scenario i dati del token dell'utente vengono arricchiti mediante l'integrazione con un flusso di lavoro line-of-business aziendale. Durante l'iscrizione o l'accesso con un account locale o federato, Azure AD B2C richiama un'API REST per ottenere i dati del profilo esteso dell'utente da un'origine dati remota. In questo esempio Azure AD B2C invia l'identificatore univoco dell'utente, ovvero objectId. L'API REST restituisce quindi il saldo dell'account utente (un numero casuale). Usare questo esempio come punto iniziale per l'integrazione con il sistema CRM, il database di marketing o qualsiasi flusso di lavoro line-of-business. È anche possibile progettare l'interazione come un profilo tecnico di convalida. Questa situazione è idonea quando l'API REST convalida i dati sullo schermo e restituisce attestazioni. Per altre informazioni, vedere Procedura dettagliata: Aggiungere un connettore API a un flusso utente di iscrizione.

Prerequisiti

Completare la procedura descritta in Introduzione ai criteri personalizzati. È necessario disporre di un criterio personalizzato di lavoro per l'iscrizione e l'accesso con account locali.
Informazioni su come integrare scambi di attestazioni API REST nei criteri personalizzati di Azure AD B2C.

Preparare un endpoint dell'API REST

Per questa procedura dettagliata è necessario disporre di un'API REST per verificare che l'objectId Azure AD B2C di un utente sia registrato nel sistema back-end. Se registrata, l'API REST restituisce il saldo dell'account utente. In caso contrario, l'API REST registra il nuovo account nella directory e restituisce il saldo iniziale 50.00. Il codice JSON seguente illustra i dati che Azure AD B2C invierà all'endpoint dell'API REST.

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

Quando l'API REST convalida i dati, deve restituire un codice HTTP 200 (Ok) con i dati JSON seguenti:

{
    "balance": "760.50"
}

La configurazione dell'endpoint dell'API REST non rientra nell'ambito di questo articolo. È stata creato un esempio di Funzioni di Azure. È possibile accedere al codice completo della funzione di Azure in GitHub.

Definire attestazioni

Un'attestazione fornisce un'archiviazione temporanea dei dati durante l'esecuzione dei criteri di Azure AD B2C. È possibile dichiarare attestazioni nella sezione ClaimsSchema.

Aprire il file delle estensioni del criterio, Ad esempio, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Cercare l'elemento BuildingBlocks. Se l'elemento non esiste, aggiungerlo.
Individuare l'elemento ClaimsSchema. Se l'elemento non esiste, aggiungerlo.
Aggiungere le attestazioni seguenti all'elemento ClaimsSchema.

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Aggiungere il profilo tecnico dell'API RESTful

Un profilo tecnico RESTful fornisce supporto per l'interazione con il servizio RESTful. Azure AD B2C invia dati al servizio RESTful in una raccolta InputClaims e riceve dati in una raccolta OutputClaims. Trovare l'elemento ClaimsProviders nel file TrustFrameworkExtensions.xml e aggiungere un nuovo provider di attestazioni come indicato di seguito:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

In questo esempio userLanguage viene inviato al servizio REST come lang nel payload JSON. Il valore dell'attestazione userLanguage contiene l'ID della lingua utente corrente. Per altre informazioni, vedere i resolver di attestazioni.

Configurare il profilo tecnico dell'API RESTful

Dopo aver distribuito l'API REST, impostare i metadati del profilo tecnico in modo da riflettere la REST-GetProfile propria API REST, tra cui:

ServiceUrl. Impostare l'URL dell'endpoint DELL'API REST.
SendClaimsIn. Specificare la modalità di invio delle attestazioni di input al provider di attestazioni RESTful.
AuthenticationType. Impostare il tipo di autenticazione eseguito dal provider di attestazioni RESTful, ad Basic esempio o ClientCertificate
AllowInsecureAuthInProduction. In un ambiente di produzione assicurarsi di impostare questi metadati su false.

Per altre configurazioni, vedere i metadati del profilo tecnico RESTful. I commenti precedenti AuthenticationType e AllowInsecureAuthInProduction specificano le modifiche che è necessario apportare quando si passa a un ambiente di produzione. Per informazioni su come proteggere le API RESTful per la produzione, vedere Proteggere l'API RESTful.

Per aggiungere un passaggio di orchestrazione

I percorsi utente specificano percorsi espliciti attraverso cui un criterio consente a un'applicazione relying party di ottenere le attestazioni desiderate per un utente. Un percorso utente è costituito da una sequenza di orchestrazione da seguire per garantire l'esito positivo di una transazione. È possibile aggiungere o sottrarre passaggi di orchestrazione. In questo caso, viene aggiunto un nuovo passaggio di orchestrazione usato per ampliare le informazioni fornite all'applicazione dopo l'iscrizione o l'accesso dell'utente tramite la chiamata all'API REST.

Aprire il file di base dei criteri, Ad esempio, SocialAndLocalAccounts/TrustFrameworkBase.xml.
Cercare l'elemento <UserJourneys>. Copiare l'intero elemento, quindi eliminarlo.
Aprire il file delle estensioni del criterio, Ad esempio, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Incollare <UserJourneys> nel file delle estensioni, dopo la chiusura dell'elemento <ClaimsProviders>.

Individuare <UserJourney Id="SignUpOrSignIn"> e aggiungere il passaggio di orchestrazione seguente prima dell'ultimo.

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>

Effettuare il refactoring dell'ultimo passaggio di orchestrazione modificando Order in 8. I due passaggi di orchestrazione finali dovrebbero essere simili ai seguenti:

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
<OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />

Ripetere gli ultimi due passaggi per i percorsi utente ProfileEdit e PasswordReset.

Includere un'attestazione nel token

Per restituire l'attestazione balance all'applicazione relying party, aggiungere un'attestazione di output al file SocialAndLocalAccounts/SignUpOrSignIn.xml. Se si aggiunge un'attestazione di output, l'attestazione viene rilasciata nel token dopo un percorso utente con esito positivo e viene inviata all'applicazione. Modificare l'elemento profilo tecnico nella sezione relying party per aggiungere balance come attestazione di output.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <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="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Ripetere questo passaggio per i percorsi utente ProfileEdit.xml e PasswordReset.xml. Salvare i file modificati: TrustFrameworkBase.xml e TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml e PasswordReset.xml.

Testare i criteri personalizzati

Accedi 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 Registrazioni per l'app.
Fare clic su Framework dell'esperienza di gestione delle identità.
Selezionare Carica criteri personalizzati e quindi caricare i file di criteri modificati: TrustFrameworkBase.xml e TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml e PasswordReset.xml.
Selezionare il criterio di iscrizione o di accesso che è stato caricato e fare clic sul pulsante Esegui adesso.
Dovrebbe essere possibile iscriversi usando un indirizzo e-mail o un account Facebook.
Il token inviato all'applicazione include l'attestazione balance.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Le funzioni serverless, ad esempio i trigger HTTP in Funzioni di Azure, consentono di creare endpoint API da usare con il connettore API. La funzione cloud serverless può anche chiamare e richiamare altre API Web, archivi dati e altri servizi cloud per scenari complessi.

Procedure consigliate

Assicurarsi che:

L'API segue la richiesta API e i contratti di risposta, come descritto in precedenza.
L'URL dell'endpoint del connettore API punta all'endpoint API corretto.
L'API verifica in modo esplicito la presenza di valori Null delle attestazioni ricevute da cui dipende.
L'API implementa un metodo di autenticazione descritto in Proteggere il connettore API.
L'API risponde il più rapidamente possibile per garantire un'esperienza utente fluida.
- Azure AD B2C attenderà un massimo di 20 secondi per ricevere una risposta. Se non viene ricevuto alcuno, eseguirà un altro tentativo (riprovare) alla chiamata dell'API.
- Se si usa una funzione serverless o un servizio Web scalabile, usare un piano di hosting che mantiene l'API "attiva" o "calda" nell'ambiente di produzione. Per Funzioni di Azure, è consigliabile usare almeno il piano Premium nell'ambiente di produzione.
Garantire la disponibilità elevata dell'API.
Monitorare e ottimizzare le prestazioni delle API downstream, dei database o di altre dipendenze dell'API.

Importante

Gli endpoint devono essere conformi ai requisiti di sicurezza di Azure AD B2C. Le versioni precedenti di TLS e le crittografie sono deprecate. Per altre informazioni, vedere Requisiti di Azure AD B2C TLS e della suite di crittografia.

Usare la registrazione

Uso delle funzioni cloud serverless

Uso della registrazione

In generale, è utile usare gli strumenti di registrazione abilitati dal servizio API Web, ad esempio Application Insights, per monitorare l'API per individuare codici di errore imprevisti, eccezioni e prestazioni scarse.

Monitorare i codici di stato HTTP che non sono HTTP 200 o 400.
Un codice di stato HTTP 401 o 403 indica in genere che si è verificato un problema con l'autenticazione. Controllare il livello di autenticazione dell'API e la configurazione corrispondente nel connettore API.
Se necessario, usare livelli più aggressivi di registrazione ,ad esempio "traccia" o "debug".
Monitorare l'API per tempi di risposta lunghi. Azure AD B2C registra inoltre i metadati sulle transazioni API che si verificano durante l'autenticazione utente tramite un flusso utente. Per trovare questi elementi:

Passare ad Azure AD B2C
In Attività selezionare Log di controllo.
Filtrare la visualizzazione elenco: per Data, selezionare l'intervallo di tempo desiderato e selezionare Un'API chiamata come parte di un flusso utente.
Esaminare i singoli log. Ogni riga rappresenta un connettore API che tenta di essere chiamato durante un flusso utente. Se una chiamata API ha esito negativo e si verifica un nuovo tentativo, viene comunque rappresentata come una singola riga. numberOfAttempts Indica il numero di chiamate dell'API. Questo valore può essere 1 o 2. Altre informazioni sulla chiamata API sono descritte in dettaglio nei log.

Passaggi successivi

Introduzione agli esempi.
Proteggere il Connessione or dell'API

Vedere gli articoli seguenti per informazioni su come proteggere le API:

Condividi tramite

Arricchire i token con attestazioni da origini esterne usando connettori API

Prerequisiti

Creare un connettore API

Abilitare il connettore API in un flusso utente

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Esempio di risposta

Esempio di risposta di continuazione

Prerequisiti

Preparare un endpoint dell'API REST

Definire attestazioni

Aggiungere il profilo tecnico dell'API RESTful

Configurare il profilo tecnico dell'API RESTful

Per aggiungere un passaggio di orchestrazione

Includere un'attestazione nel token

Testare i criteri personalizzati

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Procedure consigliate

Usare la registrazione

Uso delle funzioni cloud serverless

Uso della registrazione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive