Wzbogacanie tokenów twierdzeniami ze źródeł zewnętrznych przy użyciu łączników API

Możesz użyć łączników interfejsu API zastosowanych do kroku Przed wysłaniem tokenu (wersja zapoznawcza), aby wzbogacić tokeny dla aplikacji o informacje ze źródeł zewnętrznych. Gdy użytkownik zaloguje się lub zarejestruje się, usługa Azure AD B2C wywoła punkt końcowy interfejsu API skonfigurowany w łączniku interfejsu API, który może wysyłać zapytania o informacje o użytkowniku w usługach podrzędnych, takich jak usługi w chmurze, niestandardowe magazyny użytkowników, niestandardowe systemy uprawnień, starsze systemy tożsamości i inne.

Punkt końcowy interfejsu API można utworzyć przy użyciu jednego z naszych przykładów.

Wymagania wstępne

• Punkt końcowy interfejsu API. Punkt końcowy interfejsu API można utworzyć przy użyciu jednego z naszych przykładów.

Tworzenie łącznika interfejsu API

Aby użyć łącznika API, należy najpierw go utworzyć, a następnie włączyć w przepływie użytkownika.

1. Zaloguj się do witryny Azure Portal.

2. W obszarze usługi Azurewybierz Azure AD B2C.

3. Wybierz pozycję Łączniki interfejsu API, a następnie wybierz pozycję Nowy łącznik interfejsu API.

   

4. Podaj nazwę wyświetlaną wywołania. Na przykład wzbogacanie tokenu ze źródła zewnętrznego.

5. Podaj adres URL punktu końcowego dla wywołania interfejsu API.

6. Wybierz typ uwierzytelniania i skonfiguruj informacje uwierzytelniania na potrzeby wywoływania interfejsu API. Dowiedz się, jak zabezpieczyć łącznik interfejsu API.

   

7. Wybierz Zapisz.

Włączanie łącznika interfejsu API w przepływie użytkownika

Wykonaj następujące kroki, aby dodać łącznik interfejsu API do przepływu użytkownika rejestracji.

1. Zaloguj się do witryny Azure Portal.

2. W obszarze usługi Azurewybierz Azure AD B2C.

3. Wybierz pozycję Przepływy użytkownika, a następnie wybierz przepływ użytkownika, do którego chcesz dodać łącznik interfejsu API.

4. Wybierz Łączniki interfejsu API, a następnie wybierz punkt końcowy interfejsu API, który chcesz wywołać w kroku Przed wysłaniem tokenu (wersja zapoznawcza) w procesie użytkownika:

   

5. Wybierz Zapisz.

Ten krok istnieje tylko w przypadku przepływów użytkowników dla tworzenia konta i logowania (zalecane), rejestracji (zalecane) oraz logowania (zalecane).

Przykładowe żądanie wysłane do interfejsu API w tym kroku

Konektor API na tym etapie jest wywoływany, gdy token ma zostać wystawiony podczas rejestracji lub logowania. Łącznik interfejsu API przyjmuje formę żądania HTTP POST, wysyłając atrybuty użytkownika ('roszczenia') jako pary klucz-wartość w ciele JSON. Atrybuty są serializowane podobnie jak właściwości użytkownika programu 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": "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"
}

Oświadczenia wysyłane do interfejsu API zależą od informacji zdefiniowanych dla użytkownika. W żądaniu można wysyłać tylko właściwości użytkownika i atrybuty niestandardowe wymienione w środowiskuatrybutów użytkownika>. Atrybuty niestandardowe istnieją w formacie extension_<extensions-app-id>_CustomAttribute w katalogu. Interfejs API powinien oczekiwać otrzymania oświadczeń w tym samym formacie serializowanym. Aby uzyskać więcej informacji na temat atrybutów niestandardowych, zobacz Definiowanie atrybutów niestandardowych w usłudze Azure AD B2C. Ponadto te oświadczenia są zwykle wysyłane we wszystkich żądaniach dotyczących tego kroku:

• Ustawienia regionalne interfejsu użytkownika ('ui_locales') — ustawienia regionalne użytkownika końcowego skonfigurowane na urządzeniu. Może to być używane przez interfejs API do zwracania międzynarodowych odpowiedzi.
• Krok ('krok') — krok lub punkt przepływu użytkownika wywoływanego przez łącznik interfejsu API. Wartość dla tego kroku to "
• Identyfikator klienta ('client_id') — appId wartość aplikacji uwierzytelnianej przez użytkownika końcowego w przepływie użytkownika. To nie jest element aplikacji zasobów appId w tokenach dostępu.
• objectId — identyfikator użytkownika. Za pomocą tej funkcji można wykonywać zapytania dotyczące usług podrzędnych w celu uzyskania informacji o użytkowniku.

Oczekiwane typy odpowiedzi z internetowego interfejsu API na tym etapie

Gdy internetowy interfejs API odbiera żądanie HTTP z Microsoft Entra ID podczas przepływu użytkownika, może zwrócić "odpowiedź zwrotną".

Kontynuacja odpowiedzi

Odpowiedź kontynuacji wskazuje, że przepływ użytkownika powinien przejść do następnego kroku: wystawiania tokenu. W odpowiedzi ciągłej interfejs API może zwrócić dodatkowe oświadczenia. Oświadczenie zwrócone przez interfejs API, który ma zostać zwrócony w tokenie, musi być wbudowanym oświadczeniem lub zdefiniowanym jako atrybut niestandardowy i musi zostać wybrane w konfiguracji oświadczenia aplikacji przepływu użytkownika. Wartość roszczenia w tokenie będzie zwracana przez interfejs API, a nie z katalogu. Niektóre wartości oświadczeń nie mogą zostać nadpisane przez odpowiedź interfejsu API. Oświadczenia, które mogą być zwracane przez interfejs API, odpowiadają zestawowi znalezionemu w obszarze Atrybuty użytkownika z wyjątkiem email.

Przykładowa odpowiedź

Przykład kontynuacji odpowiedzi

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
}

W tym scenariuszu wzbogacamy dane tokenu użytkownika przez integrację z firmowym przepływem pracy. Podczas tworzenia konta lub logowania przy użyciu konta lokalnego lub federacyjnego usługa Azure AD B2C wywołuje interfejs API REST w celu uzyskania rozszerzonych danych profilu użytkownika ze zdalnego źródła danych. W tym przykładzie usługa Azure AD B2C wysyła unikatowy identyfikator użytkownika , objectId. Następnie interfejs API REST zwraca saldo konta użytkownika (liczbę losową). Użyj tego przykładu jako punktu wyjścia, aby zintegrować się z własnym systemem CRM, bazą danych marketingu lub dowolnym przepływem pracy biznesowym. Możesz również zaprojektować interakcję jako profil techniczny weryfikacji. Jest to odpowiednie, gdy interfejs API REST będzie weryfikował dane na ekranie i zwracał oświadczenia. Aby uzyskać więcej informacji, zobacz Przewodnik: dodawanie łącznika API do procesu rejestracji użytkownika.

Wymagania wstępne

• Wykonaj kroki w sekcji Wprowadzenie do zasad niestandardowych. Należy mieć działające zasady niestandardowe na potrzeby rejestracji i logowania się przy użyciu kont lokalnych.
• Dowiedz się, jak zintegrować wymiany oświadczeń interfejsu API REST w zasadach niestandardowych usługi Azure AD B2C.

Przygotowywanie punktu końcowego interfejsu API REST

W tym przewodniku należy mieć interfejs API REST, który waliduje, czy identyfikator objectId użytkownika z Azure AD B2C jest zarejestrowany w systemie backendowym. W przypadku zarejestrowania interfejs API REST zwraca saldo konta użytkownika. W przeciwnym razie interfejs API REST rejestruje nowe konto w katalogu i zwraca saldo 50.00początkowe . Poniższy kod JSON ilustruje dane, które usługa Azure AD B2C wyśle do punktu końcowego interfejsu API REST.

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

Gdy interfejs API REST zweryfikuje dane, musi zwrócić kod HTTP 200 (OK) z następującymi danymi JSON:

{
    "balance": "760.50"
}

Konfiguracja punktu końcowego interfejsu API REST wykracza poza zakres tego artykułu. Utworzyliśmy przykład usługi Azure Functions . Pełny kod funkcji platformy Azure można uzyskać w witrynie GitHub.

Definiowanie oświadczeń

Roszczenie zapewnia tymczasowe przechowywanie danych podczas wykonywania polityki usługi Azure AD B2C. Oświadczenia można zadeklarować w sekcji schematu oświadczeń .

1. Otwórz plik rozszerzeń zasad. Na przykład SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
2. Wyszukaj element BuildingBlocks . Jeśli element nie istnieje, dodaj go.
3. Znajdź element ClaimsSchema . Jeśli element nie istnieje, dodaj go.
4. Dodaj następujące oświadczenia do elementu 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>

Dodawanie profilu technicznego interfejsu API RESTful

Profil techniczny RESTful zapewnia obsługę współdziałania z własną usługą RESTful. Usługa Azure AD B2C wysyła dane do usługi RESTful w InputClaims kolekcji i odbiera je z powrotem w OutputClaims kolekcji. Znajdź element ClaimsProviders w pliku TrustFrameworkExtensions.xml i dodaj nowego dostawcę oświadczeń w następujący sposób:

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

W tym przykładzie userLanguage zostanie wysłany do usługi REST jako lang w danych JSON. Wartość userLanguage oświadczenia zawiera bieżący identyfikator języka użytkownika. Aby uzyskać więcej informacji, zobacz moduł rozstrzygania roszczeń.

Konfigurowanie profilu technicznego interfejsu API RESTful

Po wdrożeniu interfejsu API REST, ustawienia metadanych profilu technicznego REST-GetProfile powinny odzwierciedlać własny interfejs API REST, w tym:

• Adres URL usługi. Ustaw adres URL punktu końcowego interfejsu API REST.
• Wyślij ClaimsIn. Określ sposób wysyłania oświadczeń wejściowych do dostawcy oświadczeń RESTful.
• Typ uwierzytelniania. Ustawianie typu uwierzytelniania wykonywanego przez dostawcę oświadczeń RESTful, takiego jak Basic lub ClientCertificate
• AllowInsecureAuthInProduction. W środowisku produkcyjnym upewnij się, że dla tych metadanych ustawiono wartość false.

Zobacz metadane profilu technicznego RESTful, aby uzyskać więcej konfiguracji. Komentarze powyżej AuthenticationType i AllowInsecureAuthInProduction określają zmiany, które należy wprowadzić podczas przechodzenia do środowiska produkcyjnego. Aby dowiedzieć się, jak zabezpieczyć interfejsy API RESTful dla środowiska produkcyjnego, zobacz Zabezpieczanie interfejsu API RESTful.

Dodaj krok orkiestracji

Podróże użytkownika określają jawne ścieżki, za pośrednictwem których zasady umożliwiają aplikacji jednostki zależnej uzyskanie żądanych oświadczeń dla użytkownika. Podróż użytkownika jest reprezentowana jako sekwencja aranżacji, którą należy wykonać w celu pomyślnej transakcji. Kroki orkiestracji można dodawać lub odejmować. W takim przypadku dodasz nowy krok aranżacji, który służy do rozszerzania informacji dostarczonych do aplikacji po zarejestrowaniu się użytkownika lub zalogowaniu się za pośrednictwem wywołania interfejsu API REST.

1. Otwórz plik podstawowy zasad. Na przykład SocialAndLocalAccounts/TrustFrameworkBase.xml.
2. Wyszukaj element <UserJourneys>. Skopiuj cały element, a następnie usuń go.
3. Otwórz plik rozszerzeń zasad. Na przykład SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
4. Wklej element <UserJourneys> do pliku rozszerzeń po zamknięciu <ClaimsProviders> elementu.
5. Znajdź element <UserJourney Id="SignUpOrSignIn">i dodaj następujący krok aranżacji przed ostatnim.

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

6. Refaktoryzuj ostatni krok orkiestracji, zmieniając Order na 8. Ostatnie dwa kroki orkiestracji powinny wyglądać następująco:

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

7. Powtórz dwa ostatnie kroki dla ścieżek użytkownika ProfileEdit i PasswordReset.

Dołączanie oświadczenia do tokenu

Aby zwrócić balance oświadczenie z powrotem do aplikacji jednostki uzależnionej, dodaj oświadczenie wyjściowe do SocialAndLocalAccounts/SignUpOrSignIn.xml pliku. Dodanie oświadczenia wyjściowego spowoduje wysłanie oświadczenia do tokenu po pomyślnej podróży użytkownika i zostanie wysłane do aplikacji. Zmodyfikuj element profilu technicznego w sekcji strony zaufanej, aby dodać balance jako roszczenie wyjściowe.

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

Powtórz ten krok dla ProfileEdit.xml i PasswordReset.xml ścieżek użytkownika. Zapisz zmienione pliki: TrustFrameworkBase.xmli TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmli PasswordReset.xml.

Przetestuj politykę niestandardową

1. Zaloguj się do witryny Azure Portal.
2. Jeśli masz dostęp do wielu dzierżaw, wybierz ikonę Ustawienia z paska nawigacyjnego, aby przełączyć się do dzierżawy Microsoft Entra z menu Katalogi i subskrypcje.
3. Wybierz pozycję Wszystkie usługi w lewym górnym rogu witryny Azure Portal, a następnie wyszukaj i wybierz pozycję Rejestracje aplikacji.
4. Wybierz Identity Experience Framework.
5. Wybierz pozycję Przekaż zasady niestandardowe, a następnie przekaż zmienione pliki zasad: TrustFrameworkBase.xmli TrustFrameworkExtensions.xml, SignUpOrSignin.xml, ProfileEdit.xmli PasswordReset.xml.
6. Wybierz przekazane zasady rejestracji lub logowania, a następnie kliknij przycisk Uruchom teraz .
7. Powinno być możliwe zarejestrowanie się przy użyciu adresu e-mail lub konta na Facebooku.
8. Token wysłany z powrotem do twojej aplikacji zawiera roszczenie 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"
  ...
}

Najlepsze rozwiązania i sposoby rozwiązywania problemów

Korzystanie z funkcji chmury bezserwerowej

Funkcje bezserwerowe, takie jak wyzwalacze HTTP w usłudze Azure Functions, zapewniają sposób na tworzenie punktów końcowych API do użycia z łącznikiem API. Funkcja chmury bezserwerowej może również wywoływać inne API, magazyny danych oraz inne usługi chmurowe w złożonych scenariuszach.

Najlepsze rozwiązania

Upewnij się, że:

• Twój interfejs API spełnia kontrakty zapytań i odpowiedzi interfejsu API zgodnie z powyższym opisem.
• Adres URL punktu końcowego łącznika interfejsu API wskazuje prawidłowy punkt końcowy interfejsu API.
• Twój interfejs API jawnie sprawdza wartości null odebranych roszczeń, od których są uzależnione.
• Interfejs API implementuje metodę uwierzytelniania opisaną w temacie Zabezpieczanie łącznika interfejsu API.
• Interfejs API reaguje tak szybko, jak to możliwe, aby zapewnić płynne doświadczenie użytkownika.
  • Usługa Azure AD B2C poczeka maksymalnie 20 sekund na odebranie odpowiedzi. Jeśli żadna z nich nie zostanie odebrana, podejmie jeszcze jedną próbę (ponów próbę) podczas wywoływania interfejsu API.
  • Jeśli używasz funkcji bezserwerowej lub skalowalnej usługi internetowej, użyj planu hostingu, który utrzymuje interfejs API w aktywności lub w gotowości w produkcji. W przypadku usługi Azure Functions zaleca się użycie co najmniej planu Premium w środowisku produkcyjnym.
• Zapewnij wysoką dostępność interfejsu API.
• Monitorowanie i optymalizowanie wydajności podrzędnych interfejsów API, baz danych lub innych zależności interfejsu API.

Korzystanie z rejestrowania

Korzystanie z funkcji chmury bezserwerowej

Funkcje bezserwerowe, takie jak wyzwalacze HTTP w usłudze Azure Functions, zapewniają sposób na tworzenie punktów końcowych API do użycia z łącznikiem API. Funkcja chmury bezserwerowej może również wywoływać inne API, magazyny danych oraz inne usługi chmurowe w złożonych scenariuszach.

Korzystanie z rejestrowania

Ogólnie rzecz biorąc, warto używać narzędzi rejestrowania włączonych przez usługę internetowego interfejsu API, takich jak application insights, do monitorowania interfejsu API pod kątem nieoczekiwanych kodów błędów, wyjątków i niskiej wydajności.

• Monitoruj kody stanu HTTP, które nie są http 200 lub 400.
• Kod stanu HTTP 401 lub 403 zwykle wskazuje, że występuje problem z uwierzytelnianiem. Dokładnie sprawdź warstwę uwierzytelniania interfejsu API i odpowiednią konfigurację w łączniku API.
• Jeśli to konieczne, użyj bardziej agresywnych poziomów rejestrowania (na przykład "trace" lub "debug") w trakcie rozwoju.
• Monitoruj interfejs API pod kątem długich czasów odpowiedzi.

Dodatkowo, usługa Azure AD B2C rejestruje metadane dotyczące transakcji interfejsu API występujących podczas uwierzytelniania użytkowników za pośrednictwem procesu logowania użytkownika. Aby je znaleźć:

1. Przejdź do usługi Azure AD B2C
2. Pod Aktywności wybierz Dzienniki audytu.
3. Filtruj widok listy: w polu Data wybierz żądany interwał czasu, a w polu Działanie wybierz pozycję Interfejs API został wywołany jako część przepływu użytkownika.
4. Sprawdź poszczególne dzienniki. Każdy wiersz reprezentuje łącznik interfejsu API, który próbuje zostać wywołany podczas przepływu użytkownika. Jeśli wywołanie interfejsu API zakończy się niepowodzeniem i nastąpi ponowna próba, nadal jest reprezentowana jako pojedynczy wiersz. numberOfAttempts wskazuje, ile razy wywołano twoje API. Ta wartość może być 1lub 2. Inne informacje o wywołaniu interfejsu API są szczegółowe w dziennikach.

• Rozpocznij pracę z naszymi przykładami.
• Zabezpieczanie łącznika interfejsu API

Aby dowiedzieć się, jak zabezpieczyć interfejsy API, zobacz następujące artykuły:

• Przewodnik: jak zintegrować wymianę oświadczeń interfejsu API REST w ścieżce użytkownika w usłudze Azure AD B2C jako kroku orkiestracji
• Zabezpieczanie interfejsu API RESTful
• Dokumentacja: profil techniczny RESTful