Over API-connectors in Azure AD B2C

Artikel
06/01/2023

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.

Overzicht

Als ontwikkelaar of IT-beheerder kunt u API-connectors gebruiken om uw gebruikersstromen voor registratie te integreren met REST API's om de registratie-ervaring aan te passen en te integreren met externe systemen. Met API-connectors kunt u bijvoorbeeld het volgende doen:

Invoergegevens van gebruikers valideren. Valideer op basis van ongeldige of ongeldige gebruikersgegevens. U kunt bijvoorbeeld door de gebruiker verstrekte gegevens valideren op basis van bestaande gegevens in een extern gegevensarchief of een lijst met toegestane waarden. Als dit ongeldig is, kunt u een gebruiker vragen om geldige gegevens op te geven of de gebruiker te blokkeren om door te gaan met de registratiestroom.
Controleer de gebruikersidentiteit. Gebruik een service voor identiteitsverificatie of externe identiteitsgegevensbronnen om een extra beveiligingsniveau toe te voegen aan beslissingen over het maken van accounts.
Integreren met een aangepaste goedkeuringswerkstroom. Maak verbinding met een aangepast goedkeuringssysteem voor het beheren en beperken van het maken van accounts.
Uitbreidingstokens met kenmerken uit externe bronnen. Verrijk tokens met kenmerken over de gebruiker uit bronnen die extern zijn van Azure AD B2C, zoals cloudsystemen, aangepaste gebruikersarchieven, aangepaste machtigingssystemen, verouderde identiteitsservices en meer.
Gebruikerskenmerken overschrijven. Een waarde opnieuw opmaken of toewijzen aan een kenmerk dat van de gebruiker is verzameld. Als een gebruiker bijvoorbeeld de voornaam in alle kleine letters of hoofdletters invoert, kunt u de naam opmaken met alleen de eerste hoofdletter.
Aangepaste bedrijfslogica uitvoeren. U kunt downstreamgebeurtenissen in uw cloudsystemen activeren om pushmeldingen te verzenden, bedrijfsdatabases bij te werken, machtigingen te beheren, databases te controleren en andere aangepaste acties uit te voeren.

Een API-connector biedt Azure AD B2C de informatie die nodig is om het API-eindpunt aan te roepen door de URL van het HTTP-eindpunt en de verificatie voor de API-aanroep te definiëren. Zodra u een API-connector hebt geconfigureerd, kunt u deze inschakelen voor een specifieke stap in een gebruikersstroom. Wanneer een gebruiker die stap in de registratiestroom bereikt, wordt de API-connector aangeroepen en wordt deze geïmplementeerd als een HTTP POST-aanvraag naar uw API, waarbij gebruikersgegevens (claims) als sleutel-waardeparen in een JSON-hoofdtekst worden verzonden. Het API-antwoord kan van invloed zijn op de uitvoering van de gebruikersstroom. Het API-antwoord kan bijvoorbeeld voorkomen dat een gebruiker zich registreert, de gebruiker vragen om informatie opnieuw in te geven of gebruikerskenmerken overschrijven.

Waar u een API-connector in een gebruikersstroom kunt inschakelen

Er zijn drie plaatsen in een gebruikersstroom waar u een API-connector kunt inschakelen:

Na federatie met een id-provider tijdens het registreren : is alleen van toepassing op aanmeldingservaringen
Voordat u de gebruiker maakt : is alleen van toepassing op aanmeldingservaringen
Voordat het token wordt verzonden (preview) - is van toepassing op registraties en aanmeldingen

Een API-connector bij deze stap in het registratieproces wordt aangeroepen direct 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 met een lokaal account. Hier volgen voorbeelden van SCENARIO's voor API-connectors die u in deze stap kunt inschakelen:

Gebruik het e-mailadres of de federatieve identiteit die de gebruiker heeft opgegeven om claims op te zoeken in een bestaand systeem. Retourneer deze claims van het bestaande systeem, vul de pagina van de kenmerkverzameling vooraf in en maak ze beschikbaar om terug te keren in het token.
Implementeer een acceptatie- of blokkeringslijst op basis van sociale identiteit.

Voordat u de gebruiker maakt

Een API-connector in 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. Hier volgen voorbeelden van scenario's die u op dit moment tijdens de registratie kunt inschakelen:

Valideer de invoergegevens van de gebruiker en vraag een gebruiker om gegevens opnieuw in te leveren.
Registratie van een gebruiker blokkeren op basis van gegevens die door de gebruiker zijn ingevoerd.
Controleer de gebruikersidentiteit.
Query's uitvoeren op externe systemen op bestaande gegevens over de gebruiker om deze te retourneren in het token van de toepassing of om deze op te slaan in Microsoft Entra-id.

Voordat het token wordt verzonden (preview)

Notitie

Deze functie is beschikbaar voor openbare preview.

Een API-connector in deze stap in het registratie- of aanmeldingsproces wordt aangeroepen voordat een token wordt uitgegeven. Hier volgen voorbeelden van scenario's die u in deze stap kunt inschakelen:

Het token verrijken met kenmerken over de gebruiker uit andere bronnen dan de directory, waaronder verouderde identiteitssystemen, HR-systemen, externe gebruikersarchieven en meer.
Het token verrijken met groeps- of rolkenmerken die u opslaat en beheert in uw eigen machtigingssysteem.
Claimtransformaties of -manipulaties toepassen op waarden van claims in de directory.

Het Identity Experience Framework, dat ten grondslag valt aan Azure Active Directory B2C (Azure AD B2C), kan worden geïntegreerd met RESTful API's binnen een gebruikerstraject. In dit artikel wordt beschreven hoe u een gebruikersbeleving maakt die communiceert met een RESTful-service met behulp van een technisch RESTful-profiel.

Met Azure AD B2C kunt u uw eigen bedrijfslogica toevoegen aan een gebruikerstraject door uw eigen RESTful-service aan te roepen. Het Identity Experience Framework kan gegevens verzenden en ontvangen van uw RESTful-service om claims uit te wisselen. U kunt bijvoorbeeld:

Externe identiteitsgegevensbron gebruiken om invoergegevens van gebruikers te valideren. U kunt bijvoorbeeld controleren of het e-mailadres dat door de gebruiker is opgegeven, bestaat in de database van uw klant en zo niet, dan kunt u een fout presenteren. U kunt API-connectors net zo goed zien als een manier om uitgaande webhooks te ondersteunen, omdat de aanroep wordt uitgevoerd wanneer een gebeurtenis plaatsvindt, bijvoorbeeld een registratie.
Claims verwerken. Als een gebruiker de voornaam in alle kleine letters of hoofdletters invoert, kan uw REST API de naam opmaken met alleen de eerste hoofdletter en deze terugzetten naar Azure AD B2C. Wanneer u echter een aangepast beleid gebruikt, heeft ClaimsTransformations de voorkeur boven het aanroepen van een RESTful-API.
Gebruikersgegevens dynamisch verrijken door verdere integratie met zakelijke Line-Of-Business-toepassingen. Uw RESTful-service kan het e-mailadres van de gebruiker ontvangen, een query uitvoeren op de database van de klant en het loyaliteitsnummer van de gebruiker retourneren aan Azure AD B2C. Vervolgens kunnen retourclaims worden opgeslagen in het Microsoft Entra-account van de gebruiker, worden geëvalueerd in de volgende indelingsstappen of worden opgenomen in het toegangstoken.
Aangepaste bedrijfslogica uitvoeren. U kunt pushmeldingen verzenden, bedrijfsdatabases bijwerken, een gebruikersmigratieproces uitvoeren, machtigingen beheren, databases controleren en andere werkstromen uitvoeren.

Diagram van de uitwisseling van RESTful-serviceclaims

Notitie

Als er een trage of geen reactie van de RESTful-service is op Azure AD B2C, is de time-out 30 seconden en is het aantal nieuwe pogingen twee keer (wat betekent dat er in totaal 3 pogingen zijn). Op dit moment kunt u de instellingen voor time-outs en het aantal nieuwe pogingen niet configureren.

Een RESTful-service aanroepen

De interactie omvat een claimuitwisseling van informatie tussen de REST API-claims en Azure AD B2C. U kunt de integratie met de RESTful-services op de volgende manieren ontwerpen:

Technisch validatieprofiel. De aanroep van de RESTful-service vindt plaats binnen een technisch validatieprofiel van het opgegeven zelf-gecontroleerde technische profiel of een controleweergave van een weergavebesturingselement voor verificatie. Het technische validatieprofiel valideert de door de gebruiker verstrekte gegevens voordat het gebruikerstraject wordt uitgevoerd. Met het technische validatieprofiel kunt u het volgende doen:
- Claims verzenden naar uw REST API.
- Valideer claims en genereert aangepaste foutberichten die aan de gebruiker worden weergegeven.
- Claims van de REST API terugsturen naar de volgende indelingsstappen.
Claims uitwisselen. Een directe claimuitwisseling kan worden geconfigureerd door rechtstreeks vanuit een indelingsstap van een gebruikerstraject een technisch REST API-profiel aan te roepen. Deze definitie is beperkt tot:
- Claims verzenden naar uw REST API.
- Valideer claims en genereert aangepaste foutberichten die worden geretourneerd naar de toepassing.
- Claims van de REST API terugsturen naar de volgende indelingsstappen.

U kunt aan elke stap in de gebruikersbeleving die is gedefinieerd door een aangepast beleid, een aanroep van een REST-API toevoegen. U kunt bijvoorbeeld een REST-API aanroepen:

Tijdens het aanmelden, net voordat Azure AD B2C de referenties valideert.
Direct na aanmelding.
Voordat Azure AD B2C een nieuw account in de map maakt.
Na Azure AD B2C een nieuw account in de map gemaakt.
Voordat Azure AD B2C een toegangstoken uitgeeft.

Gegevens verzenden

In het technische profiel RESTful bevat het InputClaims element een lijst met claims die naar uw RESTful-service moeten worden verzonden. U kunt de naam van uw claim toewijzen aan de naam die is gedefinieerd in de RESTful-service, een standaardwaarde instellen en claimomzetters gebruiken.

U kunt configureren hoe de invoerclaims worden verzonden naar de RESTful-claimprovider met behulp van het kenmerk SendClaimsIn. De mogelijke waarden zijn:

Hoofdtekst, verzonden in de HTTP POST-aanvraagbody in JSON-indeling.
Formulier, verzonden in de hoofdtekst van de HTTP POST-aanvraag in een indeling met een en-teken en -&sleutelwaarde.
Header, verzonden in de HTTP GET-aanvraagheader.
QueryString, verzonden in de http GET-aanvraagqueryreeks.

Wanneer de optie Hoofdtekst is geconfigureerd, kunt u met het technische profiel van de REST API een complexe JSON-nettolading verzenden naar een eindpunt. Zie Een JSON-nettolading verzenden voor meer informatie.

Gegevens ontvangen

Het OutputClaims element van het technische RESTful-profiel bevat een lijst met claims die door de REST API worden geretourneerd. Mogelijk moet u de naam van de claim die in uw beleid is gedefinieerd toewijzen aan de naam die is gedefinieerd in de REST API. U kunt ook claims opnemen die niet worden geretourneerd door de ID-provider van de REST API, zolang u het kenmerk DefaultValue instelt.

De uitvoerclaims die door de RESTful-claimprovider worden geparseerd, verwachten altijd een platte JSON-hoofdtekst te parseren, zoals:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

De uitvoerclaims moeten eruitzien als het volgende XML-fragment:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Null-waarden verwerken

Een null-waarde in een database wordt gebruikt wanneer de waarde in een kolom onbekend is of ontbreekt. Voeg geen JSON-sleutels met een null waarde toe. In het volgende voorbeeld retourneert null het e-mailbericht de waarde:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Wanneer een element null is, kunt u het volgende doen:

Laat het sleutel-waardepaar weg uit de JSON.
Retourneert een waarde die overeenkomt met het gegevenstype Azure AD B2C-claim. Voor een gegevenstype retourneert u bijvoorbeeld een string lege tekenreeks "". Retourneer voor een integer gegevenstype een nulwaarde 0. Retourneer voor een dateTime gegevenstype een minimumwaarde 1970-00-00T00:00:00.0000000Z.

In het volgende voorbeeld ziet u hoe u een null-waarde verwerkt. Het e-mailbericht wordt weggelaten uit de JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Een geneste JSON-hoofdtekst parseren

Als u een geneste JSON-hoofdtekst wilt parseren, stelt u de metagegevens resolveJsonPathsInJsonTokens in op true. Stel in de uitvoerclaim het PartnerClaimType in op het JSON-padelement dat u wilt uitvoeren.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

De uitvoerclaims moeten eruitzien als het volgende XML-fragment:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

De REST API lokaliseren

In een technisch RESTful-profiel kunt u de taal/landinstelling van de huidige sessie verzenden en indien nodig een gelokaliseerd foutbericht genereren. Met behulp van de claimosser kunt u een contextuele claim verzenden, zoals de gebruikerstaal. In het volgende voorbeeld ziet u een technisch RESTful-profiel dat dit scenario laat zien.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</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://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Foutberichten verwerken

Uw REST API moet mogelijk een foutbericht retourneren, zoals 'De gebruiker is niet gevonden in het CRM-systeem'. Als er een fout optreedt, moet de REST API een HTTP 409-foutbericht retourneren (statuscode conflictreactie). Zie het technische profiel RESTful voor meer informatie.

Dit gedrag kan alleen worden bereikt door een technisch REST API-profiel aan te roepen vanuit een technisch validatieprofiel. Hiermee kan de gebruiker de gegevens op de pagina corrigeren en de validatie opnieuw uitvoeren bij het indienen van de pagina.

Als u rechtstreeks vanuit een gebruikerstraject naar een technisch PROFIEL van de REST API verwijst, wordt de gebruiker teruggeleid naar de relying party-toepassing met het relevante foutbericht.

Ontwikkeling van uw REST API

Uw REST API kan op elk platform worden ontwikkeld en geschreven in elke programmeertaal, zolang deze veilig is en claims in JSON-indeling kan verzenden en ontvangen.

De aanvraag voor uw REST API-service is afkomstig van Azure AD B2C-servers. De REST API-service moet worden gepubliceerd naar een openbaar toegankelijk HTTPS-eindpunt. De REST API-aanroepen komen binnen vanaf een IP-adres van een Azure-datacenter.

U kunt serverloze cloudfuncties, zoals HTTP-triggers, gebruiken in Azure Functions voor eenvoudige ontwikkeling.

Uw REST API-service en de onderliggende onderdelen (zoals de database en het bestandssysteem) moeten maximaal beschikbaar zijn.

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.

Volgende stappen

Meer informatie over het toevoegen van een API-connector om registratie-ervaringen te wijzigen
Meer informatie over het toevoegen van een API-connector om tokens te verrijken met externe claims
Meer informatie over het beveiligen van uw API-connector
Aan de slag met onze voorbeelden

Zie de volgende artikelen voor voorbeelden van het gebruik van een technisch RESTful-profiel:

Meer informatie over het bouwen van tolerantie bij interfacing met externe processen
Meer informatie over het bouwen van tolerantie via best practices voor ontwikkelaars.

API-connectors gebruiken om aanmeldingsgebruikersstromen en aangepaste beleidsregels aan te passen en uit te breiden met externe identiteitsgegevensbronnen