Använd API-anslutningar för att anpassa och utöka registreringsflöden och anpassningsbara principer med externa identitetsdatakällor

Ö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 att skapa kontobeslut.
• 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. Berika token med användarattribut 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 ger Azure AD B2C 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-kontakt i ett användarflöde

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

• Efter federering med en identitetsleverantör vid registreringen – gäller endast för 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 identitetsleverantör vid registrering

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-kontakter 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, förifyll sidan för attributinsamling och gör dem tillgängliga för retur i token.
• Implementera en tillåtelselista eller blockeringslista baserat på social identitet.

Innan du skapar användaren

En API-kontakt i det här steget av registreringsprocessen anropas efter sidan för attributinsamling, om en sådan inkluderas. Det här steget anropas alltid innan ett användarkonto skapas. Följande är exempel på scenarier som du kan aktivera i det här läget under registreringen:

• Verifiera användarindata 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)

En API-kontakt 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 källor som skiljer sig frå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åkstransformeringar eller manipulationer 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 den e-postadress som användaren har angett finns i kundens databas, och om inte visas ett fel. Du kan också se API-kopplingar 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 alla gemener eller versaler kan rest-API:et formatera namnet med endast den första bokstaven versaliserad 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öretagsspecifika 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.

Anropa en RESTful-tjänst

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

• Teknisk valideringsprofil. 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 användardata innan användarens resa går framåt. Med den tekniska verifieringsprofilen kan du:

  • Skicka förfrågningar till REST-API:t.
  • 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åksutbyte. Ett direkt anspråksutbyte kan konfigureras genom att anropa en REST API-teknisk profil direkt från ett orkestreringssteg för en användarresa. Den här definitionen är begränsad till:

  • Skicka förfrågningar till REST-API:t.
  • 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, precis innan Azure AD B2C verifierar autentiseringsuppgifterna.
• Omedelbart efter inloggningen.
• Innan Azure AD B2C skapar ett nytt konto i katalogen.
• När Azure AD B2C har skapat ett nytt konto i katalogen.
• Innan Azure AD B2C utfärdar en åtkomsttoken.

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 det namn 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ärandekroppen i ett '&'-separerat nyckel-värdeformat.
• Sidhuvud, som skickas i HTTP GET-begärandehuvudet.
• QueryString, som skickas i frågesträngen för en 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 parsas av RESTful-anspråksprovidern förväntar sig alltid att parsa ett platt JSON-brödtextsvar, till exempel:

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

Utdatana ska se ut som följande XML-kod:

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

• 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 en tom sträng "". För en integer datatyp returnerar du ett nollvärde 0. För en dateTime datatyp returnerar du ett minsta värde 0001-01-01T00: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 resultatkravet ställer du in PartnerClaimType till JSON-sökvägselementet du vill ange.

"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 teknisk RESTful-profil kanske du vill skicka den nuvarande sessionens språk/locale, och vid behov generera 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 ska REST API returnera ett HTTP 409-felmeddelande (statuskod för konfliktsvar). Mer information finns i den tekniska RESTful-profilen.

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 när sidan skickas.

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.

• Lär dig hur du lägger till en API-anslutningsapp för att ändra registreringsupplevelser
• Lär dig hur du lägger till en API-anslutning för att berika token med externa påståenden
• Lär dig hur du skyddar api-anslutningsappen
• Kom igång med våra exempel

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

• Genomgång: Lägga till en API-kontakt i ett registreringsflöde för användare
• Genomgång: Lägga till REST API-anspråksutbyten till anpassade principer i Azure Active Directory B2C
• Skydda dina REST API-tjänster
• Anropa ett REST-API med hjälp av en anpassad princip för Azure Active Directory B2C