Aggiungere un connettore API a un flusso utente di iscrizione

  • Articolo

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.

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.

È possibile progettare l'interazione anche 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 nei percorsi utente di Azure AD B2C come passaggio di orchestrazione.

Prerequisiti

Creare un connettore API

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

  1. Accedi al portale di Azure.

  2. In Servizi di Azure selezionare Azure AD B2C.

  3. Selezionare Connettori API e quindi Nuovo connettore API.

    Screenshot of basic configuration for an API connector

  4. Specificare un nome visualizzato per la chiamata. Ad esempio, Convalidare le informazioni utente.

  5. Specificare l'URL dell'endpoint per la chiamata API.

  6. Scegliere il tipo di autenticazione e configurare le informazioni di autenticazione per chiamare l'API. Informazioni su come proteggere il Connessione or dell'API.

    Screenshot of authentication configuration for an API connector

  7. Seleziona Salva.

Richiesta inviata all'API

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 .

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": "11111111-0000-0000-0000-000000000000",
 "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":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

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:

  • 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. 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 dell'applicazione di risorse nei token di appId accesso.
  • Indirizzo di posta elettronica ('email') o identità ('identità'): 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.

  1. Accedi al portale di Azure.

  2. In Servizi di Azure selezionare Azure AD B2C.

  3. Selezionare Flussi utente e quindi selezionare il flusso utente a cui si vuole aggiungere il connettore API.

  4. Selezionare Connettori API e quindi selezionare gli endpoint API da richiamare nei passaggi seguenti nel flusso utente:

    • Dopo la federazione con un provider di identità durante l'iscrizione
    • Prima di creare l'utente
    • Prima di inviare il token (anteprima)

    Selecting an API connector for a step in the user flow

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

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 che l'utente esegue l'autenticazione 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 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à. '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 della raccolta di attributi.

In una risposta di continuazione, l'API può restituire attestazioni. 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 rilasciato intenzionalmente dall'API per arrestare la continuazione del flusso utente visualizzando una pagina di blocco all'utente. La pagina del blocco visualizza l'oggetto userMessage fornito dall'API.

Vedere un esempio di risposta di blocco.

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 è 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":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "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 attestazioni. 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 attestazioni nella directory all'iscrizione che non deve essere raccolta dall'utente, è comunque necessario selezionare le attestazioni in Attributi utente del flusso utente, che richiederà per impostazione predefinita all'utente valori, ma è possibile usare JavaScript o CSS personalizzato per nascondere i campi di input da un utente finale.

Vedere un esempio di risposta di continuazione.

Risposta di blocco

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

Vedere un esempio di risposta di blocco.

Risposta di errore di convalida

Quando l'API risponde con una risposta di errore di convalida, il flusso utente rimane nella pagina della raccolta di attributi e userMessage viene visualizzato un oggetto all'utente. 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": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "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 dell'attestazione nel token sarà il valore restituito dall'API, non il 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.

Vedere un esempio di risposta di continuazione.

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.

Risposte di esempio

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 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 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 Type Richiesto Descrizione
version Stringa Sì Versione dell'API.
action Stringa Sì Il valore deve essere ShowBlockPage
userMessage Stringa Sì Messaggio da visualizzare all'utente.

Esperienza dell'utente finale con una risposta di blocco

Example of a blocking response

Esempio di 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 Type Richiesto Descrizione
version Stringa Sì Versione dell'API.
action Stringa Sì Il valore deve essere ValidationError.
stato Integer/String Sì Deve essere un valore 400o "400" per una risposta ValidationError.
userMessage Stringa Sì Messaggio da visualizzare all'utente.

Nota

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

Esperienza dell'utente finale con una risposta di errore di convalida

Example of a validation-error response

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

Quando l'API REST convalida i dati, deve restituire un codice 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. È 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.

  1. Aprire il file delle estensioni del criterio, Ad esempio, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Cercare l'elemento BuildingBlocks. Se l'elemento non esiste, aggiungerlo.
  3. Individuare l'elemento ClaimsSchema. Se l'elemento non esiste, aggiungerlo.
  4. 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 offre supporto per l'interazione con il proprio 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 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 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-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 che è necessario apportare quando si passa a un ambiente di produzione. Per informazioni su come proteggere le API RESTful per la produzione, vedere Proteggere i servizi 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 del profilo tecnico di OutputClaims 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 .REST-ValidateProfile Il nuovo profilo tecnico di convalida verrà aggiunto all'inizio della <ValidationTechnicalProfiles> raccolta definita nei criteri di base. Questo comportamento significa che solo dopo la corretta convalida, Azure AD B2C passa alla creazione dell'account nella directory.

  1. Trovare l'elemento ClaimsProviders. Aggiungere un nuovo provider 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 SocialAndLocalAccounts/SignUpOrSignIn.xml file. 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 come promoCode 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 i criteri personalizzati

  1. Accedi al portale di Azure.
  2. Se si ha accesso a più tenant, selezionare l'icona Impostazioni nel menu in alto per passare al tenant microsoft Entra ID dal menu Directory e sottoscrizioni.
  3. Scegliere Tutti i servizi nell'angolo in alto a sinistra nel portale di Azure e quindi cercare e selezionare Registrazioni per l'app.
  4. Fare clic su Framework dell'esperienza di gestione delle identità.
  5. Selezionare Carica criteri personalizzati e quindi caricare i file dei criteri modificati: TrustFrameworkExtensions.xml e SignUpOrSignin.xml.
  6. Selezionare il criterio di iscrizione o di accesso che è stato caricato e fare clic sul pulsante Esegui adesso.
  7. Dovrebbe essere possibile iscriversi usando un indirizzo di posta elettronica.
  8. Fare clic sul collegamento Iscriviti ora .
  9. Nell'ID fedeltà digitare 1234 e fare clic su Continua. A questo punto, dovrebbe essere visualizzato un messaggio di errore di convalida.
  10. Passare a un altro valore e fare clic su Continua.
  11. 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/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "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, ad esempio 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 l'API Connessione or.
  • 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

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:

  1. Passare ad Azure AD B2C.
  2. In Attività selezionare Log di controllo.
  3. Filtrare la visualizzazione elenco: per Data, selezionare l'intervallo di tempo desiderato e selezionare Un'API chiamata come parte di un flusso utente.
  4. 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.

Example of an API connector transaction during user authentication

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 l'API Connessione or.
  • 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 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

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.

Passaggi successivi