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

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. Lo scambio di attestazioni di API REST:The REST API claims exchange:

  • Può essere progettato come passaggio di orchestrazione.Can be designed as an orchestration step.
  • Può attivare un'azione esterna.Can trigger an external action. Può registrare ad esempio un evento in un database esterno.For instance, it can log an event in an external database.
  • Consente di recuperare un valore e quindi archiviarlo nel database utente.Can be used to fetch a value and then store it in the user database.

È possibile usare le attestazioni ricevute in un secondo momento per modificare il flusso di esecuzione.You can use the received claims later to change the flow of execution.

È anche possibile progettare l'interazione come un profilo di convalida.You can also design the interaction as a validation profile. Per altre informazioni, vedere Procedura dettagliata: Integrare scambi di attestazioni API REST nei percorsi utente di Azure AD B2C come convalida dell'input utente.For more information, see Walkthrough: Integrate REST API claims exchanges in your Azure AD B2C user journey as validation on user input.

Lo scenario è che quando un utente esegue la modifica di un profilo, si desidera:The scenario is that when a user performs a profile edit, we want to:

  1. Cercare l'utente in un sistema esterno.Look up the user in an external system.
  2. Ottenere la città in cui tale utente è registrato.Get the city where that user is registered.
  3. Restituire tale attributo all'applicazione come un'attestazione.Return that attribute to the application as a claim.

PrerequisitiPrerequisites

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 configurata una funzione di Azure che riceve un'attestazione denominata email e quindi restituisce l'attestazione city con il valore assegnato di Redmond.We have set up an Azure function that receives a claim called email, and then returns the claim city with the assigned value of Redmond. La funzione di Azure di esempio è disponibile in GitHub.The sample Azure function is on GitHub.

L'attestazione userMessage restituita dalla funzione di Azure è facoltativa in questo contesto e verrà ignorata dal framework dell'esperienza di gestione delle identità.The userMessage claim that the Azure function returns is optional in this context, and the IEF will ignore it. Può essere usata come messaggio passato all'applicazione e presentata all'utente in un secondo momento.You can potentially use it as a message passed to the application and presented to the user later.

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

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

return request.CreateResponse<ResponseContent>(
    HttpStatusCode.OK,
    new ResponseContent
    {
        version = "1.0.0",
        status = (int) HttpStatusCode.OK,
        userMessage = "User Found",
        city = "Redmond"
    },
    new JsonMediaTypeFormatter(),
    "application/json");

Un'app per le funzioni di Azure semplifica il recupero dell'URL della funzione, che include l'identificatore della funzione specifica.An Azure function app makes it easy to get the function URL, which includes the identifier of the specific function. In questo caso l'URL è: https://wingtipb2cfuncs.azurewebsites.net/api/LookUpLoyaltyWebHook?code=MQuG7BIE3eXBaCZ/YCfY1SHabm55HEphpNLmh1OP3hdfHkvI2QwPrw==.In this case, the URL is: https://wingtipb2cfuncs.azurewebsites.net/api/LookUpLoyaltyWebHook?code=MQuG7BIE3eXBaCZ/YCfY1SHabm55HEphpNLmh1OP3hdfHkvI2QwPrw==. È possibile usarlo per il test.You can use it for testing.

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 TrustFrameworExtensions.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 <ClaimsProvider>.Open the TrustFrameworkExtensions.xml file and add the following XML snippet inside the <ClaimsProvider> 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-LookUpLoyaltyWebHook">
            <DisplayName>Check LookUpLoyalty 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/LookUpLoyaltyWebHook?code=MQuG7BIE3eXBaCZ/YCfY1SHabm55HEphpNLmh1OP3hdfHkvI2QwPrw==</Item>
                <Item Key="AuthenticationType">None</Item>
                <Item Key="SendClaimsIn">Body</Item>
            </Metadata>
            <InputClaims>
                <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="email" />
            </InputClaims>
            <OutputClaims>
                <OutputClaim ClaimTypeReferenceId="city" PartnerClaimType="city" />
            </OutputClaims>
            <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
        </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 attestazione email.In this example, the contents of the claim givenName will be sent to the REST service as the claim email.

L'elemento <OutputClaims> definisce le attestazioni che il framework dell'esperienza di gestione delle identità deve ricevere dal servizio REST.The <OutputClaims> element defines the claims that the IEF will expect from the REST service. Indipendentemente dal numero di attestazioni ricevute, il framework dell'esperienza di gestione delle identità usa soltanto le attestazioni qui indicate.Regardless of the number of claims that are received, the IEF will use only those identified here. In questo esempio viene eseguito il mapping dell'attestazione ricevuta come city a un'attestazione del framework dell'esperienza di gestione delle identità denominata city.In this example, a claim received as city will be mapped to an IEF claim called city.

Passaggio 3: Aggiungere la nuova attestazione city allo schema del file TrustFrameworkExtensions.xmlStep 3: Add the new claim city to the schema of your TrustFrameworkExtensions.xml file

L'attestazione city non è ancora definita nello schema.The claim city is not yet defined anywhere in our schema. In tal caso, aggiungere una definizione all'interno dell'elemento <BuildingBlocks>.So, add a definition inside the element <BuildingBlocks>. È possibile trovare questo elemento all'inizio del file TrustFrameworkExtensions.xml.You can find this element at the beginning of the TrustFrameworkExtensions.xml file.

<BuildingBlocks>
    <!--The claimtype city must be added to the TrustFrameworkPolicy-->
    <!-- You can add new claims in the BASE file Section III, or in the extensions file-->
    <ClaimsSchema>
        <ClaimType Id="city">
            <DisplayName>City</DisplayName>
            <DataType>string</DataType>
            <UserHelpText>Your city</UserHelpText>
            <UserInputType>TextBox</UserInputType>
        </ClaimType>
    </ClaimsSchema>
</BuildingBlocks>

Passaggio 4: Includere lo scambio di attestazioni del servizio REST come passaggio di orchestrazione nel percorso utente di modifica del profilo nel file TrustFrameworkExtensions.xmlStep 4: Include the REST service claims exchange as an orchestration step in your profile edit user journey in TrustFrameworkExtensions.xml

Aggiungere un passaggio al percorso utente di modifica del profilo, dopo che l'utente è stato autenticato (passaggi di orchestrazione da 1 a 4 riportati nel seguente XML) e che ha specificato le informazioni sul profilo aggiornato (passaggio 5).Add a step to the profile edit user journey, after the user has been authenticated (orchestration steps 1-4 in the following XML) and the user has provided the updated profile information (step 5).

Nota

In molti casi d'uso la chiamata all'API REST può essere usata come passaggio di orchestrazione.There are many use cases where the REST API call can be used as an orchestration step. Come passaggio di orchestrazione, può essere usata come aggiornamento a un sistema esterno dopo che un utente ha completato un'attività, come una prima registrazione o un aggiornamento del profilo per sincronizzare le informazioni.As an orchestration step, it can be used as an update to an external system after a user has successfully completed a task like first-time registration, or as a profile update to keep information synchronized. In questo caso viene usata per incrementare le informazioni fornite all'applicazione dopo la modifica del profilo.In this case, it's used to augment the information provided to the application after the profile edit.

Copiare il codice XML del percorso utente di modifica del profilo dal file TrustFrameworkBase.xml al file TrustFrameworkExtensions.xml all'interno dell'elemento <UserJourneys>.Copy the profile edit user journey XML code from the TrustFrameworkBase.xml file to your TrustFrameworkExtensions.xml file inside the <UserJourneys> element. Eseguire quindi la modifica indicata nel passaggio 6.Then make the modification under step 6.

<OrchestrationStep Order="6" Type="ClaimsExchange">
    <ClaimsExchanges>
        <ClaimsExchange Id="GetLoyaltyData" TechnicalProfileReferenceId="AzureFunctions-LookUpLoyaltyWebHook" />
    </ClaimsExchanges>
</OrchestrationStep>

Importante

Se l'ordine non corrisponde alla versione usata, assicurarsi di inserire il codice come passaggio prima del ClaimsExchangetipoSendClaims.If the order does not match your version, make sure that you insert the code as the step before the ClaimsExchange type SendClaims.

Il codice XML finale per il percorso utente dovrebbe essere simile al seguente:The final XML for the user journey should look like this:

<UserJourney Id="ProfileEdit">
    <OrchestrationSteps>
        <OrchestrationStep Order="1" Type="ClaimsProviderSelection" ContentDefinitionReferenceId="api.idpselections">
            <ClaimsProviderSelections>
                <ClaimsProviderSelection TargetClaimsExchangeId="FacebookExchange" />
                <ClaimsProviderSelection TargetClaimsExchangeId="LocalAccountSigninEmailExchange" />
            </ClaimsProviderSelections>
        </OrchestrationStep>
        <OrchestrationStep Order="2" Type="ClaimsExchange">
            <ClaimsExchanges>
                <ClaimsExchange Id="FacebookExchange" TechnicalProfileReferenceId="Facebook-OAUTH" />
                <ClaimsExchange Id="LocalAccountSigninEmailExchange" TechnicalProfileReferenceId="SelfAsserted-LocalAccountSignin-Email" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <OrchestrationStep Order="3" Type="ClaimsExchange">
            <Preconditions>
                <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
                    <Value>authenticationSource</Value>
                    <Value>localAccountAuthentication</Value>
                    <Action>SkipThisOrchestrationStep</Action>
                </Precondition>
            </Preconditions>
            <ClaimsExchanges>
                <ClaimsExchange Id="AADUserRead" TechnicalProfileReferenceId="AAD-UserReadUsingAlternativeSecurityId" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <OrchestrationStep Order="4" Type="ClaimsExchange">
            <Preconditions>
                <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
                    <Value>authenticationSource</Value>
                    <Value>socialIdpAuthentication</Value>
                    <Action>SkipThisOrchestrationStep</Action>
                </Precondition>
            </Preconditions>
            <ClaimsExchanges>
                <ClaimsExchange Id="AADUserReadWithObjectId" TechnicalProfileReferenceId="AAD-UserReadUsingObjectId" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <OrchestrationStep Order="5" Type="ClaimsExchange">
            <ClaimsExchanges>
                <ClaimsExchange Id="B2CUserProfileUpdateExchange" TechnicalProfileReferenceId="SelfAsserted-ProfileUpdate" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <!-- Add a step 6 to the user journey before the JWT token is created-->
        <OrchestrationStep Order="6" Type="ClaimsExchange">
            <ClaimsExchanges>
                <ClaimsExchange Id="GetLoyaltyData" TechnicalProfileReferenceId="AzureFunctions-LookUpLoyaltyWebHook" />
            </ClaimsExchanges>
        </OrchestrationStep>
        <OrchestrationStep Order="7" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
    </OrchestrationSteps>
    <ClientDefinition ReferenceId="DefaultWeb" />
</UserJourney>

Passaggio 5: Aggiungere l'attestazione city al file dei criteri relying party in modo che l'attestazione venga inviata all'applicazioneStep 5: Add the claim city to your relying party policy file so the claim is sent to your application

Modificare il file relying party (RP) ProfileEdit.xml e l'elemento <TechnicalProfile Id="PolicyProfile"> per aggiungere quanto segue: <OutputClaim ClaimTypeReferenceId="city" />.Edit your ProfileEdit.xml relying party (RP) file and modify the <TechnicalProfile Id="PolicyProfile"> element to add the following: <OutputClaim ClaimTypeReferenceId="city" />.

Dopo aver aggiunto la nuova attestazione, il profilo tecnico avrà un aspetto simile al seguente:After you add the new claim, the technical profile looks like this:

<DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="city" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
</TechnicalProfile>

Passaggio 6: Caricare le modifiche ed eseguire un testStep 6: Upload your changes and test

Sovrascrivere le versioni esistenti dei criteri.Overwrite the existing versions of the policy.

  1. (Facoltativo) Salvare, scaricandola, la versione esistente del file delle estensioni prima di procedere.(Optional:) Save the existing version (by downloading) of your extensions file before you proceed. Per tenere bassa la complessità iniziale, evitare di caricare più versioni del file delle estensioni.To keep the initial complexity low, we recommend that you do not upload multiple versions of the extensions file.
  2. (Facoltativo) Rinominare la nuova versione dell'ID dei criteri del file di modifica dei criteri modificando...PolicyId="B2C_1A_TrustFrameworkProfileEdit".(Optional:) Rename the new version of the policy ID for the policy edit file by changing PolicyId="B2C_1A_TrustFrameworkProfileEdit".
  3. Caricare il file delle estensioni.Upload the extensions file.
  4. Caricare il file RP di modifica dei criteri.Upload the policy edit RP file.
  5. Usare Esegui adesso per testare i criteri.Use Run Now to test the policy. Esaminare il token restituito dal framework dell'esperienza di gestione delle identità all'applicazione.Review the token that the IEF returns to the application.

Se tutte le impostazioni sono corrette, il token include la nuova attestazione city, con il valore Redmond.If everything is set up correctly, the token will include the new claim city, with the value Redmond.

{
  "exp": 1493053292,
  "nbf": 1493049692,
  "ver": "1.0",
  "iss": "https://login.microsoftonline.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "sub": "a58e7c6c-7535-4074-93da-b0023fbaf3ac",
  "aud": "4e87c1dd-e5f5-4ac8-8368-bc6a98751b8b",
  "acr": "b2c_1a_trustframeworkprofileedit",
  "nonce": "defaultNonce",
  "iat": 1493049692,
  "auth_time": 1493049692,
  "city": "Redmond"
}

Passaggi successiviNext steps

Usare un'API REST come passaggio di convalidaUse a REST API as a validation step

Cambiare la modifica del profilo per raccogliere altre informazioni dagli utentiModify the profile edit to gather additional information from your users