Delen via

Een API-connector toevoegen aan een gebruikersstroom

  • Artikel

Van toepassing op:Groene cirkel met een wit vinkje.Externe tenantsWitte 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

Een API-connector maken

Tip

Stappen in dit artikel kunnen enigszins variëren op basis van de portal waaruit u begint.

  1. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een gebruiker Beheer istrator.

  2. Blader naar overzicht>van externe identiteiten.>

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

    Schermopname van het toevoegen van een nieuwe API-connector aan externe id.

  4. Geef een weergavenaam op voor de aanroep. Controleer bijvoorbeeld de goedkeuringsstatus.

  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.

    Schermopname van het configureren van een 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": [ // 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 >>ervaring Aangepaste>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.

  1. Meld u aan bij het Microsoft Entra-beheercentrum als ten minste een gebruiker Beheer istrator.

  2. Blader naar overzicht>van externe identiteiten.>

  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

    Selecteren welke API-connector moet worden gebruikt voor een stap in de gebruikersstroom, zoals 'Voordat u de gebruiker maakt'.

  5. Selecteer Opslaan.

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

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 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 String 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 String Ja Waarde moet zijn ShowBlockPage
userMessage String 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 String Ja Waarde moet zijn ValidationError.
status Geheel getal/tekenreeks Ja Moet een waarde 400zijn, of "400" voor een ValidationError-antwoord.
userMessage String 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 veilig uw API-Verbinding maken or.
  • 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