Aggiungere connettori API per registrare i flussi utente

2024-01-24

Importante

A partire dal 1° maggio 2025, Azure AD B2C non sarà più disponibile per l'acquisto per i nuovi clienti. Altre informazioni sono disponibili nelle domande frequenti.

Prima di iniziare, utilizza 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.

Gli sviluppatori o gli amministratori IT possono usare i connettori API per integrare i flussi utente di iscrizione con le API REST per personalizzare l'esperienza di iscrizione e l'integrazione con sistemi esterni. Al termine di questa procedura dettagliata, sarà possibile creare un flusso utente di Azure AD B2C che interagisce con i servizi API REST per modificare le esperienze di iscrizione.

È possibile creare un endpoint API usando uno degli esempi.

In questo scenario si aggiungerà la possibilità agli utenti di immettere un numero di fedeltà nella pagina di iscrizione ad Azure AD B2C. L'API REST verifica se la combinazione di messaggi di posta elettronica e numero di fedeltà viene mappata a un codice promozionale. Se l'API REST trova un codice promozionale per questo utente, verrà restituito ad Azure AD B2C. Infine, il codice promozionale verrà inserito nelle attestazioni del token da utilizzare per l'applicazione.

È anche possibile progettare l'interazione come passaggio di orchestrazione. Questa operazione è adatta quando l'API REST non convalida i dati sullo schermo e restituisce sempre attestazioni. Per altre informazioni, vedere Procedura dettagliata: Integrare scambi di attestazioni API REST nel percorso utente di Azure AD B2C come passaggio di orchestrazione.

Prerequisiti

Creare un flusso utente in modo tale 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. Questa esercitazione illustra come aggiornare i file di criteri personalizzati per usare la configurazione del tenant di Azure AD B2C.
Registrare un'applicazione Web.

Creare un connettore API

Per usare un connettore API, creare prima il connettore API, 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, Convalidare le informazioni utente.
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 connettore API.
Seleziona Salva.

La richiesta inviata all'API

Un connettore API si materializza come richiesta HTTP POST, inviando attributi utente ('richieste') come coppie chiave-valore in un corpo JSON. Gli attributi vengono serializzati in modo analogo alle proprietà utente di Microsoft Graph.

Richiesta di esempio

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "step": "<step-name>",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Nella richiesta sono disponibili solo le proprietà utente e gli attributi personalizzati elencati nell'esperienzaAttributi utente di >.

Gli attributi personalizzati esistono nel formato extension_<extensions-app-id>_CustomAttribute nella directory. L'API dovrebbe aspettarsi di ricevere richieste 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:

Impostazioni locali dell'interfaccia utente ('ui_locales'): impostazione locale dell'utente finale così come è configurata sul suo 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. I valori includono:
- PostFederationSignup - corrisponde a "Dopo la federazione con un provider di identità durante l'iscrizione"
- PostAttributeCollection - corrisponde a "Prima di creare l'utente"
- PreTokenIssuance - corrisponde a "Prima di inviare il token (anteprima)". Altre informazioni su 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 del appId dell'applicazione di risorse nei token di accesso.
Indirizzo e-mail ('email') o identità ('identities'): queste attestazioni possono essere usate dall'API per identificare l'utente finale che esegue l'autenticazione all'applicazione.

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.

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, quindi selezionare il flusso utente a cui si vuole aggiungere il connettore API.
Selezionare Connettori API, quindi selezionare gli endpoint API da richiamare nei passaggi seguenti nel flusso utente:
- Dopo la federazione con un provider di identità durante l'accesso
- Prima della creazione dell'utente
- Prima di inviare il token (anteprima)
Seleziona Salva.

Questi passaggi esistono solo per l'iscrizione e l'accesso (scelta consigliata) e l'iscrizione (scelta consigliata), ma si applicano solo alla parte di iscrizione dell'esperienza.

Un connettore API in questo passaggio del processo di iscrizione viene richiamato immediatamente dopo che l'utente esegue l'autenticazione con un provider di identità (ad esempio Google, Facebook e Microsoft Entra ID). Questo passaggio precede la pagina di raccolta attributi, ovvero il modulo presentato all'utente per raccogliere gli attributi utente. Questo passaggio non viene richiamato se un utente esegue la registrazione con un account locale.

Richiesta di esempio inviata all'API in questo passaggio

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "step": "PostFederationSignup",
 "client_id":"<guid>",
 "ui_locales":"en-US"
}

Le attestazioni esatte inviate all'API dipendono dalle informazioni fornite dal provider di identità. Il contenuto 'email' viene sempre inviato.

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 queste risposte:

Risposta di continuazione
Risposta di blocco

Risposta di continuazione

Una risposta di continuazione indica che il flusso utente deve continuare con il passaggio successivo: la pagina di raccolta di attributi.

In una risposta di continuazione, l'API può restituire richieste. Se un'attestazione viene restituita dall'API, l'attestazione esegue le operazioni seguenti:

Compila in modo preliminare il campo di input nella pagina della raccolta di attributi.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

Una risposta di blocco esce dal flusso utente. Può essere rilasciata intenzionalmente dall'API per arrestare la continuazione del flusso utente visualizzando una pagina di blocco all'utente. La pagina di blocco visualizza il userMessage fornito dall'API.

Vedere un esempio di risposta di blocco.

Prima della creazione dell'utente

Un connettore API in questo passaggio del processo di iscrizione viene richiamato dopo la pagina di raccolta degli attributi, se ne è inclusa una. Questo passaggio viene sempre richiamato prima della creazione di un account utente.

Richiesta di esempio inviata all'API in questo passaggio

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "step": "PostAttributeCollection",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Le attestazioni inviate all'API dipendono dalle informazioni raccolte dall'utente o fornite dal provider di identità.

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 queste risposte:

Risposta di continuazione
Risposta di blocco
Risposta di convalida

Risposta di continuazione

Una risposta di continuazione indica che il flusso utente deve continuare con il passaggio successivo: creare l'utente nella directory.

In una risposta di continuazione, l'API può restituire richieste. Se un'attestazione viene restituita dall'API, l'attestazione esegue le operazioni seguenti:

Esegue l'override di qualsiasi valore già fornito da un utente nella pagina della raccolta di attributi.

Per scrivere attributi nella directory durante l'iscrizione che non devono essere raccolti dall'utente, è comunque necessario selezionare gli attributi sotto Attributi utente del flusso utente, che chiederà all'utente, per impostazione predefinita, di fornire valori. Tuttavia, è possibile utilizzare JavaScript o CSS personalizzati per nascondere i campi di input agli utenti finali.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

Vedere un esempio di risposta di blocco.

Risposta di errore di convalida

Quando l'API risponde con un errore di convalida, il flusso utente rimane sulla pagina di raccolta degli attributi e viene visualizzato al'utente un userMessage. L'utente può quindi modificare e inviare nuovamente il modulo. Questo tipo di risposta può essere usato per la convalida dell'input.

Vedere un esempio di risposta di errore di convalida.

Prima di inviare il token (anteprima)

Importante

I connettori API usati in questo passaggio sono in anteprima. Per altre informazioni sulle anteprime, vedere Condizioni per i prodotti per i servizi online.

Un connettore API in questo passaggio viene richiamato quando un token sta per essere rilasciato durante l'accesso e l'iscrizione. Un connettore API per questo passaggio può essere usato per arricchire il token con valori attestazioni provenienti da origini esterne.

Richiesta di esempio inviata all'API in questo passaggio

POST <API-endpoint>
Content-type: application/json

{
 "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
}

Le attestazioni inviate all'API dipendono dalle informazioni definite per l'utente.

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 queste risposte:

Risposta di continuazione

Risposta di continuazione

Una risposta di continuazione indica che il flusso utente deve continuare con il passaggio successivo: rilasciare il token.

In una risposta di continuazione, l'API può restituire attestazioni aggiuntive. Un'attestazione restituita dall'API che si vuole 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 asserito nel token sarà il valore restituito dall'API, non quello 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.

Vedere un esempio di risposta di continuazione.

Annotazioni

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.

Risposte di esempio

Esempio di una risposta continua

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	TIPO	Obbligatorio	Descrizione
Versione	string	Sì	La versione dell'API.
azione	string	Sì	Il valore deve essere `Continue`.
<builtInUserAttribute>	<tipo di attributo>	NO	I valori restituiti possono sovrascrivere i valori raccolti da un utente.
<extension_{extensions-app-id}_CustomAttribute>	<tipo di attributo>	NO	L'attestazione non deve contenere `_<extensions-app-id>_`, è facoltativa. I valori restituiti possono sovrascrivere i valori raccolti da un utente.

Esempio di una risposta di blocco

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was a problem with your request. You are not able to sign up at this time. Please contact your system administrator",
}

Parametro	TIPO	Obbligatorio	Descrizione
Versione	string	Sì	La versione dell'API.
azione	string	Sì	Il valore deve essere `ShowBlockPage`
messaggio dell'utente	string	Sì	Messaggio da visualizzare all'utente.

Esperienza utente finale con una risposta di blocco

Esempio di risposta di blocco

Esempio di una risposta di errore di convalida

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code."
}

Parametro	TIPO	Obbligatorio	Descrizione
Versione	string	Sì	La versione dell'API.
azione	string	Sì	Il valore deve essere `ValidationError`.
stato	Integer / Stringa	Sì	Deve essere un valore di `400` o `"400"` per una risposta ValidationError.
messaggio dell'utente	string	Sì	Messaggio da visualizzare all'utente.

Annotazioni

Il codice di stato HTTP deve essere "400" oltre al valore "status" nel corpo della risposta.

Esperienza utente finale con una risposta di errore di convalida

Esempio di risposta di errore di convalida

Preparare un endpoint DELL'API REST

Per questa procedura dettagliata, è necessario disporre di un'API REST che convalida se un indirizzo di posta elettronica è registrato nel sistema back-end con un ID fedeltà. Se registrato, l'API REST deve restituire un codice promozionale di registrazione, che il cliente può usare per acquistare merci all'interno dell'applicazione. In caso contrario, l'API REST deve restituire un messaggio di errore HTTP 409: "ID fedeltà '{ID fedeltà}' non è associato all'indirizzo di posta elettronica '{email}'.

Il codice JSON seguente illustra i dati che Azure AD B2C invierà all'endpoint dell'API REST.

{
    "email": "User email address",
    "language": "Current UI language",
    "loyaltyId": "User loyalty ID"
}

Dopo aver convalidato i dati, l'API REST deve restituire un HTTP 200 (Ok), con i dati JSON seguenti:

{
    "promoCode": "24534"
}

Se la convalida non è riuscita, l'API REST deve restituire un http 409 (conflitto), con l'elemento userMessage JSON. L'IEF prevede l'attestazione userMessage restituita dall'API REST. Questa attestazione verrà presentata come stringa all'utente se la convalida non riesce.

{
    "version": "1.0.1",
    "status": 409,
    "userMessage": "LoyaltyId ID '1234' is not associated with 'david@contoso.com' email address."
}

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

Definire le richieste

Un claim fornisce l'archiviazione temporanea dei dati durante l'esecuzione di una policy di Azure AD B2C. È possibile dichiarare attestazioni all'interno della sezione dello schema delle attestazioni .

Apri il file delle estensioni della tua policy. 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="loyaltyId">
  <DisplayName>Your loyalty ID</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>
<ClaimType Id="promoCode">
  <DisplayName>Your promo code</DisplayName>
  <DataType>string</DataType>
  <UserInputType>Paragraph</UserInputType>
</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 proprio servizio RESTful. Azure AD B2C invia i dati al servizio RESTful in una InputClaims raccolta e riceve i dati in una OutputClaims raccolta. Trovare l'elemento ClaimsProviders e aggiungere un nuovo provider di attestazioni come indicato di seguito:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-ValidateProfile">
      <DisplayName>Check loyaltyId 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/ValidateProfile?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="loyaltyId" />
        <InputClaim ClaimTypeReferenceId="email" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

In questo esempio, userLanguage verrà inviato al servizio REST come lang all'interno del payload JSON. Il valore della richiesta userLanguage contiene l'ID della lingua dell'utente corrente. Per ulteriori informazioni, vedere Risolutore di reclami.

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-ValidateProfile 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 eseguita dal provider di attestazioni RESTful.
AllowInsecureAuthInProduction. In un ambiente di produzione assicurarsi di impostare questi metadati su true

Per altre configurazioni, vedere i metadati del profilo tecnico RESTful .

I commenti precedenti AuthenticationType e AllowInsecureAuthInProduction specificano le modifiche da 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.

Convalidare l'input dell'utente

Per ottenere il numero di fedeltà dell'utente durante l'iscrizione, è necessario consentire all'utente di immettere questi dati sullo schermo. Aggiungere l'attestazione di output loyaltyId alla pagina di iscrizione aggiungendola all'elemento OutputClaims del profilo tecnico di iscrizione esistente. Specificare l'intero elenco di attestazioni di output per controllare l'ordine in cui vengono visualizzate le attestazioni sullo schermo.

Aggiungere il riferimento al profilo tecnico di convalida al profilo tecnico di iscrizione, che chiama il REST-ValidateProfile. Il nuovo profilo tecnico di convalida verrà aggiunto all'inizio della <ValidationTechnicalProfiles> raccolta definita nella politica di base. Questo comportamento significa che solo dopo la corretta convalida, Azure AD B2C passa alla creazione dell'account nella directory.

Trova l'elemento ClaimsProviders. Aggiungere un nuovo fornitore di attestazioni come segue:

<ClaimsProvider>
  <DisplayName>Local Account</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="Verified.Email" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="newPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="reenterPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surName"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile" />
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>
<ClaimsProvider>
  <DisplayName>Self Asserted</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="SelfAsserted-Social">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="email" />
      </InputClaims>
        <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surname"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile"/>
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Includere un'attestazione nel token

Per restituire l'attestazione di codice promozionale all'applicazione relying party, aggiungere un'attestazione di output al file SocialAndLocalAccounts/SignUpOrSignIn.xml. L'attestazione di output consentirà di aggiungere l'attestazione al token dopo un percorso utente riuscito e verrà inviata all'applicazione. Modificare l'elemento del profilo tecnico all'interno della sezione relying party per aggiungere promoCode 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="promoCode" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Testare la politica personalizzata

Accedi al portale di Azure.
Se hai accesso a più tenant, seleziona l'icona Impostazioni nel menu in alto della schermata per passare al tenant di Microsoft Entra ID dal menu Directory + sottoscrizioni.
Scegliere Tutti i servizi nell'angolo in alto a sinistra del portale di Azure e quindi cercare e selezionare Registrazioni app.
Selezionare Identity Experience Framework.
Selezionare Carica criteri personalizzati e quindi caricare i file dei criteri modificati: TrustFrameworkExtensions.xmle SignUpOrSignin.xml.
Selezionare i criteri di iscrizione o di accesso caricati e fare clic sul pulsante Esegui adesso .
Dovrebbe essere possibile iscriversi usando un indirizzo di posta elettronica.
Fare clic sul collegamento Iscriviti ora .
Nell'ID fedeltà digitare 1234 e fare clic su Continua. A questo punto, dovrebbe essere visualizzato un messaggio di errore di convalida.
Passare a un altro valore e fare clic su Continua.
Il token inviato all'applicazione include l'attestazione promoCode.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "22223333-cccc-4444-dddd-5555eeee6666",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584292103,
  "auth_time": 1584292103,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "promoCode": "84362"
  ...
}

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Le funzioni serverless, come i trigger HTTP in Funzioni di Azure, consentono di creare endpoint API da usare con il connettore API. È possibile usare la funzione cloud serverless per, ad esempio, eseguire la logica di convalida e limitare le iscrizione a domini di posta elettronica specifici. 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 10 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 downstream delle API, 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

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. Ricontrollare il livello di autenticazione dell'API e la configurazione corrispondente nel connettore API.
Se necessario, usare livelli di log più aggressivi, ad esempio "trace" o "debug", durante lo sviluppo.
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 per Attività, selezionare Un'API è stata 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 1o 2. Altre informazioni sulla chiamata API sono descritte in dettaglio nei log.

Esempio di transazione del connettore API durante l'autenticazione utente

Uso delle funzioni cloud serverless

Le funzioni cloud serverless, come i trigger HTTP in Funzioni di Azure, offrono un modo semplice, a disponibilità elevata e ad alte prestazioni per creare endpoint API da usare come connettori API.

Procedure consigliate

Assicurarsi che:

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.
- 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
Garantire la disponibilità elevata dell'API.
Monitorare e ottimizzare le prestazioni downstream delle API, dei database o di altre dipendenze dell'API.

Importante

Usare la registrazione

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. Ricontrollare il livello di autenticazione dell'API e la configurazione corrispondente nel connettore API.
Se necessario, usare livelli di log più aggressivi, ad esempio "trace" o "debug", durante lo sviluppo.
Monitorare l'API per tempi di risposta lunghi.

Passaggi successivi

Inizia con i nostri esempi.
Proteggere il connettore API

Condividi tramite

Aggiungere un connettore API a un flusso utente di iscrizione

Prerequisiti

Creare un connettore API

La richiesta inviata all'API

Abilitare il connettore API in un flusso utente

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

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposta di blocco

Prima della creazione dell'utente

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposta di blocco

Risposta di errore di convalida

Prima di inviare il token (anteprima)

Richiesta di esempio inviata all'API in questo passaggio

Tipi di risposta previsti dall'API Web in questo passaggio

Risposta di continuazione

Risposte di esempio

Esempio di una risposta continua

Esempio di una risposta di blocco

Esempio di una risposta di errore di convalida

Preparare un endpoint DELL'API REST

Definire le richieste

Aggiungere il profilo tecnico dell'API RESTful

Configurare il profilo tecnico dell'API RESTful

Convalidare l'input dell'utente

Includere un'attestazione nel token

Testare la politica personalizzata

Procedure consigliate e risoluzione dei problemi

Uso delle funzioni cloud serverless

Procedure consigliate

Usare la registrazione

Uso delle funzioni cloud serverless

Procedure consigliate

Usare la registrazione

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive