Een API-connector toevoegen aan een gebruikersstroom voor registratie

  • Artikel

Voordat u begint, gebruikt u de selector Een beleidstype kiezen om het type beleid te kiezen dat u instelt. U kunt in Azure Active Directory B2C op twee manieren definiëren hoe gebruikers met uw toepassingen communiceren: via vooraf gedefinieerde gebruikersstromen of via volledig configureerbaar aangepast beleid. De stappen die in dit artikel zijn vereist, verschillen voor elke methode.

Als ontwikkelaar of IT-beheerder kunt u API-connectors gebruiken om uw aanmeldingsgebruikersstromen te integreren met REST API's om de registratie-ervaring aan te passen en te integreren met externe systemen. Aan het einde van dit scenario kunt u een Azure AD B2C-gebruikersstroom maken die communiceert met REST API-services om uw registratie-ervaringen te wijzigen.

U kunt een API-eindpunt maken met behulp van een van onze voorbeelden.

In dit scenario voegen we de mogelijkheid toe dat gebruikers een loyaliteitsnummer invoeren op de registratiepagina van Azure AD B2C. De REST API valideert of de combinatie van e-mail en loyaliteitsnummer is toegewezen aan een promotiecode. Als de REST API een promotiecode voor deze gebruiker vindt, wordt deze geretourneerd naar Azure AD B2C. Ten slotte wordt de promotiecode ingevoegd in de tokenclaims die de toepassing kan gebruiken.

U kunt de interactie ook ontwerpen als een indelingsstap. Dit is geschikt wanneer de REST API geen gegevens op het scherm valideert en altijd claims retourneert. Zie Walkthrough: Rest API-claims in uw Azure AD B2C-gebruikerstraject integreren als een indelingsstap voor meer informatie.

Vereisten

Een API-connector maken

Als u een API-connector wilt gebruiken, maakt u eerst de API-connector en schakelt u deze vervolgens in in een gebruikersstroom.

  1. Meld u aan bij de Azure-portal.

  2. Selecteer onder Azure-services de optie Azure AD B2C.

  3. Selecteer API-connectors en selecteer vervolgens Nieuwe API-connector.

    Screenshot of basic configuration for an API connector

  4. Geef een weergavenaam op voor de aanroep. Bijvoorbeeld: Gebruikersgegevens valideren.

  5. Geef de eindpunt-URL op voor de API-aanroep.

  6. Kies het verificatietype en configureer de verificatiegegevens voor het aanroepen van uw API. Meer informatie over het beveiligen van uw API-Verbinding maken or.

    Screenshot of authentication configuration for an API connector

  7. Selecteer Opslaan.

De aanvraag die naar uw API is verzonden

Een API-connector wordt gerealiseerd als een HTTP POST-aanvraag en verzendt gebruikerskenmerken ('claims') als sleutel-waardeparen in een JSON-hoofdtekst. Kenmerken worden geserialiseerd op dezelfde manier als gebruikerseigenschappen van Microsoft Graph .

Voorbeeldaanvraag

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

Alleen gebruikerseigenschappen en aangepaste kenmerken die worden vermeld in de azure AD B2C-gebruikerskenmerken>zijn beschikbaar om in de aanvraag te worden verzonden.

Aangepaste kenmerken bestaan in de indeling extension_<extensions-app-id>_CustomAttribute in de map. Uw API verwacht claims in dezelfde geserialiseerde indeling te ontvangen. Zie Aangepaste kenmerken definiëren in Azure AD B2C voor meer informatie over aangepaste kenmerken.

Bovendien worden deze claims meestal verzonden in alle aanvragen:

  • Landinstellingen van de gebruikersinterface ('ui_locales'): een of meer landinstellingen van eindgebruikers zoals geconfigureerd op hun apparaat. Dit kan worden gebruikt door uw API om geinternationaliseerde antwoorden te retourneren.
  • Stap ('stap'): de stap of het punt in de gebruikersstroom waarvoor de API-connector is aangeroepen. Waarden zijn onder andere:
    • PostFederationSignup - komt overeen met 'Na federatie met een id-provider tijdens registratie'
    • PostAttributeCollection - komt overeen met 'Voordat de gebruiker wordt gemaakt'
    • PreTokenIssuance - komt overeen met 'Voordat het token wordt verzonden (preview)'. Meer informatie over deze stap
  • Client-id ('client_id'): de appId waarde van de toepassing waarnaar een eindgebruiker zich in een gebruikersstroom verificeert. Dit is niet de brontoepassing appId in toegangstokens.
  • E-mailadres ('e-mail') of identiteiten ('identiteiten') - deze claims kunnen door uw API worden gebruikt om de eindgebruiker te identificeren die bij de toepassing wordt geverifieerd.

Belangrijk

Als een claim geen waarde heeft op het moment dat het API-eindpunt wordt aangeroepen, wordt de claim niet naar de API verzonden. Uw API moet zijn ontworpen om expliciet het geval te controleren en te verwerken waarin een claim zich niet in de aanvraag bevindt.

De API-connector inschakelen in een gebruikersstroom

Volg deze stappen om een API-connector toe te voegen aan een gebruikersstroom voor registratie.

  1. Meld u aan bij de Azure-portal.

  2. Selecteer onder Azure-services de optie Azure AD B2C.

  3. Selecteer Gebruikersstromen en selecteer vervolgens de gebruikersstroom waaraan u de API-connector wilt toevoegen.

  4. Selecteer API-connectors en selecteer vervolgens de API-eindpunten die u wilt aanroepen in de volgende stappen in de gebruikersstroom:

    • Na het federeren met een id-provider tijdens het registreren
    • Voordat u de gebruiker maakt
    • Voordat u het token verzendt (preview)

    Selecting an API connector for a step in the user flow

  5. Selecteer Opslaan.

Deze stappen bestaan alleen voor registreren en aanmelden (aanbevolen) en registreren (aanbevolen), maar zijn alleen van toepassing op het registratiegedeelte van de ervaring.

Na het federeren met een id-provider tijdens het registreren

Een API-connector bij deze stap in het registratieproces wordt onmiddellijk aangeroepen nadat de gebruiker zich heeft geverifieerd bij een id-provider (zoals Google, Facebook en Microsoft Entra ID). Deze stap gaat vooraf aan de pagina voor het verzamelen van kenmerken. Dit is het formulier dat aan de gebruiker wordt gepresenteerd om gebruikerskenmerken te verzamelen. Deze stap wordt niet aangeroepen als een gebruiker zich registreert bij een lokaal account.

Voorbeeldaanvraag verzonden naar de API in deze stap

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

De exacte claims die naar de API worden verzonden, zijn afhankelijk van de informatie die door de id-provider wordt verstrekt. 'e-mail' wordt altijd verzonden.

Verwachte antwoordtypen van de web-API in deze stap

Wanneer de web-API een HTTP-aanvraag van Microsoft Entra-id ontvangt tijdens een gebruikersstroom, kan deze antwoorden worden geretourneerd:

  • Vervolgantwoord
  • Blokkeringsreactie

Vervolgantwoord

Een vervolgantwoord geeft aan dat de gebruikersstroom moet doorgaan naar de volgende stap: de pagina voor het verzamelen van kenmerken.

In een vervolgantwoord kan de API claims retourneren. Als een claim wordt geretourneerd door de API, doet de claim het volgende:

  • Vult het invoerveld vooraf in op de pagina voor het verzamelen van kenmerken.

Bekijk een voorbeeld van een vervolgantwoord.

Blokkeringsreactie

Een blokkerend antwoord sluit de gebruikersstroom af. Het kan doelloos worden uitgegeven door de API om de voortzetting van de gebruikersstroom te stoppen door een blokpagina weer te geven aan de gebruiker. Op de blokpagina wordt de userMessage opgegeven door de API weergegeven.

Bekijk een voorbeeld van een blokkerend antwoord.

Voordat u de gebruiker maakt

Een API-connector bij deze stap in het registratieproces wordt aangeroepen na de pagina voor het verzamelen van kenmerken, als deze is opgenomen. Deze stap wordt altijd aangeroepen voordat een gebruikersaccount wordt gemaakt.

Voorbeeldaanvraag verzonden naar de API in deze stap

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

De claims die naar de API worden verzonden, zijn afhankelijk van de gegevens die worden verzameld van de gebruiker of worden verstrekt door de id-provider.

Verwachte antwoordtypen van de web-API in deze stap

Wanneer de web-API een HTTP-aanvraag van Microsoft Entra-id ontvangt tijdens een gebruikersstroom, kan deze antwoorden worden geretourneerd:

  • Vervolgantwoord
  • Blokkeringsreactie
  • Validatieantwoord

Vervolgantwoord

Een vervolgantwoord geeft aan dat de gebruikersstroom moet doorgaan naar de volgende stap: de gebruiker maken in de map.

In een vervolgantwoord kan de API claims retourneren. Als een claim wordt geretourneerd door de API, doet de claim het volgende:

  • Hiermee wordt een waarde overschreven die al is opgegeven door een gebruiker op de pagina voor het verzamelen van kenmerken.

Als u claims wilt schrijven naar de directory bij aanmelding die niet van de gebruiker moeten worden verzameld, moet u nog steeds de claims selecteren onder Gebruikerskenmerken van de gebruikersstroom. Deze vraagt de gebruiker standaard om waarden, maar u kunt aangepaste JavaScript of CSS gebruiken om de invoervelden van een eindgebruiker te verbergen.

Bekijk een voorbeeld van een vervolgantwoord.

Blokkeringsreactie

Een blokkerend antwoord sluit de gebruikersstroom af. Het kan doelloos worden uitgegeven door de API om de voortzetting van de gebruikersstroom te stoppen door een blokpagina weer te geven aan de gebruiker. Op de blokpagina wordt de userMessage opgegeven door de API weergegeven.

Bekijk een voorbeeld van een blokkerend antwoord.

Validatiefoutantwoord

Wanneer de API reageert met een antwoord op validatiefouten, blijft de gebruikersstroom op de pagina kenmerkverzameling en wordt er een userMessage weergegeven voor de gebruiker. De gebruiker kan het formulier vervolgens bewerken en opnieuw indienen. Dit type antwoord kan worden gebruikt voor invoervalidatie.

Bekijk een voorbeeld van een validatiefoutreactie.

Voordat u het token verzendt (preview)

Belangrijk

API-connectors die in deze stap worden gebruikt, zijn in preview. Zie Productvoorwaarden voor onlineservices voor meer informatie over previews.

Een API-connector bij deze stap wordt aangeroepen wanneer een token op het punt staat te worden uitgegeven tijdens aanmeldingen en aanmeldingen. Een API-connector voor deze stap kan worden gebruikt om het token te verrijken met claimwaarden uit externe bronnen.

Voorbeeldaanvraag verzonden naar de API in deze stap

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

De claims die naar de API worden verzonden, zijn afhankelijk van de informatie die voor de gebruiker is gedefinieerd.

Verwachte antwoordtypen van de web-API in deze stap

Wanneer de web-API een HTTP-aanvraag van Microsoft Entra-id ontvangt tijdens een gebruikersstroom, kan deze antwoorden worden geretourneerd:

  • Vervolgantwoord

Vervolgantwoord

Een vervolgantwoord geeft aan dat de gebruikersstroom moet doorgaan naar de volgende stap: het token uitgeven.

In een vervolgantwoord kan de API aanvullende claims retourneren. Een claim die wordt geretourneerd door de API die u wilt retourneren in het token, moet een ingebouwde claim zijn of zijn gedefinieerd als een aangepast kenmerk en moet worden geselecteerd in de configuratie van toepassingsclaims van de gebruikersstroom.

De claimwaarde in het token is de waarde die wordt geretourneerd door de API, niet de waarde in de map. Sommige claimwaarden kunnen niet worden overschreven door het API-antwoord. Claims die door de API kunnen worden geretourneerd, komen overeen met de set die is gevonden onder Gebruikerskenmerken met uitzondering van email.

Bekijk een voorbeeld van een vervolgantwoord.

Notitie

De API wordt alleen aangeroepen tijdens een eerste verificatie. Wanneer u vernieuwingstokens gebruikt om op de achtergrond nieuwe toegangs- of id-tokens te verkrijgen, bevat het token de waarden die tijdens de eerste verificatie worden geëvalueerd.

Voorbeeldantwoorden

Voorbeeld van een vervolgantwoord

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
}
Parameter Type Vereist Beschrijving
versie Tekenreeks Ja De versie van uw API.
action Tekenreeks Ja Waarde moet zijn Continue.
<builtInUserAttribute> <kenmerktype> Nee Geretourneerde waarden kunnen waarden overschrijven die zijn verzameld van een gebruiker.
<extension_{extensions-app-id}_CustomAttribute> <kenmerktype> Nee De claim hoeft niet te bevatten _<extensions-app-id>_, het is optioneel. Geretourneerde waarden kunnen waarden overschrijven die zijn verzameld van een gebruiker.

Voorbeeld van een blokkerend antwoord

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",
}
Parameter Type Vereist Beschrijving
versie Tekenreeks Ja De versie van uw API.
action Tekenreeks Ja Waarde moet zijn ShowBlockPage
userMessage Tekenreeks Ja Het bericht dat wordt weergegeven aan de gebruiker.

Eindgebruikerservaring met een blokkerend antwoord

Example of a blocking response

Voorbeeld van een validatiefoutantwoord

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."
}
Parameter Type Vereist Beschrijving
versie Tekenreeks Ja De versie van uw API.
action Tekenreeks Ja Waarde moet zijn ValidationError.
status Geheel getal/tekenreeks Ja Moet een waarde 400zijn, of "400" voor een ValidationError-antwoord.
userMessage Tekenreeks Ja Het bericht dat wordt weergegeven aan de gebruiker.

Notitie

HTTP-statuscode moet '400' zijn, naast de 'status'-waarde in de hoofdtekst van het antwoord.

Eindgebruikerservaring met een validatiefoutreactie

Example of a validation-error response

Een REST API-eindpunt voorbereiden

Voor deze procedure moet u een REST API hebben die controleert of een e-mailadres is geregistreerd in uw back-endsysteem met een loyaliteits-id. Indien geregistreerd, moet de REST API een registratiepromotiecode retourneren, die de klant kan gebruiken om goederen in uw toepassing te kopen. Anders moet de REST API een HTTP 409-foutbericht retourneren: 'Loyaliteits-id '{loyaliteits-id}' is niet gekoppeld aan het e-mailadres {email}.'

De volgende JSON-code illustreert de gegevens die Azure AD B2C naar uw REST API-eindpunt verzendt.

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

Zodra uw REST API de gegevens valideert, moet deze een HTTP 200 (OK) retourneren met de volgende JSON-gegevens:

{
    "promoCode": "24534"
}

Als de validatie is mislukt, moet de REST API een HTTP 409 (Conflict) retourneren met het userMessage JSON-element. De IEF verwacht de userMessage claim die de REST API retourneert. Deze claim wordt weergegeven als een tekenreeks voor de gebruiker als de validatie mislukt.

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

De installatie van het REST API-eindpunt valt buiten het bereik van dit artikel. We hebben een Azure Functions-voorbeeld gemaakt. U hebt toegang tot de volledige Azure-functiecode op GitHub.

Claims definiëren

Een claim maakt tijdelijke opslag van gegevens mogelijk tijdens de uitvoering van een Azure AD B2C-beleid. U kunt claims declareren in de sectie claimsschema .

  1. Open het uitbreidingsbestand van uw beleid. Bijvoorbeeld SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Zoek element BuildingBlocks. Als het element niet aanwezig is, voegt u het toe.
  3. Zoek naar het element ClaimsSchema. Als het element niet aanwezig is, voegt u het toe.
  4. Voeg de volgende claims toe aan het element 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>

Het technische profiel van de RESTful-API toevoegen

Een restful technisch profiel biedt ondersteuning voor communicatie met uw eigen RESTful-service. Azure AD B2C verzendt gegevens naar de RESTful-service in een InputClaims verzameling en ontvangt gegevens terug in een OutputClaims verzameling. Zoek het element ClaimsProviders en voeg als volgt een nieuwe claimprovider toe:

<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 dit voorbeeld wordt de userLanguage service verzonden naar de REST-service als lang binnen de JSON-nettolading. De waarde van de userLanguage claim bevat de huidige gebruikerstaal-id. Zie claim resolver voor meer informatie.

Het technische profiel van de RESTful-API configureren

Nadat u uw REST API hebt geïmplementeerd, stelt u de metagegevens van het REST-ValidateProfile technische profiel in om uw eigen REST API weer te geven, waaronder:

  • ServiceUrl. Stel de URL van het REST API-eindpunt in.
  • SendClaimsIn. Geef op hoe de invoerclaims worden verzonden naar de RESTful-claimprovider.
  • AuthenticationType. Stel het type verificatie in dat wordt uitgevoerd door de RESTful-claimprovider.
  • AllowInsecureAuthInProduction. Zorg ervoor dat u in een productieomgeving deze metagegevens instelt op true

Zie de metagegevens van het RESTful-technische profiel voor meer configuraties.

De bovenstaande AuthenticationType opmerkingen en AllowInsecureAuthInProduction geef wijzigingen op die u moet aanbrengen wanneer u naar een productieomgeving gaat. Zie RESTful API beveiligen voor meer informatie over het beveiligen van uw RESTful-API's voor productie.

De gebruikersinvoer valideren

Als u het loyaliteitsnummer van de gebruiker wilt verkrijgen tijdens de registratie, moet u de gebruiker toestaan om deze gegevens op het scherm in te voeren. Voeg de loyaltyId-uitvoerclaim toe aan de registratiepagina door deze toe te voegen aan het element van OutputClaims het bestaande technische aanmeldingsprofiel. Geef de volledige lijst met uitvoerclaims op om de volgorde te bepalen waarin de claims op het scherm worden weergegeven.

Voeg de technische validatieprofielverwijzing toe aan het technische registratieprofiel, dat het REST-ValidateProfileaanroept. Het nieuwe technische validatieprofiel wordt toegevoegd aan het begin van de <ValidationTechnicalProfiles> verzameling die is gedefinieerd in het basisbeleid. Dit gedrag betekent dat Azure AD B2C pas na een geslaagde validatie het account in de directory maakt.

  1. Ga naar het element ClaimsProviders. Voeg als volgt een nieuwe claimprovider toe:

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

Een claim opnemen in het token

Als u de promotiecodeclaim wilt terugsturen naar de relying party-toepassing, voegt u een uitvoerclaim toe aan het SocialAndLocalAccounts/SignUpOrSignIn.xml bestand. Met de uitvoerclaim kan de claim na een geslaagde gebruikersbeleving aan het token worden toegevoegd en naar de toepassing worden verzonden. Wijzig het technische profielelement in de sectie relying party om de promoCode als uitvoerclaim toe te voegen.

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

Het aangepaste beleid testen

  1. Meld u aan bij de Azure-portal.
  2. Als u toegang hebt tot meerdere tenants, selecteert u het pictogram Instellingen in het bovenste menu om over te schakelen naar uw Microsoft Entra ID-tenant in het menu Mappen en abonnementen.
  3. Kies linksboven in de Azure Portal Alle services, zoek App-registraties en selecteer deze.
  4. Selecteer Identity Experience Framework.
  5. Selecteer Aangepast beleid uploaden en upload vervolgens de beleidsbestanden die u hebt gewijzigd: TrustFrameworkExtensions.xml en SignUpOrSignin.xml.
  6. Selecteer het registratie- of aanmeldingsbeleid dat u hebt geüpload en klik op de knop Nu uitvoeren .
  7. U moet zich kunnen registreren met een e-mailadres.
  8. Klik op de koppeling Nu registreren .
  9. Typ 1234 in uw loyaliteits-id en klik op Doorgaan. Op dit moment krijgt u een validatiefoutbericht.
  10. Ga naar een andere waarde en klik op Doorgaan.
  11. Het token dat naar uw toepassing wordt geretourneerd, bevat de promoCode-claim.
{
  "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"
  ...
}

Aanbevolen procedures en probleemoplossing

Serverloze cloudfuncties gebruiken

Serverloze functies, zoals HTTP-triggers in Azure Functions, bieden een manier om API-eindpunten te maken voor gebruik met de API-connector. U kunt de serverloze cloudfunctie gebruiken om bijvoorbeeld validatielogica uit te voeren en registraties te beperken tot specifieke e-maildomeinen. De serverloze cloudfunctie kan ook andere web-API's, gegevensarchieven en andere cloudservices aanroepen en aanroepen voor complexe scenario's.

Aanbevolen procedures

U moet het volgende hebben gedaan:

  • Uw API volgt de API-aanvraag- en antwoordcontracten zoals hierboven beschreven.
  • De eindpunt-URL van de API-connector verwijst naar het juiste API-eindpunt.
  • Uw API controleert expliciet op null-waarden van ontvangen claims waarvan deze afhankelijk is.
  • Uw API implementeert een verificatiemethode die wordt beschreven in veilig uw API-Verbinding maken or.
  • Uw API reageert zo snel mogelijk om een vloeiende gebruikerservaring te garanderen.
    • Azure AD B2C wacht maximaal 20 seconden om een antwoord te ontvangen. Als er geen wordt ontvangen, wordt er nog een poging (opnieuw) geprobeerd om uw API aan te roepen.
    • Als u een serverloze functie of schaalbare webservice gebruikt, gebruikt u een hostingabonnement dat de API 'wakker' of 'warm' in productie houdt. Voor Azure Functions is het raadzaam om minimaal het Premium-abonnement in productie te gebruiken.
  • Hoge beschikbaarheid van uw API garanderen.
  • De prestaties van downstream-API's, databases of andere afhankelijkheden van uw API bewaken en optimaliseren.

Belangrijk

Uw eindpunten moeten voldoen aan de Azure AD B2C-beveiligingsvereisten. Oudere TLS-versies en -coderingen zijn afgeschaft. Zie Vereisten voor Azure AD B2C TLS en suites met coderingsmethoden voor meer informatie.

Logboekregistratie gebruiken

Over het algemeen is het handig om de hulpprogramma's voor logboekregistratie te gebruiken die zijn ingeschakeld door uw web-API-service, zoals Application Insights, om uw API te bewaken op onverwachte foutcodes, uitzonderingen en slechte prestaties.

  • Controleer op HTTP-statuscodes die geen HTTP 200 of 400 zijn.
  • Een HTTP-statuscode van 401 of 403 geeft meestal aan dat er een probleem is met uw verificatie. Controleer de verificatielaag van uw API en de bijbehorende configuratie in de API-connector.
  • Gebruik zo nodig agressievere niveaus van logboekregistratie (bijvoorbeeld tracering of foutopsporing).
  • Bewaak uw API voor lange reactietijden.

Daarnaast registreert Azure AD B2C metagegevens over de API-transacties die plaatsvinden tijdens gebruikersverificaties via een gebruikersstroom. Ga als volgt te werk om deze te vinden:

  1. Ga naar Azure AD B2C.
  2. Onder Activiteiten selecteert u Controlelogboeken.
  3. Filter de lijstweergave: Selecteer voor Datum het gewenste tijdsinterval en selecteer voor Activiteit een API die is aangeroepen als onderdeel van een gebruikersstroom.
  4. Afzonderlijke logboeken inspecteren. Elke rij vertegenwoordigt een API-connector die wordt aangeroepen tijdens een gebruikersstroom. Als een API-aanroep mislukt en er een nieuwe poging wordt uitgevoerd, wordt deze nog steeds weergegeven als één rij. Hiermee numberOfAttempts wordt aangegeven hoe vaak uw API is aangeroepen. Deze waarde kan 1of 2. Andere informatie over de API-aanroep wordt in de logboeken beschreven.

Example of an API connector transaction during user authentication

Serverloze cloudfuncties gebruiken

Serverloze cloudfuncties, zoals HTTP-triggers in Azure Functions, bieden een eenvoudige, maximaal beschikbare, krachtige manier om API-eindpunten te maken voor gebruik als API-connectors.

Aanbevolen procedures

U moet het volgende hebben gedaan:

  • Uw API controleert expliciet op null-waarden van ontvangen claims waarvan deze afhankelijk is.
  • Uw API implementeert een verificatiemethode die wordt beschreven in veilig uw API-Verbinding maken or.
  • Uw API reageert zo snel mogelijk om een vloeiende gebruikerservaring te garanderen.
    • Als u een serverloze functie of schaalbare webservice gebruikt, gebruikt u een hostingabonnement dat de API 'wakker' of 'warm' in productie houdt. Voor Azure Functions is het raadzaam om minimaal het Premium-abonnement te gebruiken
  • Hoge beschikbaarheid van uw API garanderen.
  • De prestaties van downstream-API's, databases of andere afhankelijkheden van uw API bewaken en optimaliseren.

Belangrijk

Uw eindpunten moeten voldoen aan de Azure AD B2C-beveiligingsvereisten. Oudere TLS-versies en -coderingen zijn afgeschaft. Zie Vereisten voor Azure AD B2C TLS en suites met coderingsmethoden voor meer informatie.

Logboekregistratie gebruiken

Over het algemeen is het handig om de hulpprogramma's voor logboekregistratie te gebruiken die zijn ingeschakeld door uw web-API-service, zoals Application Insights, om uw API te bewaken op onverwachte foutcodes, uitzonderingen en slechte prestaties.

  • Controleer op HTTP-statuscodes die geen HTTP 200 of 400 zijn.
  • Een HTTP-statuscode van 401 of 403 geeft meestal aan dat er een probleem is met uw verificatie. Controleer de verificatielaag van uw API en de bijbehorende configuratie in de API-connector.
  • Gebruik zo nodig agressievere niveaus van logboekregistratie (bijvoorbeeld tracering of foutopsporing).
  • Bewaak uw API voor lange reactietijden.

Volgende stappen