Condividi tramite

Usare i connettori API per personalizzare ed estendere i flussi utente di iscrizione e i criteri personalizzati con origini dati di identità esterne

  • Articolo

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

Panoramica

Come sviluppatore o amministratore IT, è possibile usare connettori API per integrare i flussi utente di iscrizione con le API REST per personalizzare l'esperienza di iscrizione e integrarsi con sistemi esterni. Ad esempio, con connettori API, è possibile:

  • Convalidare i dati di input utente. Convalidare i dati utente non validi o non validi. Ad esempio, è possibile convalidare i dati forniti dall'utente rispetto ai dati esistenti in un archivio dati esterno o un elenco di valori consentiti. Se non è valido, è possibile chiedere a un utente di fornire dati validi o impedire all'utente di continuare il flusso di iscrizione.
  • Verificare l'identità utente. Usare un servizio di verifica delle identità o origini dati di identità esterne per aggiungere un livello di sicurezza aggiuntivo alle decisioni di creazione dell'account.
  • Integrare con un flusso di lavoro di approvazione personalizzato. Connettersi a un sistema di approvazione personalizzato per la gestione e la limitazione della creazione dell'account.
  • Aumentare i token con attributi da origini esterne. Arricchire i token con attributi relativi all'utente da origini esterne ad Azure AD B2C, ad esempio sistemi cloud, archivi utente personalizzati, sistemi di autorizzazione personalizzati, servizi di identità legacy e altro ancora.
  • Sovrascrivere gli attributi utente. Modificare o assegnare un valore a un attributo raccolto dall'utente. Ad esempio, se un utente immette il nome in lettere tutte minuscole o tutte maiuscole, è possibile formattare il nome con solo la prima lettera maiuscola.
  • Eseguire la logica di business personalizzata. È possibile attivare eventi downstream nei sistemi cloud per inviare notifiche push, aggiornare database aziendali, gestire autorizzazioni, database di controllo ed eseguire altre azioni personalizzate.

Un connettore API fornisce ad Azure AD B2C le informazioni necessarie per chiamare l'endpoint API definendo l'URL dell'endpoint HTTP e l'autenticazione per la chiamata API. Dopo aver configurato un connettore API, è possibile abilitarlo per un passaggio specifico in un flusso utente. Quando un utente raggiunge tale passaggio nel flusso di iscrizione, il connettore API viene richiamato e materializza come richiesta HTTP POST all'API, inviando le informazioni utente ("attestazioni") come coppie chiave-valore in un corpo JSON. La risposta api può influire sull'esecuzione del flusso utente. Ad esempio, la risposta api può impedire a un utente di iscriversi, chiedere all'utente di immettere nuovamente le informazioni o sovrascrivere gli attributi utente.

Dove è possibile abilitare un connettore API in un flusso utente

Esistono tre posizioni in un flusso utente in cui è possibile abilitare un connettore API:

  • Dopo la federazione con un provider di identità durante l'iscrizione , si applica solo alle esperienze di iscrizione
  • Prima di creare l'utente : si applica solo alle esperienze di iscrizione
  • Prima di inviare il token (anteprima) - si applica agli accessi e agli accessi

Dopo la federazione con un provider di identità durante l'iscrizione

Un connettore API in questo passaggio del processo di iscrizione viene richiamato immediatamente dopo l'autenticazione dell'utente con un provider di identità (ad esempio Google, Facebook e Microsoft Entra ID). Questo passaggio precede la pagina della raccolta di attributi, ovvero il modulo presentato all'utente per raccogliere gli attributi utente. Questo passaggio non viene richiamato se un utente sta registrando con un account locale. Di seguito sono riportati esempi di scenari di connettore API che è possibile abilitare in questo passaggio:

  • Usare l'identità di posta elettronica o federata fornita dall'utente per cercare le attestazioni in un sistema esistente. Restituisce queste attestazioni dal sistema esistente, pre-compilare la pagina della raccolta di attributi e renderle disponibili per restituire nel token.
  • Implementare un elenco consentito o bloccato in base all'identità social.

Prima di creare l'utente

Un connettore API in questo passaggio del processo di iscrizione viene richiamato dopo la pagina della raccolta di attributi, se ne è incluso uno. Questo passaggio viene sempre richiamato prima della creazione di un account utente. Di seguito sono riportati esempi di scenari che è possibile abilitare a questo punto durante l'iscrizione:

  • Convalidare i dati di input utente e chiedere a un utente di inviare nuovamente i dati.
  • Bloccare l'iscrizione di un utente in base ai dati immessi dall'utente.
  • Verificare l'identità utente.
  • Eseguire query sui sistemi esterni per i dati esistenti sull'utente per restituirlo nel token dell'applicazione o archiviarlo in Microsoft Entra ID.

Prima di inviare il token (anteprima)

Nota

Questa funzionalità è disponibile in anteprima pubblica.

Un connettore API in questo passaggio dell'iscrizione o del processo di accesso viene richiamato prima dell'emissione di un token. Di seguito sono riportati esempi di scenari che è possibile abilitare in questo passaggio:

  • Arricchimento del token con attributi relativi all'utente da origini diverse rispetto alla directory, inclusi i sistemi di identità legacy, i sistemi HR, gli archivi utente esterni e altro ancora.
  • Arricchimento del token con attributi di gruppo o ruolo archiviati e gestiti nel proprio sistema di autorizzazione.
  • Applicazione di trasformazioni o manipolazioni delle attestazioni ai valori delle attestazioni nella directory.

L'Identity Experience Framework, che è alla base di Azure Active Directory B2C (Azure AD B2C), è in grado di eseguire un'integrazione con API RESTful all'interno di un percorso utente. Questo articolo illustra come creare un percorso utente che interagisce con un servizio RESTful usando un profilo tecnico RESTful.

Usando Azure AD B2C, è possibile aggiungere la logica di business a un percorso utente chiamando il servizio RESTful. L'Identity Experience Framework può inviare e ricevere dati dal servizio RESTful per lo scambio di attestazioni. Ad esempio, è possibile:

  • Usare l'origine dati dell'identità esterna per convalidare i dati di input utente. È possibile ad esempio verificare che l'indirizzo di posta elettronica indicato dall'utente sia presente nel database del cliente e, in caso contrario, presentare un errore. È anche possibile considerare i connettori API come un modo per supportare webhook in uscita perché la chiamata viene eseguita quando si verifica un evento, ad esempio un iscrizione.
  • Elaborare le attestazioni. Se un utente immette il nome in lettere tutte minuscole o tutte maiuscole, l'API REST può formattare il nome con solo la prima lettera maiuscola e restituirlo ad Azure AD B2C. Tuttavia, quando si usa un criterio personalizzato, Le attestazioniTransformations sono preferite per chiamare un'API RESTful.
  • Arricchire dinamicamente i dati utente integrando ulteriormente le applicazioni line-of-business aziendali. Il servizio RESTful può ricevere l'indirizzo di posta elettronica dell'utente, eseguire una query sul database del cliente e restituire il numero del programma fedeltà dell'utente ad Azure AD B2C. Le attestazioni restituite possono quindi essere archiviate nell'account di Microsoft Entra dell'utente, valutate nei passaggi di orchestrazione successivi o incluse nel token di accesso.
  • Eseguire la logica di business personalizzata. È possibile inviare notifiche push, aggiornare i database aziendali, eseguire un processo di migrazione utente, gestire le autorizzazioni, controllare i database ed eseguire qualsiasi altro flusso di lavoro.

Diagramma di uno scambio di attestazioni del servizio RESTful

Nota

Se il servizio RESTful è lento o nessuna risposta a Azure AD B2C, il timeout è di 30 secondi e il conteggio dei tentativi è due volte (ovvero sono presenti 3 tentativi in totale). Attualmente non è possibile configurare le impostazioni di timeout e conteggio dei tentativi.

Chiamata a un servizio RESTful

L'interazione include uno scambio di attestazioni di informazioni tra le attestazioni API REST e Azure AD B2C. È possibile progettare l'integrazione con i servizi RESTful nei modi seguenti:

  • Profilo tecnico di convalida. La chiamata al servizio RESTful si verifica all'interno di un profilo tecnico di convalida del profilo tecnico autocertificato specificato o di un controllo di visualizzazione della verifica di un controllo di visualizzazione. Il profilo tecnico convalida i dati specificati dall'utente prima che il percorso utente proceda. Il profilo tecnico di convalida consente di eseguire queste operazioni:

    • Inviare attestazioni all'API REST.
    • Convalidare le attestazioni e generare messaggi di errore personalizzati che vengono visualizzati all'utente.
    • Inviare attestazioni dall'API REST alla procedura di orchestrazione successiva.

  • Scambio di attestazioni. Uno scambio di attestazioni dirette può essere configurato chiamando un profilo tecnico dell'API REST direttamente da un passaggio di orchestrazione di un percorso utente. Questa definizione è limitata alle operazioni seguenti:

    • Inviare attestazioni all'API REST.
    • Convalidare le attestazioni e generare messaggi di errore personalizzati che vengono restituiti all'applicazione.
    • Inviare attestazioni dall'API REST alla procedura di orchestrazione successiva.

È possibile aggiungere una chiamata API REST in qualsiasi passaggio del percorso utente definito da un criterio personalizzato. Ad esempio, è possibile chiamare un'API REST:

  • Durante l'accesso, subito prima che Azure AD B2C convalidi le credenziali.
  • Subito dopo l'accesso.
  • Prima che Azure AD B2C crei un nuovo account nella directory.
  • Dopo che Azure AD B2C ha creato un nuovo account nella directory.
  • Prima che Azure AD B2C rilasci un token di accesso.

Raccolta del profilo tecnico di convalida

Invio di dati

Nel profilo tecnico RESTful, l'elemento InputClaims contiene un elenco di attestazioni da inviare al servizio RESTful. È possibile mappare il nome dell'attestazione al nome definito nel servizio RESTful, impostare un valore predefinito e usare resolver di attestazioni.

È possibile configurare la modalità di invio delle attestazioni di input al provider di attestazioni RESTful tramite l'attributo SendClaimsIn. I valori possibili sono:

  • Corpo, inviato nel corpo della richiesta HTTP POST in formato JSON.
  • Modulo inviato nel corpo della richiesta HTTP POST in un formato di valore chiave separato '&' .
  • Intestazione, inviato nell'intestazione della richiesta HTTP GET.
  • QueryString, inviato nella stringa di query della richiesta HTTP GET.

Quando viene configurata l'opzione Corpo, il profilo tecnico dell'API REST consente di inviare un payload JSON complesso a un endpoint. Per altre informazioni, vedere Inviare un payload JSON.

Ricezione di dati

L'elemento OutputClaims del profilo tecnico RESTful contiene un elenco di attestazioni restituite dall'API REST. Potrebbe essere necessario eseguire il mapping del nome dell'attestazione definito nei criteri per il nome definito nell'API REST. È anche possibile includere attestazioni che non sono restituite dal provider di identità API REST purché siano impostate sull'attributo DefaultValue.

Le attestazioni di output analizzate dal provider di attestazioni RESTful si aspettano sempre di analizzare una risposta del corpo JSON Flat, ad esempio:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Le attestazioni di output devono essere simili al frammento xml seguente:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Gestione dei valori NULL

Un valore Null in un database viene usato quando il valore in una colonna è sconosciuto o mancante. Non includere chiavi JSON con un null valore. Nell'esempio seguente il messaggio di posta elettronica restituisce null il valore:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Quando un elemento è Null, entrambi:

  • Omettere la coppia chiave-valore dal codice JSON.
  • Restituire un valore che corrisponde al tipo di dati attestazione di Azure AD B2C. Ad esempio, per un string tipo di dati, restituire una stringa ""vuota. Per un integer tipo di dati, restituire un valore 0zero. Per un dateTime tipo di dati, restituire un valore 1970-00-00T00:00:00.0000000Zminimo.

Nell'esempio seguente viene illustrato come gestire un valore Null. Il messaggio di posta elettronica viene omesso dal codice JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Analizzare un corpo JSON annidato

Per analizzare una risposta del corpo JSON annidata, impostare i metadati ResolveJsonPathsInJsonTokens su true. Nell'attestazione di output impostare PartnerClaimType sull'elemento percorso JSON di cui si vuole eseguire l'output.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Le attestazioni di output devono essere simili al frammento xml seguente:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Localizzare l'API REST

In un profilo tecnico RESTful, è possibile inviare il linguaggio o le impostazioni locali della sessione corrente e, se necessario, generare un messaggio di errore localizzato. Usando il resolver delle attestazioni, è possibile inviare un'attestazione contestuale, ad esempio la lingua dell'utente. Nell'esempio seguente viene illustrato un profilo tecnico RESTful che dimostra questo scenario.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Gestione dei messaggi di errore

L'API REST potrebbe dover restituire un messaggio di errore, ad esempio "L'utente non è stato trovato nel sistema CRM". Se si verifica un errore, l'API REST deve restituire un messaggio di errore HTTP 409 (codice di stato della risposta in conflitto). Per altre informazioni, vedere il profilo tecnico RESTful.

Questo comportamento può essere ottenuto solo chiamando un profilo tecnico dell'API REST da un profilo tecnico di convalida. Consentendo all'utente di correggere i dati nella pagina ed eseguire nuovamente la convalida al momento dell'invio della pagina.

Se si fa riferimento a un profilo tecnico dell'API REST direttamente da un percorso utente, l'utente viene reindirizzato di nuovo all'applicazione basata su attestazioni con il messaggio di errore pertinente.

Sviluppo dell'API REST

L'API REST può essere sviluppata in qualsiasi piattaforma e scritta in qualsiasi linguaggio di programmazione, purché sia sicura e possa inviare e ricevere attestazioni in formato JSON.

La richiesta al servizio API REST deriva da server Azure AD B2C. Il servizio API REST deve essere pubblicato in un endpoint HTTPS accessibile pubblicamente. Le chiamate all'API REST arriveranno da un indirizzo IP del data center Azure.

È possibile usare funzioni cloud serverless, ad esempio trigger HTTP in Funzioni di Azure per semplificare lo sviluppo.

È consigliabile progettare il servizio API REST e i relativi componenti sottostanti (ad esempio il database e il file system) per essere a disponibilità elevata.

Importante

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

Passaggi successivi

Per esempi relativi all'uso di un profilo tecnico RESTful, vedere gli articoli seguenti: