Dela via

Lägga till en API-anslutningsapp i ett användarflöde

  • Artikel

Gäller för:Grön cirkel med en vit bockmarkeringssymbol.Personalklientorganisationer Vit cirkel med en grå X-symbol. Externa klienter (läs mer)

Om du vill använda en API-anslutningsapp skapar du först API-anslutningsappen och aktiverar den sedan i ett användarflöde.

Viktigt!

  • Från och med den 12 juli 2021, om Microsoft Entra B2B-kunder konfigurerar nya Google-integreringar för användning med självbetjäningsregistrering för sina anpassade eller branschspecifika program, fungerar inte autentisering med Google-identiteter förrän autentiseringar flyttas till systemwebbvyer. Läs mer.
  • Från och med den 30 september 2021 är Google inaktuellt stöd för inbäddad webbvisningsinloggning. Om dina appar autentiserar användare med en inbäddad webbvy och du använder Google-federation med Azure AD B2C eller Microsoft Entra B2B för externa användarinbjudningar eller självbetjäningsregistrering kommer Google Gmail-användare inte att kunna autentisera. Läs mer.

Skapa en API-anslutningsapp

Dricks

Stegen i den här artikeln kan variera något beroende på vilken portal du börjar från.

  1. Logga in på administrationscentret för Microsoft Entra som minst användaradministratör.

  2. Bläddra till Översikt>över identiteter för externa identiteter.>

  3. Välj Alla API-anslutningsappar och välj sedan Ny API-anslutningsapp.

    Skärmbild av att lägga till en ny API-anslutningsapp i externt ID.

  4. Ange ett visningsnamn för samtalet. Till exempel Kontrollera godkännandestatus.

  5. Ange slutpunkts-URL :en för API-anropet.

  6. Välj typ av autentisering och konfigurera autentiseringsinformationen för att anropa ditt API. Lär dig hur du skyddar ditt API-Anslut eller.

    Skärmbild av hur du konfigurerar en API-anslutningsapp.

  7. Välj Spara.

Begäran som skickas till ditt API

En API-anslutningsapp materialiseras som en HTTP POST-begäran och skickar användarattribut ("anspråk") som nyckel/värde-par i en JSON-brödtext. Attribut serialiseras på samma sätt som Microsoft Graph-användaregenskaper .

Exempelbegäran

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

Endast användaregenskaper och anpassade attribut som anges i funktionen Översikt över>anpassade användarattribut för identiteter>>är tillgängliga för att skickas i begäran.

Anpassade attribut finns i formatet extension_<extensions-app-id>_AttributeName i katalogen. Ditt API bör förvänta sig att ta emot anspråk i samma serialiserade format. Mer information om anpassade attribut finns i definiera anpassade attribut för självbetjäningsregistreringsflöden.

Dessutom skickas anspråken vanligtvis i alla begäranden:

  • Nationella användargränssnitt ("ui_locales") – En slutanvändares nationella inställningar som konfigurerats på deras enhet. Detta kan användas av ditt API för att returnera internationaliserade svar.
  • E-postadress ("e-post") eller identiteter ("identiteter") – dessa anspråk kan användas av ditt API för att identifiera slutanvändaren som autentiserar till programmet.

Viktigt!

Om ett anspråk inte har något värde när API-slutpunkten anropas skickas inte anspråket till API:et. DITT API bör utformas för att uttryckligen kontrollera och hantera det fall där ett anspråk inte finns i begäran.

Aktivera API-anslutningsappen i ett användarflöde

Följ de här stegen för att lägga till en API-anslutningsapp i ett användarflöde för självbetjäningsregistrering.

  1. Logga in på administrationscentret för Microsoft Entra som minst användaradministratör.

  2. Bläddra till Översikt>över identiteter för externa identiteter.>

  3. Välj Användarflöden och välj sedan det användarflöde som du vill lägga till API-anslutningsappen i.

  4. Välj API-anslutningsappar och välj sedan de API-slutpunkter som du vill anropa i följande steg i användarflödet:

    • Efter federering med en identitetsprovider under registreringen
    • Innan du skapar användaren

    Välja vilken API-anslutningsapp som ska användas för ett steg i användarflödet som

  5. Välj Spara.

Efter federering med en identitetsprovider under registreringen

En API-anslutningsapp i det här steget i registreringsprocessen anropas omedelbart efter att användaren autentiserats med en identitetsprovider (till exempel Google, Facebook eller Microsoft Entra ID). Det här steget föregår sidan för attributsamlingen, som är det formulär som visas för användaren för att samla in användarattribut.

Exempelbegäran som skickas till API:et i det här steget

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 exakta anspråk som skickas till API:et beror på vilken information som tillhandahålls av identitetsprovidern. "e-post" skickas alltid.

Förväntade svarstyper från webb-API:et i det här steget

När webb-API:et tar emot en HTTP-begäran från Microsoft Entra-ID under ett användarflöde kan det returnera följande svar:

  • Fortsättningssvar
  • Blockerande svar

Fortsättningssvar

Ett fortsättningssvar anger att användarflödet ska fortsätta till nästa steg: sidan för attributsamlingen.

I ett fortsättningssvar kan API:et returnera anspråk. Om ett anspråk returneras av API:et gör anspråket följande:

  • Fyller i indatafältet på sidan för attributsamlingen.

Se ett exempel på ett fortsättningssvar.

Blockerande svar

Ett blockerande svar avslutar användarflödet. Det kan utfärdas avsiktligt av API:et för att stoppa fortsättningen av användarflödet genom att visa en blocksida för användaren. På blocksidan visas den userMessage som tillhandahålls av API:et.

Se ett exempel på ett blockerande svar.

Innan du skapar användaren

En API-anslutningsapp i det här steget i registreringsprocessen anropas efter sidan för attributsamlingen, om en är inkluderad. Det här steget anropas alltid innan ett användarkonto skapas i Microsoft Entra-ID.

Exempelbegäran som skickas till API:et i det här steget

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 exakta anspråk som skickas till API:et beror på vilken information som samlas in från användaren eller tillhandahålls av identitetsprovidern.

Förväntade svarstyper från webb-API:et i det här steget

När webb-API:et tar emot en HTTP-begäran från Microsoft Entra-ID under ett användarflöde kan det returnera följande svar:

  • Fortsättningssvar
  • Blockerande svar
  • Valideringssvar

Fortsättningssvar

Ett fortsättningssvar anger att användarflödet ska fortsätta till nästa steg: skapa användaren i katalogen.

I ett fortsättningssvar kan API:et returnera anspråk. Om ett anspråk returneras av API:et gör anspråket följande:

  • Åsidosätter alla värden som redan har tilldelats anspråket från attributsamlingssidan.

Se ett exempel på ett fortsättningssvar.

Blockerande svar

Ett blockerande svar avslutar användarflödet. Det kan utfärdas avsiktligt av API:et för att stoppa fortsättningen av användarflödet genom att visa en blocksida för användaren. På blocksidan visas den userMessage som tillhandahålls av API:et.

Se ett exempel på ett blockerande svar.

Svar på valideringsfel

När API:et svarar med ett svar på valideringsfel finns användarflödet kvar på sidan för attributsamlingen och ett userMessage visas för användaren. Användaren kan sedan redigera och skicka formuläret igen. Den här typen av svar kan användas för indataverifiering.

Se ett exempel på ett svar på valideringsfel.

Exempelsvar

Exempel på ett fortsättningssvar

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 Obligatoriskt Beskrivning
version Sträng Ja Versionen av api:et.
åtgärd String Ja Värdet måste vara Continue.
<builtInUserAttribute> <attributtyp> Nej Värden kan lagras i katalogen om de har valts som ett anspråk som ska tas emot i API-anslutningsappens konfiguration och användarattribut för ett användarflöde. Värden kan returneras i token om de väljs som ett programanspråk.
<extension_{extensions-app-id}_CustomAttribute> <attributtyp> Nej Anspråket behöver inte innehålla _<extensions-app-id>_, det är valfritt. Returnerade värden kan skriva över värden som samlats in från en användare.

Exempel på ett blockeringssvar

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 Obligatoriskt Beskrivning
version Sträng Ja Versionen av api:et.
åtgärd String Ja Värdet måste vara ShowBlockPage
userMessage String Ja Meddelande som ska visas för användaren.

Slutanvändarupplevelse med ett blockerande svar

Ett exempel på hur slutanvändarupplevelsen ser ut när ett API returnerar ett blockerande svar.

Exempel på ett svar på valideringsfel

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 Obligatoriskt Beskrivning
version Sträng Ja Versionen av api:et.
åtgärd String Ja Värdet måste vara ValidationError.
status Heltal/sträng Ja Måste vara värdet 400, eller "400" för ett ValidationError-svar.
userMessage String Ja Meddelande som ska visas för användaren.

Kommentar

HTTP-statuskoden måste vara "400" utöver värdet "status" i svarets brödtext.

Slutanvändarupplevelse med svar på valideringsfel

Ett exempel på hur slutanvändarupplevelsen ser ut när ett API returnerar ett svar på valideringsfel.

Metodtips och hur du felsöker

Använda serverlösa molnfunktioner

Serverlösa funktioner, till exempel HTTP-utlösare i Azure Functions, tillhandahåller ett sätt att skapa API-slutpunkter att använda med API-anslutningsappen. Du kan använda den serverlösa molnfunktionen för att till exempel utföra valideringslogik och begränsa registreringar till specifika e-postdomäner. Den serverlösa molnfunktionen kan också anropa och anropa andra webb-API:er, datalager och andra molntjänster för komplexa scenarier.

Bästa praxis

Se till att du har gjort följande:

  • Ditt API följer API-begärande- och svarskontrakten enligt beskrivningen ovan.
  • Slutpunkts-URL:en för API-anslutningsappen pekar på rätt API-slutpunkt.
  • Api:et söker uttryckligen efter nullvärden för mottagna anspråk som det är beroende av.
  • Ditt API implementerar en autentiseringsmetod som beskrivs i skydda din API-Anslut eller.
  • Ditt API svarar så snabbt som möjligt för att säkerställa en smidig användarupplevelse.
    • Microsoft Entra ID väntar i högst 20 sekunder för att få ett svar. Om ingen tas emot görs ytterligare ett försök (försök igen) att anropa ditt API.
    • Om du använder en serverlös funktion eller skalbar webbtjänst använder du en värdplan som håller API:et "vaken" eller "varmt" i produktion. För Azure Functions rekommenderar vi att du använder premiumplanen som minst.
  • Säkerställ hög tillgänglighet för ditt API.
  • Övervaka och optimera prestanda för underordnade API:er, databaser eller andra beroenden för ditt API.
  • Dina slutpunkter måste uppfylla säkerhetskraven för Microsoft Entra TLS och chiffer. Mer information finns i krav för TLS och chiffersvit.

Använda loggning

I allmänhet är det bra att använda loggningsverktygen som aktiveras av webb-API-tjänsten, till exempel Application Insights, för att övervaka ditt API för oväntade felkoder, undantag och dåliga prestanda.

  • Övervaka för HTTP-statuskoder som inte är HTTP 200 eller 400.
  • En HTTP-statuskod på 401 eller 403 indikerar vanligtvis att det finns ett problem med din autentisering. Dubbelkolla API:ets autentiseringslager och motsvarande konfiguration i API-anslutningsappen.
  • Använd mer aggressiva loggningsnivåer (till exempel "spårning" eller "felsökning") under utveckling om det behövs.
  • Övervaka ditt API för långa svarstider.

Nästa steg