Berika token med anspråk från externa källor med hjälp av API-anslutningsappar

  • 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. De steg som krävs i den här artikeln skiljer sig åt för varje metod.

Med Azure Active Directory B2C (Azure AD B2C) kan identitetsutvecklare integrera en interaktion med ett RESTful-API i användarflödet med hjälp av API-anslutningsappar. Det gör det möjligt för utvecklare att dynamiskt hämta data från externa identitetskällor. I slutet av den här genomgången kan du skapa ett Azure AD B2C-användarflöde som interagerar med API:er för att berika token med information från externa källor.

Du kan använda API-anslutningsappar som tillämpas på steget Innan du skickar token (förhandsversion) för att utöka token för dina program 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.

Kommentar

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

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

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.

    Screenshot showing the API connectors page in the Azure portal with the New API Connector button highlighted.

  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 ditt API-Anslut eller.

    Screenshot showing sample authentication configuration for an API connector.

  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-anslutningsappar och välj sedan den API-slutpunkt som du vill anropa i steget Innan token (förhandsversion) skickas i användarflödet:

    Screenshot of selecting an API connector for a user flow step.

  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-anslutningsapp i det här steget anropas när en token ska utfärdas under inloggningar och registreringar. 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 .

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "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 resursprogrammets appId i åtkomsttoken.
  • 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.

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.

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.

Kommentar

API:et anropas endast under en första autentisering. När du använder uppdateringstoken för att tyst få ny åtkomst eller ID-token innehåller token de värden som utvärderas under den första autentiseringen.

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 Sträng Ja Värdet måste vara Continue.
<builtInUserAttribute> <attributtyp> Inga De kan returneras i token om de väljs som ett programanspråk.
<extension_{extensions-app-id}_CustomAttribute> <attributtyp> Inga Anspråket behöver inte innehålla _<extensions-app-id>_, det är valfritt. De kan returneras i token om de väljs som ett programanspråk.

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

Förutsättningar

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 anspråk ger tillfällig lagring av data under en Azure AD B2C-principkörning. Du kan deklarera anspråk i avsnittet anspråksschema .

  1. Öppna tilläggsfilen för principen. 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 vilsam 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 anspråkslösare.

Konfigurera den tekniska profilen för RESTful API

När du har distribuerat rest-API:et anger du metadata för den tekniska profilen så att de REST-GetProfile återspeglar 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.

Mer konfiguration finns i RESTfuls tekniska profilmetadata . 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 principen. Exempel: SocialAndLocalAccounts/TrustFrameworkBase.xml
  2. Sök efter elementet <UserJourneys> . Kopiera hela elementet och ta sedan bort det.
  3. Öppna tilläggsfilen för principen. Exempel: SocialAndLocalAccounts/TrustFrameworkExtensions.xml
  4. <UserJourneys> Klistra in i filnamnstillägget efter slutet av elementet<ClaimsProviders>.
  5. <UserJourney Id="SignUpOrSignIn">Leta upp 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

Om du vill returnera anspråket balance tillbaka till det förlitande partprogrammet lägger du till ett utdataanspråk i SocialAndLocalAccounts/SignUpOrSignIn.xml filen. Om du lägger till ett utdataanspråk utfärdas anspråket i token efter en lyckad användarresa och skickas till programmet. Ändra det tekniska profilelementet i avsnittet förlitande part för att lägga balance till som ett utdataanspråk.

<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 användarresorna ProfileEdit.xml och PasswordReset.xml . Spara filerna som du har ändrat: TrustFrameworkBase.xml och TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml och PasswordReset.xml.

Testa den anpassade principen

  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 Azure AD B2C-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.xml och TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml och 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. Token som skickas tillbaka till ditt program innehåller anspråket balance .
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "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 anropa andra webb-API:er, datalager och andra molntjänster för komplexa scenarier.

Metodtips

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

Viktigt!

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

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 anropa andra webb-API:er, datalager och andra 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. Så här hittar du följande:
  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-anslutningsapp som försöker 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. Screenshot of an example audit log with API connector transaction.

Nästa steg

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