Een API-connector toevoegen aan een gebruikersstroom

Artikel
02/05/2024

Van toepassing op: Groene cirkel met een wit vinkje. Externe tenants Witte cirkel met een grijs X-symbool. van werknemers (meer informatie)

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

Belangrijk

Vanaf 12 juli 2021, als Microsoft Entra B2B-klanten nieuwe Google-integraties hebben ingesteld voor gebruik met selfserviceregistratie voor hun aangepaste of line-of-business-toepassingen, werkt verificatie met Google-identiteiten pas als verificaties worden verplaatst naar systeemwebweergaven. Meer informatie.
Vanaf 30 september 2021 biedt Google geen ondersteuning meer voor aanmelden via ingesloten webweergaven. Als uw apps gebruikers verifiëren met een ingesloten webweergave en u Google-federatie gebruikt met Azure AD B2C of Microsoft Entra B2B voor uitnodigingen voor externe gebruikers of selfserviceregistratie, kunnen Google Gmail-gebruikers zich niet verifiëren. Meer informatie.

Een API-connector maken

Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een gebruikersbeheerder.
Blader naar overzicht>van externe identiteiten.>
Selecteer Alle API-connectors en selecteer vervolgens Nieuwe API-connector.
Geef een weergavenaam op voor de aanroep. Controleer bijvoorbeeld de goedkeuringsstatus.
Geef de eindpunt-URL op voor de API-aanroep.
Kies het verificatietype en configureer de verificatiegegevens voor het aanroepen van uw API. Meer informatie over het beveiligen van uw API-connector.
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": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "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",
 "ui_locales":"en-US"
}

Alleen gebruikerseigenschappen en aangepaste kenmerken die worden vermeld in de >>gebruikerskenmerken voor identiteiten, zijn beschikbaar om in de aanvraag te worden verzonden.

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

Bovendien worden de 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.

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 selfservicegebruikersstroom voor registratie.

Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een gebruikersbeheerder.
Blader naar overzicht>van externe identiteiten.>
Selecteer Gebruikersstromen en selecteer vervolgens de gebruikersstroom waaraan u de API-connector wilt toevoegen.
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
Selecteer Opslaan.

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

Voorbeeldaanvraag verzonden naar de API in deze stap

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

De exacte claims die naar de API worden verzonden, zijn afhankelijk van welke informatie wordt verstrekt door de id-provider. '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 in Microsoft Entra-id.

Voorbeeldaanvraag verzonden naar de API in deze stap

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "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",
 "ui_locales":"en-US"
}

De exacte claims die naar de API worden verzonden, zijn afhankelijk van welke gegevens 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 aan de claim is toegewezen vanaf de pagina voor het verzamelen van kenmerken.

Bekijk een voorbeeld van een vervolgantwoord.

Blokkeringsreactie

Bekijk een voorbeeld van een blokkerend antwoord.

Validatiefoutantwoord

Wanneer de API reageert met een validatiefoutantwoord, 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.

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	Waarden kunnen worden opgeslagen in de map als ze zijn geselecteerd als claim voor ontvangst in de configuratie van de API-connector en gebruikerskenmerken voor een gebruikersstroom. Waarden kunnen worden geretourneerd in het token als deze is geselecteerd als een toepassingsclaim.
<extension_{extensions-app-id}_CustomAttribute>	<kenmerktype>	Nee	De claim hoeft niet te bevatten `_<extensions-app-id>_`, dit 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 an error with your request. Please try again or contact support.",
}

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

Een voorbeeldafbeelding van hoe de eindgebruikerservaring eruitziet nadat een API een blokkerend antwoord retourneert.

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 `400`zijn, 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

Een voorbeeldafbeelding van hoe de eindgebruikerservaring eruitziet nadat een API een validatiefoutantwoord retourneert.

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 uw API-connector.
Uw API reageert zo snel mogelijk om een vloeiende gebruikerservaring te garanderen.
- Microsoft Entra ID 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 te gebruiken.
Hoge beschikbaarheid van uw API garanderen.
De prestaties van downstream-API's, databases of andere afhankelijkheden van uw API bewaken en optimaliseren.
Uw eindpunten moeten voldoen aan de beveiligingsvereisten voor Microsoft Entra TLS en codering. Zie vereisten voor TLS en coderingssuites 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

Meer informatie over het toevoegen van een aangepaste goedkeuringswerkstroom aan selfserviceregistratie
Ga aan de slag met onze quickstartvoorbeelden.

Delen via

Een API-connector toevoegen aan een gebruikersstroom

Een API-connector maken

De aanvraag die naar uw API is verzonden

De API-connector inschakelen in een gebruikersstroom

Voorbeeldaanvraag verzonden naar de API in deze stap

Verwachte antwoordtypen van de web-API in deze stap

Vervolgantwoord

Blokkeringsreactie

Voordat u de gebruiker maakt

Voorbeeldaanvraag verzonden naar de API in deze stap

Verwachte antwoordtypen van de web-API in deze stap

Vervolgantwoord

Blokkeringsreactie

Validatiefoutantwoord

Voorbeeldantwoorden

Voorbeeld van een vervolgantwoord

Voorbeeld van een blokkerend antwoord

Voorbeeld van een validatiefoutantwoord

Aanbevolen procedures en probleemoplossing

Serverloze cloudfuncties gebruiken

Aanbevolen procedures

Logboekregistratie gebruiken

Volgende stappen

Feedback

Aanvullende resources

Delen via

Een API-connector toevoegen aan een gebruikersstroom

Een API-connector maken

De aanvraag die naar uw API is verzonden

De API-connector inschakelen in een gebruikersstroom

Na het federeren met een id-provider tijdens het registreren

Voorbeeldaanvraag verzonden naar de API in deze stap

Verwachte antwoordtypen van de web-API in deze stap

Vervolgantwoord

Blokkeringsreactie

Voordat u de gebruiker maakt

Voorbeeldaanvraag verzonden naar de API in deze stap

Verwachte antwoordtypen van de web-API in deze stap

Vervolgantwoord

Blokkeringsreactie

Validatiefoutantwoord

Voorbeeldantwoorden

Voorbeeld van een vervolgantwoord

Voorbeeld van een blokkerend antwoord

Voorbeeld van een validatiefoutantwoord

Aanbevolen procedures en probleemoplossing

Serverloze cloudfuncties gebruiken

Aanbevolen procedures

Logboekregistratie gebruiken

Volgende stappen

Feedback

Aanvullende resources