Tokens verrijken met claims van externe bronnen met behulp van API-connectors

  • Artikel

Voordat u begint, gebruikt u de selector Een beleidstype kiezen om het type beleid te kiezen dat u instelt. U kunt in Azure Active Directory B2C op twee manieren definiëren hoe gebruikers met uw toepassingen communiceren: via vooraf gedefinieerde gebruikersstromen of via volledig configureerbaar aangepast beleid. De stappen die in dit artikel zijn vereist, verschillen voor elke methode.

Met Azure Active Directory B2C (Azure AD B2C) kunnen identiteitsontwikkelaars een interactie met een RESTful-API integreren in hun gebruikersstroom met behulp van API-connectors. Hiermee kunnen ontwikkelaars dynamisch gegevens ophalen uit externe identiteitsbronnen. Aan het einde van dit scenario kunt u een Azure AD B2C-gebruikersstroom maken die communiceert met API's om tokens te verrijken met informatie uit externe bronnen.

U kunt API-connectors gebruiken die zijn toegepast op de stap Voordat u de tokenstap (preview) verzendt om tokens voor uw toepassingen te verrijken met informatie uit externe bronnen. Wanneer een gebruiker zich aanmeldt of zich registreert, roept Azure AD B2C het API-eindpunt aan dat is geconfigureerd in de API-connector, waarmee informatie kan worden opgevraagd over een gebruiker in downstreamservices, zoals cloudservices, aangepaste gebruikersarchieven, aangepaste machtigingssystemen, verouderde identiteitssystemen en meer.

Notitie

Deze functie is beschikbaar voor openbare preview.

U kunt een API-eindpunt maken met behulp van een van onze voorbeelden.

Vereisten

  • Een API-eindpunt. U kunt een API-eindpunt maken met behulp van een van onze voorbeelden.

Een API-connector maken

Als u een API-connector wilt gebruiken, maakt u eerst de API-connector en schakelt u deze vervolgens in in een gebruikersstroom.

  1. Meld u aan bij de Azure-portal.

  2. Selecteer onder Azure-services de optie Azure AD B2C.

  3. Selecteer API-connectors en selecteer vervolgens Nieuwe API-connector.

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

  4. Geef een weergavenaam op voor de aanroep. Verrijk bijvoorbeeld token van externe bron.

  5. Geef de eindpunt-URL op voor de API-aanroep.

  6. Kies het verificatietype en configureer de verificatiegegevens voor het aanroepen van uw API. Meer informatie over het beveiligen van uw API-Verbinding maken or.

    Screenshot showing sample authentication configuration for an API connector.

  7. Selecteer Opslaan.

De API-connector inschakelen in een gebruikersstroom

Volg deze stappen om een API-connector toe te voegen aan een gebruikersstroom voor registratie.

  1. Meld u aan bij de Azure-portal.

  2. Selecteer onder Azure-services de optie Azure AD B2C.

  3. Selecteer Gebruikersstromen en selecteer vervolgens de gebruikersstroom waaraan u de API-connector wilt toevoegen.

  4. Selecteer API-connectors en selecteer vervolgens het API-eindpunt dat u wilt aanroepen bij de stap Voordat u de tokenstap (preview) in de gebruikersstroom verzendt:

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

  5. Selecteer Opslaan.

Deze stap bestaat alleen voor gebruikersstromen registreren en aanmelden (aanbevolen), registreren (aanbevolen) en aanmelden (aanbevolen).

Voorbeeldaanvraag verzonden naar de API in deze stap

Een API-connector bij deze stap wordt aangeroepen wanneer een token op het punt staat te worden uitgegeven tijdens aanmeldingen en aanmeldingen. Een API-connector wordt gerealiseerd als een HTTP POST-aanvraag en verzendt gebruikerskenmerken ('claims') als sleutel-waardeparen in een JSON-hoofdtekst. Kenmerken worden geserialiseerd op dezelfde manier als gebruikerseigenschappen van Microsoft Graph .

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 claims die naar de API worden verzonden, zijn afhankelijk van de informatie die voor de gebruiker is gedefinieerd. Alleen gebruikerseigenschappen en aangepaste kenmerken die worden vermeld in de azure AD B2C-gebruikerskenmerken>zijn beschikbaar om in de aanvraag te worden verzonden. Aangepaste kenmerken bestaan in de indeling extension_<extensions-app-id>_CustomAttribute in de map. Uw API verwacht claims in dezelfde geserialiseerde indeling te ontvangen. Zie Aangepaste kenmerken definiëren in Azure AD B2C voor meer informatie over aangepaste kenmerken. Bovendien worden deze claims doorgaans verzonden in alle aanvragen voor deze stap:

  • Landinstellingen van de gebruikersinterface ('ui_locales'): een of meer landinstellingen van eindgebruikers zoals geconfigureerd op hun apparaat. Dit kan worden gebruikt door uw API om geinternationaliseerde antwoorden te retourneren.
  • Stap ('stap'): de stap of het punt in de gebruikersstroom waarvoor de API-connector is aangeroepen. Waarde voor deze stap is '
  • Client-id ('client_id'): de appId waarde van de toepassing waarnaar een eindgebruiker zich in een gebruikersstroom verificeert. Dit is niet de brontoepassing appId in toegangstokens.
  • objectId : de id van de gebruiker. U kunt dit gebruiken om downstreamservices op te vragen voor informatie over de gebruiker.

Belangrijk

Als een claim geen waarde heeft op het moment dat het API-eindpunt wordt aangeroepen, wordt de claim niet naar de API verzonden. Uw API moet zijn ontworpen om expliciet het geval te controleren en te verwerken waarin een claim zich niet in de aanvraag bevindt.

Verwachte antwoordtypen van de web-API in deze stap

Wanneer de web-API een HTTP-aanvraag van Microsoft Entra-id ontvangt tijdens een gebruikersstroom, kan deze een vervolgantwoord retourneren.

Vervolgantwoord

Een vervolgantwoord geeft aan dat de gebruikersstroom moet doorgaan naar de volgende stap: het verlenen van het token. In een vervolgantwoord kan de API aanvullende claims retourneren. Een claim die wordt geretourneerd door de API die u in het token wilt retourneren, moet een ingebouwde claim zijn of zijn gedefinieerd als een aangepast kenmerk en moet worden geselecteerd in de configuratie van toepassingsclaims van de gebruikersstroom. De claimwaarde in het token wordt geretourneerd door de API, niet de waarde in de map. Sommige claimwaarden kunnen niet worden overschreven door het API-antwoord. Claims die door de API kunnen worden geretourneerd, komen overeen met de set die is gevonden onder Gebruikerskenmerken met uitzondering van email.

Notitie

De API wordt alleen aangeroepen tijdens een eerste verificatie. Wanneer u vernieuwingstokens gebruikt om op de achtergrond nieuwe toegangs- of id-tokens te verkrijgen, bevat het token de waarden die tijdens de eerste verificatie worden geëvalueerd.

Voorbeeld van een antwoord

Voorbeeld van een vervolgantwoord

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 Vereist Beschrijving
versie Tekenreeks Ja De versie van uw API.
action Tekenreeks Ja Waarde moet zijn Continue.
<builtInUserAttribute> <kenmerktype> Nee Ze kunnen in het token worden geretourneerd als deze zijn geselecteerd als een toepassingsclaim.
<extension_{extensions-app-id}_CustomAttribute> <kenmerktype> Nee De claim hoeft niet te bevatten _<extensions-app-id>_, het is optioneel. Ze kunnen in het token worden geretourneerd als deze zijn geselecteerd als een toepassingsclaim.

In dit scenario verrijken we de tokengegevens van de gebruiker door te integreren met een zakelijke line-of-business-werkstroom. Tijdens het registreren of aanmelden met een lokaal of federatief account roept Azure AD B2C een REST API aan om de uitgebreide profielgegevens van de gebruiker op te halen uit een externe gegevensbron. In dit voorbeeld verzendt Azure AD B2C de unieke id van de gebruiker, de object-id. De REST API retourneert vervolgens het accountsaldo van de gebruiker (een willekeurig getal). Gebruik dit voorbeeld als uitgangspunt om te integreren met uw eigen CRM-systeem, marketingdatabase of een line-of-business-werkstroom. U kunt de interactie ook ontwerpen als een technisch validatieprofiel. Dit is geschikt wanneer de REST API gegevens op het scherm valideert en claims retourneert. Zie Walkthrough voor meer informatie: Een API-connector toevoegen aan een gebruikersstroom voor registratie.

Vereisten

Een REST API-eindpunt voorbereiden

Voor deze procedure moet u een REST API hebben die controleert of de Azure AD B2C-object-id van een gebruiker is geregistreerd in uw back-endsysteem. Indien geregistreerd, retourneert de REST API het saldo van het gebruikersaccount. Anders registreert de REST API het nieuwe account in de map en retourneert het beginsaldo 50.00. De volgende JSON-code illustreert de gegevens die Azure AD B2C naar uw REST API-eindpunt verzendt.

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

Zodra uw REST API de gegevens valideert, moet deze een HTTP 200 (OK) retourneren met de volgende JSON-gegevens:

{
    "balance": "760.50"
}

De installatie van het REST API-eindpunt valt buiten het bereik van dit artikel. We hebben een Azure Functions-voorbeeld gemaakt. U hebt toegang tot de volledige Azure-functiecode op GitHub.

Claims definiëren

Een claim maakt tijdelijke opslag van gegevens mogelijk tijdens de uitvoering van een Azure AD B2C-beleid. U kunt claims declareren in de sectie claimsschema .

  1. Open het uitbreidingsbestand van uw beleid. Bijvoorbeeld SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Zoek element BuildingBlocks. Als het element niet aanwezig is, voegt u het toe.
  3. Zoek naar het element ClaimsSchema. Als het element niet aanwezig is, voegt u het toe.
  4. Voeg de volgende claims toe aan het element 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>

Het technische profiel van de RESTful-API toevoegen

Een restful technisch profiel biedt ondersteuning voor communicatie met uw eigen RESTful-service. Azure AD B2C verzendt gegevens naar de RESTful-service in een InputClaims verzameling en ontvangt gegevens terug in een OutputClaims verzameling. Zoek het element ClaimsProviders in uw TrustFrameworkExtensions.xml bestand en voeg als volgt een nieuwe claimprovider toe:

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

In dit voorbeeld wordt de userLanguage service verzonden naar de REST-service als lang binnen de JSON-nettolading. De waarde van de userLanguage claim bevat de huidige gebruikerstaal-id. Zie claim resolver voor meer informatie.

Het technische profiel van de RESTful-API configureren

Nadat u uw REST API hebt geïmplementeerd, stelt u de metagegevens van het REST-GetProfile technische profiel in om uw eigen REST API weer te geven, waaronder:

  • ServiceUrl. Stel de URL van het REST API-eindpunt in.
  • SendClaimsIn. Geef op hoe de invoerclaims worden verzonden naar de RESTful-claimprovider.
  • AuthenticationType. Stel het type verificatie in dat wordt uitgevoerd door de RESTful-claimprovider, zoals Basic of ClientCertificate
  • AllowInsecureAuthInProduction. Zorg ervoor dat u deze metagegevens in een productieomgeving instelt op false.

Zie de metagegevens van het RESTful-technische profiel voor meer configuraties. De bovenstaande AuthenticationType opmerkingen en AllowInsecureAuthInProduction geef wijzigingen op die u moet aanbrengen wanneer u naar een productieomgeving gaat. Zie Uw RESTful-API beveiligen voor productie voor meer informatie over het beveiligen van uw RESTful-API.

Een indelingsstap toevoegen

Met gebruikersbelevingen worden expliciete paden opgegeven waarmee een op claims gebaseerde toepassing de gewenste claims voor een gebruiker kan verkrijgen. Een gebruikerstraject wordt weergegeven als een indelingsreeks die moet worden gevolgd voor een geslaagde transactie. U kunt indelingsstappen toevoegen of aftrekken. In dit geval voegt u een nieuwe indelingsstap toe die wordt gebruikt om de informatie die aan de toepassing wordt verstrekt, te verbeteren nadat de gebruiker zich heeft geregistreerd of zich heeft aangemeld via de REST API-aanroep.

  1. Open het basisbestand van uw beleid. Bijvoorbeeld SocialAndLocalAccounts/TrustFrameworkBase.xml.
  2. Zoek naar het <UserJourneys> element. Kopieer het hele element en verwijder het.
  3. Open het uitbreidingsbestand van uw beleid. Bijvoorbeeld SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  4. Plak de <UserJourneys> in het extensiebestand, na de sluiting van het <ClaimsProviders> element.
  5. Zoek de <UserJourney Id="SignUpOrSignIn">en voeg de volgende indelingsstap toe vóór de laatste. 
    <OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
  6. Herstructureer de laatste indelingsstap door het Order te wijzigen in 8. De laatste twee indelingsstappen moeten er als volgt uitzien: 
    <OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
<OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
  7. Herhaal de laatste twee stappen voor de gebruikerstrajecten ProfileEdit en PasswordReset .

Een claim opnemen in het token

Als u de balance claim wilt terugsturen naar de relying party-toepassing, voegt u een uitvoerclaim toe aan het SocialAndLocalAccounts/SignUpOrSignIn.xml bestand. Als u een uitvoerclaim toevoegt, wordt de claim na een geslaagde gebruikersbeleving in het token verzonden en naar de toepassing verzonden. Wijzig het technische profielelement in de sectie relying party om toe te voegen balance als een uitvoerclaim.

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

Herhaal deze stap voor de gebruikerstrajecten ProfileEdit.xml en PasswordReset.xml . Sla de bestanden op die u hebt gewijzigd: TrustFrameworkBase.xml en TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml en PasswordReset.xml.

Het aangepaste beleid testen

  1. Meld u aan bij de Azure-portal.
  2. Als u toegang hebt tot meerdere tenants, selecteert u het pictogram Instellingen in het bovenste menu om over te schakelen naar uw Azure AD B2C-tenant in het menu Mappen en abonnementen.
  3. Kies linksboven in de Azure Portal Alle services, zoek App-registraties en selecteer deze.
  4. Selecteer Identity Experience Framework.
  5. Selecteer Aangepast beleid uploaden en upload vervolgens de beleidsbestanden die u hebt gewijzigd: TrustFrameworkBase.xml en TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xml en PasswordReset.xml.
  6. Selecteer het registratie- of aanmeldingsbeleid dat u hebt geüpload en klik op de knop Nu uitvoeren .
  7. U moet zich kunnen registreren met een e-mailadres of een Facebook-account.
  8. Het token dat naar uw toepassing wordt geretourneerd, bevat de balance-claim.
{
  "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"
  ...
}

Aanbevolen procedures en probleemoplossing

Serverloze cloudfuncties gebruiken

Serverloze functies, zoals HTTP-triggers in Azure Functions, bieden een manier om API-eindpunten te maken voor gebruik met de API-connector. De serverloze cloudfunctie kan ook andere web-API's, gegevensarchieven en andere cloudservices aanroepen en aanroepen voor complexe scenario's.

Aanbevolen procedures

U moet het volgende hebben gedaan:

  • Uw API volgt de API-aanvraag- en antwoordcontracten zoals hierboven beschreven.
  • De eindpunt-URL van de API-connector verwijst naar het juiste API-eindpunt.
  • Uw API controleert expliciet op null-waarden van ontvangen claims waarvan deze afhankelijk is.
  • Uw API implementeert een verificatiemethode die wordt beschreven in het beveiligen van uw API-connector.
  • Uw API reageert zo snel mogelijk om een vloeiende gebruikerservaring te garanderen.
    • Azure AD B2C wacht maximaal 20 seconden om een antwoord te ontvangen. Als er geen wordt ontvangen, wordt er nog een poging (opnieuw) geprobeerd om uw API aan te roepen.
    • Als u een serverloze functie of schaalbare webservice gebruikt, gebruikt u een hostingabonnement dat de API 'wakker' of 'warm' in productie houdt. Voor Azure Functions is het raadzaam om minimaal het Premium-abonnement in productie te gebruiken.
  • Hoge beschikbaarheid van uw API garanderen.
  • De prestaties van downstream-API's, databases of andere afhankelijkheden van uw API bewaken en optimaliseren.

Belangrijk

Uw eindpunten moeten voldoen aan de Azure AD B2C-beveiligingsvereisten. Oudere TLS-versies en -coderingen zijn afgeschaft. Zie Vereisten voor Azure AD B2C TLS en suites met coderingsmethoden voor meer informatie.

Logboekregistratie gebruiken

Serverloze cloudfuncties gebruiken

Serverloze functies, zoals HTTP-triggers in Azure Functions, bieden een manier om API-eindpunten te maken voor gebruik met de API-connector. De serverloze cloudfunctie kan ook andere web-API's, gegevensarchieven en andere cloudservices aanroepen en aanroepen voor complexe scenario's.

Logboekregistratie gebruiken

Over het algemeen is het handig om de hulpprogramma's voor logboekregistratie te gebruiken die zijn ingeschakeld door uw web-API-service, zoals Application Insights, om uw API te bewaken op onverwachte foutcodes, uitzonderingen en slechte prestaties.

  • Controleer op HTTP-statuscodes die geen HTTP 200 of 400 zijn.
  • Een HTTP-statuscode van 401 of 403 geeft meestal aan dat er een probleem is met uw verificatie. Controleer de verificatielaag van uw API en de bijbehorende configuratie in de API-connector.
  • Gebruik zo nodig agressievere niveaus van logboekregistratie (bijvoorbeeld tracering of foutopsporing).
  • Bewaak uw API voor lange reactietijden. Daarnaast registreert Azure AD B2C metagegevens over de API-transacties die plaatsvinden tijdens gebruikersverificaties via een gebruikersstroom. Ga als volgt te werk om deze te vinden:
  1. Ga naar Azure AD B2C
  2. Onder Activiteiten selecteert u Controlelogboeken.
  3. Filter de lijstweergave: Selecteer voor Datum het gewenste tijdsinterval en selecteer voor Activiteit een API die is aangeroepen als onderdeel van een gebruikersstroom.
  4. Afzonderlijke logboeken inspecteren. Elke rij vertegenwoordigt een API-connector die wordt aangeroepen tijdens een gebruikersstroom. Als een API-aanroep mislukt en er een nieuwe poging wordt uitgevoerd, wordt deze nog steeds weergegeven als één rij. Hiermee numberOfAttempts wordt aangegeven hoe vaak uw API is aangeroepen. Deze waarde kan 1of 2. Andere informatie over de API-aanroep wordt in de logboeken beschreven. Screenshot of an example audit log with API connector transaction.

Volgende stappen

Zie de volgende artikelen voor meer informatie over het beveiligen van uw API's: