Berika tokens med externa anspråk med API-kopplingar från externa källor.

Du kan använda API-kopplingar som tillämpas på steget Innan du skickar token (förhandsversion) för att berika tokens för dina applikationer med information från externa källor. När en användare loggar in eller registrerar sig anropar Azure AD B2C API-slutpunkten som konfigurerats i API-anslutningsappen, som kan fråga efter information om en användare i underordnade tjänster som molntjänster, anpassade användarlager, anpassade behörighetssystem, äldre identitetssystem med mera.

Du kan skapa en API-slutpunkt med något av våra exempel.

Förutsättningar

• En API-slutpunkt. Du kan skapa en API-slutpunkt med något av våra exempel.

Skapa en API-anslutning

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

1. Logga in på Azure-portalen.

2. Under Azure-tjänster väljer du Azure AD B2C.

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

   

4. Ange ett visningsnamn för samtalet. Till exempel Berika token från extern källa.

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 api-anslutningsappen.

   

7. Välj Spara.

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 registreringsanvändarflöde.

1. Logga in på Azure-portalen.

2. Under Azure-tjänster väljer du Azure AD B2C.

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-kopplingar och välj sedan den API-slutpunkt du vill anropa i användarflödet vid steget Innan token skickas (förhandsgranskning).

   

5. Välj Spara.

Det här steget finns bara för användarflödena Registrera dig och logga in (rekommenderas), Registrera dig (rekommenderas) och Logga in (rekommenderas).

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

En API-koppling vid detta steg anropas när en token ska utfärdas under inloggningar och registreringar. En API-anslutning realiseras som en HTTP POST-begäran och skickar användarattribut ("anspråk") som nyckel/värde-par i en JSON-kropp. Attribut serialiseras på samma sätt som Microsoft Graph-användaregenskaper .

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

De anspråk som skickas till API:et beror på den information som definierats för användaren. Endast användaregenskaper och anpassade attribut som anges i azure AD B2C-användarattributen> kan skickas i begäran. Anpassade attribut finns i formatet extension_<extensions-app-id>_CustomAttribute 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 i Azure AD B2C. Dessutom skickas dessa anspråk vanligtvis i alla begäranden för det här steget:

• 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.
• Steg ('steg') – Steget eller punkten i användarflödet som API-anslutningsappen anropades för. Värdet för det här steget är "
• Klient-ID ("client_id") – värdet appId för det program som en slutanvändare autentiserar till i ett användarflöde. Det här är inte resursapplikationens appId i åtkomsttokener.
• objectId – användarens identifierare. Du kan använda detta för att fråga underordnade tjänster om du vill ha information om användaren.

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 ett "fortsättningssvar".

Fortsättningssvar

Ett fortsättningssvar anger att användarflödet ska fortsätta till nästa steg: att utfärda token. I ett fortsättningssvar kan API:et returnera ytterligare anspråk. Ett anspråk som returneras av API:et som du vill returnera i token måste vara ett inbyggt anspråk eller definierat som ett anpassat attribut och måste väljas i programanspråkskonfigurationen för användarflödet. Anspråksvärdet i token är det som returneras av API:et, inte värdet i katalogen. Vissa anspråksvärden kan inte skrivas över av API-svaret. Anspråk som kan returneras av API:et motsvarar uppsättningen som finns under Användarattribut med undantag för email.

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
}

I det här scenariot berikar vi användarens tokendata genom att integrera med ett affärsarbetsflöde för företag. Under registreringen eller inloggningen med ett lokalt eller federerat konto anropar Azure AD B2C ett REST-API för att hämta användarens utökade profildata från en fjärrdatakälla. I det här exemplet skickar Azure AD B2C användarens unika identifierare, objectId. REST-API:et returnerar sedan användarens kontosaldo (ett slumptal). Använd det här exemplet som utgångspunkt för att integrera med ditt eget CRM-system, en marknadsföringsdatabas eller ett affärsarbetsflöde. Du kan också utforma interaktionen som en teknisk valideringsprofil. Detta är lämpligt när REST-API:et verifierar data på skärmen och returnerar anspråk. Mer information finns i Genomgång: Lägga till en API-kontakt i ett registreringsflöde.

Förutsättningar

• Slutför stegen i Kom igång med anpassade principer. Du bör ha en fungerande anpassad princip för registrering och inloggning med lokala konton.
• Lär dig hur du integrerar REST API-anspråksutbyten i din anpassade Azure AD B2C-princip.

Förbereda en REST API-slutpunkt

För den här genomgången bör du ha ett REST-API som verifierar om en användares Azure AD B2C objectId är registrerat i serverdelssystemet. Om det är registrerat returnerar REST-API:et användarkontosaldot. Annars registrerar REST-API:et det nya kontot i katalogen och returnerar startsaldot 50.00. Följande JSON-kod illustrerar de data som Azure AD B2C skickar till REST API-slutpunkten.

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

När rest-API:et verifierar data måste det returnera en HTTP 200 (Ok) med följande JSON-data:

{
    "balance": "760.50"
}

Installationen av REST API-slutpunkten ligger utanför omfånget för den här artikeln. Vi har skapat ett Azure Functions-exempel . Du kan komma åt den fullständiga Azure-funktionskoden på GitHub.

Definiera anspråk

Ett tillstånd ger tillfällig lagring av data under en Azure AD B2C-policykörning. Du kan deklarera anspråk i avsnittet anspråksschema .

1. Öppna tilläggsfilen för policyn. Till exempel SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
2. Sök efter elementet BuildingBlocks . Om elementet inte finns lägger du till det.
3. Leta upp elementet ClaimsSchema . Om elementet inte finns lägger du till det.
4. Lägg till följande anspråk i elementet ClaimsSchema .

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Lägga till den tekniska profilen för RESTful API

En RESTful-teknisk profil ger stöd för att samverka med din egen RESTful-tjänst. Azure AD B2C skickar data till RESTful-tjänsten i en InputClaims samling och tar emot data tillbaka i en OutputClaims samling. Leta upp elementet ClaimsProviders i TrustFrameworkExtensions.xml filen och lägg till en ny anspråksprovider på följande sätt:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

I det här exemplet userLanguage skickas till REST-tjänsten som lang i JSON-nyttolasten. Värdet för anspråket userLanguage innehåller det aktuella användarspråks-ID:t. Mer information finns i kravhanterare.

Konfigurera den tekniska profilen för RESTful API

När du har distribuerat REST-API:n anger du metadata för den tekniska profilen för att de ska återspegla ditt eget REST-API, inklusive:

• ServiceUrl. Ange URL:en för REST API-slutpunkten.
• SendClaimsIn. Ange hur indataanspråken skickas till RESTful-anspråksprovidern.
• AuthenticationType. Ange vilken typ av autentisering som utförs av RESTful-anspråksprovidern, till exempel Basic eller ClientCertificate
• AllowInsecureAuthInProduction. I en produktionsmiljö måste du ange dessa metadata till false.

Se RESTfuls tekniska profilmetadata för mer konfigurationer. Kommentarerna ovan AuthenticationType och AllowInsecureAuthInProduction ange ändringar som du bör göra när du flyttar till en produktionsmiljö. Information om hur du skyddar dina RESTful-API:er för produktion finns i Skydda ditt RESTful-API.

Lägga till ett orkestreringssteg

Användarresor anger explicita sökvägar genom vilka en princip tillåter att ett anspråksbaserat program hämtar önskade anspråk för en användare. En användarresa representeras som en orkestreringssekvens som måste följas upp för en lyckad transaktion. Du kan lägga till eller subtrahera orkestreringssteg. I det här fallet lägger du till ett nytt orkestreringssteg som används för att utöka informationen som tillhandahålls till programmet efter att användaren har registrerat sig eller loggat in via REST API-anropet.

1. Öppna basfilen för din policy. Till exempel SocialAndLocalAccounts/TrustFrameworkBase.xml.
2. Sök efter elementet <UserJourneys> . Kopiera hela elementet och ta sedan bort det.
3. Öppna tilläggsfilen för policyn. Till exempel SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
4. Klistra in <UserJourneys> i tilläggsfilen, efter slutet på elementet <ClaimsProviders>.
5. Leta upp <UserJourney Id="SignUpOrSignIn"> och lägg till följande orkestreringssteg före det sista.

   <OrchestrationStep Order="7" Type="ClaimsExchange">
     <ClaimsExchanges>
       <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
     </ClaimsExchanges>
   </OrchestrationStep>
   

6. Omstrukturera det sista orkestreringssteget Order genom att ändra till 8. De sista två orkestreringsstegen bör se ut så här:

   <OrchestrationStep Order="7" Type="ClaimsExchange">
     <ClaimsExchanges>
       <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
     </ClaimsExchanges>
   </OrchestrationStep>
   <OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
   

7. Upprepa de två sista stegen för användarresorna ProfileEdit och PasswordReset .

Inkludera ett anspråk i token

För att returnera anspråket balance tillbaka till det förlitande programmet, lägg till ett utdataanspråk i SocialAndLocalAccounts/SignUpOrSignIn.xml-filen. Om du lägger till ett utgångsanspråk utfärdas anspråket till token efter en lyckad användarupplevelse och skickas till programmet. Ändra det tekniska elementet i profilen inom avsnittet för förlitande part för att lägga till balance som ett resultatkrav.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Upprepa det här steget för ProfileEdit.xmloch PasswordReset.xml användarresor. Spara filerna som du har ändrat: TrustFrameworkBase.xmloch TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmloch PasswordReset.xml.

Testa den anpassade policyn

1. Logga in på Azure-portalen.
2. Om du har åtkomst till flera klienter väljer du ikonen Inställningar på den översta menyn för att växla till din Microsoft Entra-klient från menyn Kataloger + prenumerationer .
3. Välj Alla tjänster i det övre vänstra hörnet i Azure-portalen och sök sedan efter och välj Appregistreringar.
4. Välj Identity Experience Framework.
5. Välj Överför anpassad princip och ladda sedan upp de principfiler som du ändrade: TrustFrameworkBase.xmloch TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmloch PasswordReset.xml.
6. Välj den registrerings- eller inloggningsprincip som du laddade upp och klicka på knappen Kör nu .
7. Du bör kunna registrera dig med hjälp av en e-postadress eller ett Facebook-konto.
8. Den token som har skickats tillbaka till din applikation innehåller anspråket balance.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

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. Den serverlösa molnfunktionen kan också anropa och initiera andra webb-API, datalager och molntjänster för komplexa scenarier.

Metodtips

Se till att:

• 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 API-anslutningsappen.
• Ditt API svarar så snabbt som möjligt för att säkerställa en smidig användarupplevelse.
  • Azure AD B2C 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 åtminstone använder Premium-planen i produktion.
• 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.

Använda loggning

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. Den serverlösa molnfunktionen kan också anropa och initiera andra webb-API, datalager och molntjänster för komplexa scenarier.

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.

Dessutom loggar Azure AD B2C metadata om DE API-transaktioner som sker under användarautentiseringar via ett användarflöde. För att hitta dessa:

1. Gå till Azure AD B2C
2. Under Aktiviteter väljer du Granskningsloggar.
3. Filtrera listvyn: För Datum väljer du önskat tidsintervall och för Aktivitet väljer du Ett API anropades som en del av ett användarflöde.
4. Granska enskilda loggar. Varje rad representerar en API-anslutning som försöker att anropas under ett användarflöde. Om ett API-anrop misslyckas och ett nytt försök görs representeras det fortfarande som en enda rad. numberOfAttempts Anger hur många gånger api:et anropades. Det här värdet kan vara 1eller 2. Annan information om API-anropet beskrivs i loggarna.

• Kom igång med våra exempel.
• Skydda api-anslutningsappen

Information om hur du skyddar dina API:er finns i följande artiklar:

• Genomgång: Integrera REST API-anspråksutbyten i din Azure AD B2C-användarresa som ett orkestreringssteg
• Skydda ditt RESTful-API
• Referens: RESTful teknisk profil