Procedura dettagliata: Integrare scambi di attestazioni API REST nel percorso utente di Azure AD B2C come convalida dell'input utenteWalkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as validation on user input

Nota

I criteri personalizzati sono disponibili in anteprima pubblica.Custom policies are in public preview.

I criteri personalizzati sono stati progettati principalmente per fare fronte a scenari complessi.Custom policies are designed primarily to address complex scenarios. Per la maggior parte degli scenari è consigliabile usare i criteri predefiniti di Azure Active Directory B2C.For most scenarios, we recommend that you use Azure Active Directory B2C built-in policies. I criteri predefiniti sono più facili da impostare per la configurazione.Built-in policies are easier to set up for your configuration.

Il framework dell'esperienza di gestione delle identità alla base di Azure Active Directory B2C (Azure AD B2C) consente allo sviluppatore delle identità di integrare un'interazione con un'API RESTful in un percorso utente.The Identity Experience Framework (IEF) that underlies Azure Active Directory B2C (Azure AD B2C) enables the identity developer to integrate an interaction with a RESTful API in a user journey.

Al termine di questa procedura dettagliata sarà possibile creare percorsi utente di Azure AD B2C che interagiscono con i servizi RESTful.At the end of this walkthrough, you will be able to create an Azure AD B2C user journey that interacts with RESTful services.

Il framework dell'esperienza di gestione delle identità invia i dati in attestazioni e riceve di nuovo i dati in attestazioni.The IEF sends data in claims and receives data back in claims. L'interazione con l'API:The interaction with the API:

  • Può essere progettata come scambio di attestazioni API REST o come profilo di convalida all'interno di un passaggio di orchestrazione.Can be designed as a REST API claims exchange or as a validation profile, which happens inside an orchestration step.
  • In genere viene convalidato l'input dell'utente.Typically validates input from the user. Se il valore fornito dall'utente viene rifiutato, l'utente può provare nuovamente a immettere un valore valido con la possibilità di restituire un messaggio di errore.If the value from the user is rejected, the user can try again to enter a valid value with the opportunity to return an error message.

È possibile progettare l'interazione anche come passaggio di orchestrazione.You can also design the interaction as an orchestration step. Per altre informazioni, vedere Procedura dettagliata: Integrare scambi di attestazioni API REST nei percorsi utente di Azure AD B2C come passaggio di orchestrazione.For more information, see Walkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as an orchestration step.

Per l'esempio del profilo di convalida si userà il percorso utente di modifica profilo disponibile nel file ProfileEdit.xml dello starter pack.For the validation profile example, we will use the profile edit user journey in the starter pack file ProfileEdit.xml.

È possibile verificare che il nome fornito dall'utente nella modifica del profilo non faccia parte di un elenco di esclusione.We can verify that the name provided by the user in the profile edit is not part of an exclusion list.

prerequisitiPrerequisites

  • Un tenant di Azure AD B2C configurato per completare una procedura di iscrizione/accesso di un account locale, come descritto in Introduzione.An Azure AD B2C tenant configured to complete a local account sign-up/sign-in, as described in Getting started.
  • Un endpoint API REST con il quale interagire.A REST API endpoint to interact with. Per questa procedura dettagliata è stato configurato un sito demo denominato WingTipGames con un servizio API REST.For this walkthrough, we've set up a demo site called WingTipGames with a REST API service.

Passaggio 1: Preparare la funzione API RESTStep 1: Prepare the REST API function

Nota

La configurazione delle funzioni API REST non rientra nell'ambito di questo articolo.Setup of REST API functions is outside the scope of this article. Funzioni di Azure offre un eccellente toolkit per creare servizi RESTful nel cloud.Azure Functions provides an excellent toolkit to create RESTful services in the cloud.

È stata creata una funzione di Azure che riceve un'attestazione prevista come playerTag.We have created an Azure function that receives a claim that it expects as playerTag. La funzione verifica che l'attestazione esista.The function validates whether this claim exists. È possibile accedere al codice completo della funzione di Azure in GitHub.You can access the complete Azure function code in GitHub.

if (requestContentAsJObject.playerTag == null)
{
  return request.CreateResponse(HttpStatusCode.BadRequest);
}

var playerTag = ((string) requestContentAsJObject.playerTag).ToLower();

if (playerTag == "mcvinny" || playerTag == "msgates123" || playerTag == "revcottonmarcus")
{
  return request.CreateResponse<ResponseContent>(
    HttpStatusCode.Conflict,
    new ResponseContent
    {
      version = "1.0.0",
      status = (int) HttpStatusCode.Conflict,
      userMessage = $"The player tag '{requestContentAsJObject.playerTag}' is already used."
    },
    new JsonMediaTypeFormatter(),
    "application/json");
}

return request.CreateResponse(HttpStatusCode.OK);

L'attestazione userMessage restituita dalla funzione di Azure è prevista dal framework dell'esperienza di gestione delle identitàThe IEF expects the userMessage claim that the Azure function returns. e verrà visualizzata all'utente sotto forma di stringa se la convalida non riesce, ad esempio quando viene restituito lo stato di conflitto 409 nell'esempio precedente.This claim will be presented as a string to the user if the validation fails, such as when a 409 conflict status is returned in the preceding example.

Passaggio 2: Configurare lo scambio di attestazioni API RESTful come profilo tecnico nel file TrustFrameworkExtensions.xmlStep 2: Configure the RESTful API claims exchange as a technical profile in your TrustFrameworkExtensions.xml file

Un profilo tecnico è la configurazione completa dello scambio desiderato con il servizio RESTful.A technical profile is the full configuration of the exchange desired with the RESTful service. Aprire il file TrustFrameworkExtensions.xml e aggiungere il frammento XML seguente all'interno dell'elemento <ClaimsProviders>.Open the TrustFrameworkExtensions.xml file and add the following XML snippet inside the <ClaimsProviders> element.

Nota

Nell'XML seguente il provider RESTful Version=1.0.0.0 viene descritto come il protocollo.In the following XML, RESTful provider Version=1.0.0.0 is described as the protocol. Considerarlo come la funzione che interagirà con il servizio esterno.Consider it as the function that will interact with the external service.

<ClaimsProvider>
    <DisplayName>REST APIs</DisplayName>
    <TechnicalProfiles>
        <TechnicalProfile Id="AzureFunctions-CheckPlayerTagWebHook">
            <DisplayName>Check Player Tag Web Hook Azure Function</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://wingtipb2cfuncs.azurewebsites.net/api/CheckPlayerTagWebHook?code=L/05YRSpojU0nECzM4Tp3LjBiA2ZGh3kTwwp1OVV7m0SelnvlRVLCg==</Item>
                <Item Key="AuthenticationType">None</Item>
                <Item Key="SendClaimsIn">Body</Item>
            </Metadata>
            <InputClaims>
                <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="playerTag" />
            </InputClaims>
            <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
        </TechnicalProfile>
        <TechnicalProfile Id="SelfAsserted-ProfileUpdate">
            <ValidationTechnicalProfiles>
                <ValidationTechnicalProfile ReferenceId="AzureFunctions-CheckPlayerTagWebHook" />
            </ValidationTechnicalProfiles>
        </TechnicalProfile>
    </TechnicalProfiles>
</ClaimsProvider>

L'elemento InputClaims definisce le attestazioni che verranno inviate dal framework dell'esperienza di gestione delle identità al servizio REST.The InputClaims element defines the claims that will be sent from the IEF to the REST service. In questo esempio il contenuto dell'attestazione givenName verrà inviato al servizio REST come playerTag.In this example, the contents of the claim givenName will be sent to the REST service as playerTag. In questo esempio, il framework dell'esperienza di gestione non prevede di ricevere attestazioni,In this example, the IEF does not expect claims back. ma attende una risposta dal servizio REST e agisce in base ai codici di stato ricevuti.Instead, it waits for a response from the REST service and acts based on the status codes that it receives.

Passaggio 3: Includere lo scambio di attestazioni del servizio RESTful nel profilo tecnico autocertificato in cui si vuole convalidare l'input dell'utenteStep 3: Include the RESTful service claims exchange in self-asserted technical profile where you want to validate the user input

L'uso più comune del passaggio di convalida è nell'interazione con un utente.The most common use of the validation step is in the interaction with a user. Tutte le interazioni in cui è previsto che l'utente fornisca un input sono profili tecnici autocertificati.All interactions where the user is expected to provide input are self-asserted technical profiles. Per questo esempio si aggiungerà la convalida al profilo tecnico Self-Asserted-ProfileUpdate.For this example, we will add the validation to the Self-Asserted-ProfileUpdate technical profile. Questo è il profilo tecnico usato dal file dei criteri relying party Profile Edit.This is the technical profile that the relying party (RP) policy file Profile Edit uses.

Per aggiungere lo scambio di attestazioni al profilo tecnico autocertificato:To add the claims exchange to the self-asserted technical profile:

  1. Aprire il file TrustFrameworkBase.xml e cercare <TechnicalProfile Id="SelfAsserted-ProfileUpdate">.Open the TrustFrameworkBase.xml file and search for <TechnicalProfile Id="SelfAsserted-ProfileUpdate">.
  2. Esaminare la configurazione di questo profilo tecnico.Review the configuration of this technical profile. Si noti che lo scambio con l'utente è definito come attestazioni che verranno chieste all'utente (attestazioni di input) e attestazioni che dovranno essere inviate dal provider autocertificato (attestazioni di output).Observe how the exchange with the user is defined as claims that will be asked of the user (input claims) and claims that will be expected back from the self-asserted provider (output claims).
  3. Cercare TechnicalProfileReferenceId="SelfAsserted-ProfileUpdate. Tenere presente che questo profilo viene richiamato come passaggio di orchestrazione 4 di <UserJourney Id="ProfileEdit">.Search for TechnicalProfileReferenceId="SelfAsserted-ProfileUpdate, and notice that this profile is invoked as orchestration step 4 of <UserJourney Id="ProfileEdit">.

Passaggio 4: Caricare e testare il file dei criteri relying party di modifica del profiloStep 4: Upload and test the profile edit RP policy file

  1. Caricare la nuova versione del file TrustFrameworkExtensions.xml.Upload the new version of the TrustFrameworkExtensions.xml file.
  2. Usare Esegui adesso per testare il file dei criteri relying party di modifica del profilo.Use Run now to test the profile edit RP policy file.
  3. Testare la convalida specificando uno dei nomi esistenti, ad esempio mcvinny, nel campo Nome.Test the validation by providing one of the existing names (for example, mcvinny) in the Given Name field. Se la configurazione è stata eseguita correttamente, verrà visualizzato un messaggio per avvisare l'utente che il tag del player è già in uso.If everything is set up correctly, you should receive a message that notifies the user that the player tag is already used.

Passaggi successiviNext steps

Cambiare la modifica del profilo e la registrazione degli utenti per raccogliere informazioni dagli utentiModify the profile edit and user registration to gather additional information from your users

Procedura dettagliata: Integrare scambi di attestazioni API REST nei percorsi utente di Azure AD B2C come passaggio di orchestrazioneWalkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as an orchestration step