Använda API-anslutningsappar för att anpassa och utöka användarflöden för registrering och anpassade principer med externa identitetsdatakällor

  • Artikel

Innan du börjar använder du väljaren Välj en principtyp för att välja den typ av princip som du konfigurerar. Azure Active Directory B2C erbjuder två metoder för att definiera hur användare interagerar med dina program: via fördefinierade användarflöden eller genom fullständigt konfigurerbara anpassade principer. Stegen som krävs i den här artikeln är olika för varje metod.

Översikt

Som utvecklare eller IT-administratör kan du använda API-anslutningsappar för att integrera dina registreringsanvändarflöden med REST-API:er för att anpassa registreringsupplevelsen och integrera med externa system. Med API-anslutningsappar kan du till exempel:

  • Verifiera indata från användaren. Verifiera mot felaktiga eller ogiltiga användardata. Du kan till exempel verifiera användarspecifika data mot befintliga data i ett externt datalager eller en lista över tillåtna värden. Om det är ogiltigt kan du be en användare att ange giltiga data eller blockera användaren från att fortsätta registreringsflödet.
  • Verifiera användaridentiteten. Använd en identitetsverifieringstjänst eller externa identitetsdatakällor för att lägga till en extra säkerhetsnivå för beslut om kontoskapande.
  • Integrera med ett anpassat arbetsflöde för godkännande. Anslut till ett anpassat godkännandesystem för att hantera och begränsa skapandet av konton.
  • Utöka token med attribut från externa källor. Utöka token med attribut om användaren från källor som är externa till Azure AD B2C, till exempel molnsystem, anpassade användarlager, anpassade behörighetssystem, äldre identitetstjänster med mera.
  • Skriv över användarattribut. Formatera om eller tilldela ett värde till ett attribut som samlas in från användaren. Om en användare till exempel anger förnamnet i alla gemener eller versaler kan du formatera namnet med endast den första bokstaven versal.
  • Kör anpassad affärslogik. Du kan utlösa nedströmshändelser i dina molnsystem för att skicka push-meddelanden, uppdatera företagsdatabaser, hantera behörigheter, granska databaser och utföra andra anpassade åtgärder.

En API-anslutningsapp tillhandahåller Azure AD B2C med den information som behövs för att anropa API-slutpunkten genom att definiera HTTP-slutpunkts-URL:en och autentisering för API-anropet. När du har konfigurerat en API-anslutningsapp kan du aktivera den för ett specifikt steg i ett användarflöde. När en användare når det steget i registreringsflödet anropas API-anslutningsappen och materialiseras som en HTTP POST-begäran till ditt API och skickar användarinformation ("anspråk") som nyckel/värde-par i en JSON-brödtext. API-svaret kan påverka körningen av användarflödet. API-svaret kan till exempel blockera en användare från att registrera sig, be användaren att ange information på nytt eller skriva över användarattribut.

Där du kan aktivera en API-anslutningsapp i ett användarflöde

Det finns tre platser i ett användarflöde där du kan aktivera en API-anslutningsapp:

  • När du har federerat med en identitetsprovider under registreringen gäller endast registreringsupplevelser
  • Innan du skapar användaren – gäller endast för registreringsupplevelser
  • Innan du skickar token (förhandsversion) – gäller för registreringar och inloggningar

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 och 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. Det här steget anropas inte om en användare registrerar sig med ett lokalt konto. Följande är exempel på scenarier för API-anslutningsappar som du kan aktivera i det här steget:

  • Använd den e-post eller federerade identitet som användaren angav för att söka efter anspråk i ett befintligt system. Returnera dessa anspråk från det befintliga systemet, fyll i attributsamlingssidan i förväg och gör dem tillgängliga för att returnera i token.
  • Implementera en tillåtna eller blockeringslista baserat på social identitet.

Innan du skapar användaren

En API-anslutningsapp i det här steget i registreringsprocessen anropas efter attributsamlingssidan, om den ingår. Det här steget anropas alltid innan ett användarkonto skapas. Följande är exempel på scenarier som du kan aktivera vid den här tidpunkten under registreringen:

  • Verifiera indata från användaren och be en användare att skicka data igen.
  • Blockera en användares registrering baserat på data som angetts av användaren.
  • Verifiera användaridentiteten.
  • Fråga externa system efter befintliga data om användaren för att returnera den i programtoken eller lagra den i Microsoft Entra-ID.

Innan du skickar token (förhandsversion)

Anteckning

Den här funktionen är en allmänt tillgänglig förhandsversion.

En API-anslutningsapp i det här steget i registrerings- eller inloggningsprocessen anropas innan en token utfärdas. Följande är exempel på scenarier som du kan aktivera i det här steget:

  • Utöka token med attribut om användaren från andra källor än katalogen, inklusive äldre identitetssystem, HR-system, externa användarlager med mera.
  • Utöka token med grupp- eller rollattribut som du lagrar och hanterar i ditt eget behörighetssystem.
  • Tillämpa anspråkstransformering eller manipuleringar på värden för anspråk i katalogen.

Identity Experience Framework, som ligger till grund för Azure Active Directory B2C (Azure AD B2C), kan integreras med RESTful-API:er inom en användarresa. Den här artikeln visar hur du skapar en användarresa som interagerar med en RESTful-tjänst med hjälp av en RESTful-teknisk profil.

Med Azure AD B2C kan du lägga till din egen affärslogik till en användarresa genom att anropa din egen RESTful-tjänst. Identity Experience Framework kan skicka och ta emot data från din RESTful-tjänst för att utbyta anspråk. Du kan till exempel:

  • Använd extern identitetsdatakälla för att verifiera indata från användaren. Du kan till exempel kontrollera att e-postadressen som tillhandahålls av användaren finns i kundens databas, och om inte, visas ett fel. Du kan lika gärna tänka på API-anslutningsappar som ett sätt att stödja utgående webhooks eftersom anropet görs när en händelse inträffar, till exempel en registrering.
  • Bearbeta anspråk. Om en användare anger sitt förnamn i gemener eller versaler kan REST-API:et formatera namnet med bara den första bokstaven versalt och returnera det till Azure AD B2C. När du använder en anpassad princip föredras dock ClaimsTransformations framför att anropa ett RESTful-API.
  • Berika användardata dynamiskt genom att ytterligare integrera med företagets verksamhetsspecifika program. Din RESTful-tjänst kan ta emot användarens e-postadress, fråga kundens databas och returnera användarens lojalitetsnummer till Azure AD B2C. Sedan kan returanspråk lagras i användarens Microsoft Entra konto, utvärderas i nästa orkestreringssteg eller inkluderas i åtkomsttoken.
  • Kör anpassad affärslogik. Du kan skicka push-meddelanden, uppdatera företagsdatabaser, köra en användarmigreringsprocess, hantera behörigheter, granska databaser och utföra andra arbetsflöden.

Diagram över ett RESTful-tjänstanspråkutbyte

Anteckning

Om det finns ett långsamt eller inget svar från RESTful-tjänsten till Azure AD B2C är tidsgränsen 30 sekunder och antalet återförsök är två gånger (vilket innebär att det finns totalt 3 försök). För närvarande kan du inte konfigurera inställningarna för timeout- och återförsöksantal.

Anropa en RESTful-tjänst

Interaktionen omfattar ett anspråksutbyte av information mellan REST API-anspråk och Azure AD B2C. Du kan utforma integreringen med RESTful-tjänsterna på följande sätt:

  • Teknisk profil för validering. Anropet till RESTful-tjänsten sker inom en teknisk valideringsprofil för den angivna självsäkra tekniska profilen eller en verifieringsvisningskontroll för en visningskontroll. Den tekniska valideringsprofilen validerar de data som tillhandahålls av användaren innan användarresan går vidare. Med den tekniska valideringsprofilen kan du:

    • Skicka anspråk till rest-API:et.
    • Verifiera anspråk och generera anpassade felmeddelanden som visas för användaren.
    • Skicka tillbaka anspråk från REST-API:et till nästa orkestreringssteg.

  • Anspråk byts ut. Ett direkt anspråksutbyte kan konfigureras genom att anropa en teknisk REST API-profil direkt från ett orkestreringssteg i en användarresa. Den här definitionen är begränsad till:

    • Skicka anspråk till rest-API:et.
    • Verifiera anspråk och generera anpassade felmeddelanden som returneras till programmet.
    • Skicka tillbaka anspråk från REST-API:et till nästa orkestreringssteg.

Du kan lägga till ett REST API-anrop när som helst i användarresan som definieras av en anpassad princip. Du kan till exempel anropa ett REST-API:

  • Under inloggningen verifierar B2C autentiseringsuppgifterna strax före Azure AD B2C.
  • Omedelbart efter inloggningen.
  • Innan Azure AD skapar B2C ett nytt konto i katalogen.
  • När Azure AD B2C skapar ett nytt konto i katalogen.
  • Innan Azure AD B2C utfärdar en åtkomsttoken.

Teknisk profilinsamling för validering

Skicka data

I den tekniska RESTful-profilen innehåller elementet InputClaims en lista över anspråk som ska skickas till din RESTful-tjänst. Du kan mappa namnet på ditt anspråk till namnet som definierats i RESTful-tjänsten, ange ett standardvärde och använda anspråksmatchare.

Du kan konfigurera hur indataanspråken skickas till RESTful-anspråksprovidern med hjälp av attributet SendClaimsIn. Möjliga värden är:

  • Brödtext som skickas i HTTP POST-begärandetexten i JSON-format.
  • Formulär, som skickas i HTTP POST-begärandetexten i ett et-talavgränsat& nyckelvärdeformat.
  • Header, som skickas i HTTP GET-begärandehuvudet.
  • QueryString, som skickas i frågesträngen HTTP GET-begäran.

När alternativet Brödtext har konfigurerats kan du med den tekniska REST API-profilen skicka en komplex JSON-nyttolast till en slutpunkt. Mer information finns i Skicka en JSON-nyttolast.

Ta emot data

Elementet OutputClaims i den tekniska RESTful-profilen innehåller en lista över anspråk som returneras av REST-API:et. Du kan behöva mappa namnet på anspråket som definierats i principen till det namn som definierats i REST-API:et. Du kan också inkludera anspråk som inte returneras av REST API-identitetsprovidern, så länge du anger attributet DefaultValue.

Utdataanspråken som tolkas av RESTful-anspråksprovidern förväntar sig alltid att parsa ett platt JSON Body-svar, till exempel:

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

Utdataanspråken bör se ut som följande XML-kodfragment:

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

Hantera null-värden

Ett null-värde i en databas används när värdet i en kolumn är okänt eller saknas. Inkludera inte JSON-nycklar med ett null värde. I följande exempel returnerar null e-postmeddelandet värdet:

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

När ett element är null, antingen:

  • Utelämna nyckel/värde-paret från JSON.
  • Returnera ett värde som motsvarar Azure AD B2C-anspråksdatatypen. För en string datatyp returnerar du till exempel den tomma strängen "". För en integer datatyp returnerar du ett nollvärde 0. För en dateTime datatyp returnerar du ett minsta värde 1970-00-00T00:00:00.0000000Z.

I följande exempel visas hur du hanterar ett null-värde. E-postmeddelandet utelämnas från JSON:

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

Parsa en kapslad JSON-brödtext

Om du vill parsa ett kapslat JSON-brödtextsvar anger du metadata för ResolveJsonPathsInJsonTokens till true. I utdataanspråket ställer du in PartnerClaimType till det JSON-sökvägselement som du vill mata ut.

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

Utdataanspråken bör se ut som följande XML-kodfragment:

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

Lokalisera REST-API:et

I en RESTful-teknisk profil kanske du vill skicka den aktuella sessionens språk/språk och vid behov skapa ett lokaliserat felmeddelande. Med hjälp av anspråkslösaren kan du skicka ett kontextuellt anspråk, till exempel användarspråket. I följande exempel visas en RESTful-teknisk profil som visar det här scenariot.

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

Hantera felmeddelanden

Rest-API:et kan behöva returnera ett felmeddelande, till exempel "Användaren hittades inte i CRM-systemet". Om ett fel inträffar bör REST-API:et returnera ett HTTP 409-felmeddelande (statuskod för konfliktsvar). Mer information finns i den tekniska profilen RESTful.

Det här beteendet kan bara uppnås genom att anropa en teknisk REST API-profil från en teknisk valideringsprofil. Låter användaren korrigera data på sidan och köra valideringen igen vid sidöverföring.

Om du refererar till en teknisk REST API-profil direkt från en användarresa omdirigeras användaren tillbaka till det förlitande partprogrammet med relevant felmeddelande.

Utveckling av rest-API:et

Rest-API:et kan utvecklas på valfri plattform och skrivas på valfritt programmeringsspråk, så länge det är säkert och kan skicka och ta emot anspråk i JSON-format.

Begäran till REST API-tjänsten kommer från Azure AD B2C-servrar. REST API-tjänsten måste publiceras till en offentligt tillgänglig HTTPS-slutpunkt. REST API-anropen kommer från en IP-adress för Azure-datacenter.

Du kan använda serverlösa molnfunktioner, till exempel HTTP-utlösare i Azure Functions för att underlätta utvecklingen.

Du bör utforma REST API-tjänsten och dess underliggande komponenter (till exempel databasen och filsystemet) så att de har hög tillgänglighet.

Viktigt

Dina slutpunkter måste uppfylla Azure AD B2C-säkerhetskrav. Äldre TLS-versioner och chiffer är inaktuella. Mer information finns i Azure AD B2C TLS- och chiffersvitkrav.

Nästa steg

I följande artiklar finns exempel på hur du använder en RESTful-teknisk profil: