Gebruik API-connectors om aanmeldingsstromen voor gebruikers en aangepaste beleidsregels aan te passen en uit te breiden met externe bronnen van identiteitsgegevens.

Belangrijk

Vanaf 1 mei 2025 is Azure AD B2C niet meer beschikbaar voor nieuwe klanten. Meer informatie vindt u in onze veelgestelde vragen.

Voordat u begint, gebruikt u de selector Een beleidstype kiezen boven aan deze pagina 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-connectoren gebruiken om uw aanmeldprocessen met REST API's te integreren, de aanmeldervaring aan te passen en te integreren met externe systemen. Met API-connectors kunt u bijvoorbeeld het volgende doen:

• Valideer gebruikersinvoergegevens. Valideer tegen vervormde 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 identiteitsverificatieservice of externe identiteitsgegevensbronnen om een extra beveiligingsniveau toe te voegen aan beslissingen over het maken van accounts.
• Integreer met een aangepaste goedkeuringswerkstroom. Maak verbinding met een aangepast goedkeuringssysteem voor het beheren en beperken van het maken van accounts.
• Uitbreidingstokens met kenmerken van externe bronnen. Verrijk tokens met gebruikerskenmerken van bronnen die zich buiten Azure AD B2C bevinden, zoals cloudsystemen, aangepaste gebruikersarchieven, aangepaste machtigingssystemen, verouderde identiteitsservices en meer.
• Gebruikerskenmerken overschrijven. Een waarde opnieuw opmaken of toewijzen aan een kenmerk dat door 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 letter met hoofdletters.
• 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 API-eindpunt aan te roepen door de URL en 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 gerealiseerd 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 verhinderen dat een gebruiker zich registreert, de gebruiker vraagt om gegevens opnieuw op te geven of gebruikerskenmerken te overschrijven.

Waar u een API-connector kunt inschakelen in een gebruikersstroom

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

• Na het federeren met een id-provider tijdens de registratie , geldt dit alleen voor registratie-ervaringen
• Voordat u de gebruiker aanmaakt, geldt dit alleen voor aanmeldingen.
• Voordat u het token verzendt (preview) - is van toepassing op aanmelden en inloggen

Na samenwerking met een identiteitsprovider tijdens de registratie

Een API-connector in deze stap van het registratieproces wordt aangeroepen direct nadat de gebruiker zich heeft geauthenticeerd met een identiteitsprovider (zoals Google, Facebook en Microsoft Entra ID). Deze stap gaat vooraf aan de attribuutverzamelingspagina, 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. Hier volgen enkele voorbeelden van API-connectorscenario's die u in deze stap kunt inschakelen:

• Gebruik de e-mail of federatieve identiteit die de gebruiker heeft opgegeven om claims in een bestaand systeem op te zoeken. Retourneer deze claims vanuit het bestaande systeem, vul de kenmerkverzamelpagina in met de vooraf ingevulde gegevens en zorg ervoor dat ze beschikbaar zijn om in het token te worden opgenomen.
• Implementeer een acceptatie- of blokkeringslijst op basis van sociale identiteiten.

Voordat u de gebruiker aanmaakt

Een API-connector op deze stap in het aanmeldenproces wordt aangeroepen na de attribuutverzamelingspagina, als deze is inbegrepen. Deze stap wordt altijd aangeroepen voordat een gebruikersaccount wordt gemaakt. Hier volgen enkele voorbeelden van scenario's die u op dit moment tijdens de registratie kunt inschakelen:

• Valideer gebruikersinvoergegevens en vraag een gebruiker om gegevens opnieuw in te dienen.
• Blokkeer de registratie van een gebruiker op basis van gegevens die door de gebruiker zijn ingevoerd.
• Controleer de gebruikersidentiteit.
• Voer een query uit op externe systemen voor bestaande gegevens over de gebruiker om deze te retourneren in het toepassingstoken of sla deze op in Microsoft Entra-id.

Voordat het token wordt verzonden (voorbeeldweergave)

Opmerking

Deze functie is beschikbaar als openbare preview.

Een API-connector bij deze stap in het registratie- of aanmeldingsproces wordt aangeroepen voordat een token wordt uitgegeven. Hier volgen enkele 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 RESTful-technisch 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 het volgende doen:

• Gebruik de externe identiteitsgegevensbron om invoergegevens van gebruikers te valideren. U kunt bijvoorbeeld controleren of het e-mailadres van de gebruiker bestaat in de database van uw klant en zo niet, een fout presenteren. U kunt api-connectors ook beschouwen 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 kleine letters of hoofdletters invoert, kan de REST API de naam opmaken met alleen de eerste letter met hoofdletters en deze retourneren naar Azure AD B2C. Wanneer u echter een aangepast beleid gebruikt, heeft ClaimsTransformations de voorkeur boven het aanroepen van een RESTful-API.
• Verrijk gebruikersgegevens dynamisch door verdere integratie met bedrijfs line-of-business-toepassingen. Uw RESTful-service kan het e-mailadres van de gebruiker ontvangen, de database van de klant opvragen en het loyaliteitsnummer van de gebruiker retourneren aan Azure AD B2C. Retourclaims kunnen vervolgens worden opgeslagen in het Microsoft Entra-account van de gebruiker, 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.

Opmerking

HTTP-aanvragen kunnen worden geannuleerd als er een traag of geen reactie van de RESTful-service naar Azure AD B2C is. De standaardtime-out is 10 seconden voor aangepast beleid en 5 seconden voor gebruikersstromen. Het standaardaantal nieuwe pogingen is één (wat betekent dat er in totaal 2 pogingen zijn).

Een RESTful-service aanroepen

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

• Technisch validatieprofiel. De aanroep van de RESTful-service vindt plaats binnen een validatie technisch profiel van het opgegeven zelf-asserteerde technische profiel, of een verificatie weergavebesturing van een weergavebesturingselement. Het technische validatieprofiel valideert de door de gebruiker verstrekte gegevens voordat het gebruikerstraject verder gaat. Met het technische validatieprofiel kunt u het volgende doen:

  • Claims verzenden naar uw REST API.
  • Valideer claims en genereer aangepaste foutberichten die worden weergegeven aan de gebruiker.
  • Verstuur claims van de REST API terug naar de volgende orkestratiestappen.

• Claims inwisselen. Een directe uitwisseling van claims kan worden geconfigureerd door rechtstreeks vanuit een orkestratiestap 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 genereer aangepaste foutberichten die worden geretourneerd naar de toepassing.
  • Verstuur claims van de REST API terug naar de volgende orkestratiestappen.

U kunt een REST API-aanroep toevoegen aan elke stap in het gebruikerstraject dat is gedefinieerd door een aangepast beleid. U kunt bijvoorbeeld een REST API aanroepen:

• Tijdens het inloggen, net voordat Azure AD B2C de gegevens valideert.
• Direct na aanmelding.
• Voordat Azure AD B2C een nieuw account in de directory maakt.
• Nadat Azure AD B2C een nieuw account in het directory heeft aangemaakt.
• Voordat Azure AD B2C een toegangstoken uitgeeft.

Gegevens verzenden

In het RESTful-technische profiel bevat het InputClaims element een lijst met claims die naar uw RESTful-service moeten worden verzonden. U kunt de naam van uw claim in kaart brengen naar de in de RESTful-service gedefinieerde naam, een standaardwaarde instellen en claimresolver 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 hoofdtekst van de HTTP POST-aanvraag in JSON-indeling.
• Formulier, met het HTTP POST-verzoek verzonden in een indeling waarbij sleutel-waarden gescheiden zijn door '&'.
• Header, verzonden in de HTTP GET-aanvraagheader.
• QueryString, verzonden in de querytekenreeks van de HTTP GET-aanvraag.

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 RESTful technische profiel bevat een lijst met claims die worden geretourneerd door de REST API. 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 REST API-id-provider, zolang u het kenmerk DefaultValue instelt.

De uitvoerclaims die worden geparseerd door de RESTful-claimprovider, verwachten altijd een plat JSON Body-antwoord 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 of ontbreekt. Neem geen JSON-sleutels op met een null waarde. In het volgende voorbeeld retourneert null het e-mailbericht de waarde:

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

Wanneer een element null is, gaat u als volgt te werk:

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

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

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

Een geneste JSON-hoofdtekst parseren

Om een geneste JSON-hoofdtekstrespons te parseren, stelt u de metagegevens van 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 RESTful-technisch profiel wilt u mogelijk de taal/landinstelling van de huidige sessie verzenden en, indien nodig, een gelokaliseerd foutbericht genereren. Met behulp van de claim-resolver kunt u een contextuele claim verzenden, zoals de gebruikerstaal. In het volgende voorbeeld ziet u een RESTful-technisch profiel waarin dit scenario wordt gedemonstreerd.

<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

Mogelijk moet uw REST API 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 (conflictstatuscode) retourneren. Zie het RESTful-technische profiel 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 REST API-profiel 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 in elke programmeertaal worden geschreven, zolang deze veilig is en claims kan verzenden en ontvangen in JSON-indeling.

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-aanroep komt van een IP-adres van een Azure-datacenter.

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

U moet uw REST API-service en de onderliggende onderdelen (zoals de database en het bestandssysteem) ontwerpen om maximaal beschikbaar te zijn.

Belangrijk

Uw eindpunten moeten voldoen aan de beveiligingsvereisten van Azure AD B2C. Oudere TLS-versies en coderingen zijn afgeschaft. Zie vereisten voor Azure AD B2C TLS en coderingssuites 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 RESTful-technisch profiel:

• Handleiding: Een API-connector toevoegen aan een aanmeldproces voor gebruikers
• Handleiding: REST API-claimsuitwisselingen toevoegen aan aangepaste beleidsregels in Azure Active Directory B2C
• Uw REST API-services beveiligen
• Een REST API aanroepen met behulp van aangepast Azure Active Directory B2C-beleid

• Leer hoe je veerkracht kunt opbouwen bij interactie met externe processen
• Leer hoe je veerkracht opbouwt met best practices voor ontwikkelaars.