Udostępnij przez

Bezpieczny dostęp do produktów i interfejsów API za pomocą aplikacji firmy Microsoft Entra

DOTYCZY: Deweloper | Podstawowy | Standardowy | Premium

Usługa API Management obsługuje teraz wbudowany dostęp oparty na aplikacji OAuth 2.0 do interfejsów API produktów przy użyciu przepływu poświadczeń klienta. Ta funkcja umożliwia menedżerom interfejsów API rejestrowanie aplikacji Microsoft Entra ID, usprawnianie bezpiecznego dostępu do interfejsu API dla deweloperów za pośrednictwem autoryzacji OAuth 2.0.

Uwaga / Notatka

Aplikacje są obecnie w ograniczonej wersji zapoznawczej. Aby się zarejestrować, wypełnij ten formularz.

Dzięki tej funkcji:

  • Menedżerowie interfejsów API ustawiają właściwość produktu, aby umożliwić dostęp oparty na aplikacji.
  • Menedżerowie interfejsów API rejestrują aplikacje klienckie w identyfikatorze Entra firmy Microsoft, aby ograniczyć dostęp do określonych produktów.
  • Deweloperzy mogą uzyskiwać dostęp do poświadczeń aplikacji klienckiej przy użyciu portalu deweloperów usługi API Management.
  • Przy użyciu przepływu poświadczeń klienta OAuth 2.0 deweloperzy lub aplikacje uzyskują tokeny, które mogą uwzględniać w żądaniach interfejsu API
  • Tokeny przedstawione w żądaniach interfejsu API są weryfikowane przez bramę usługi API Management w celu autoryzowania dostępu do interfejsów API produktu.

Wymagania wstępne

  • Wystąpienie usługi API Management wdrożone w warstwie Premium, Standard, Podstawowa lub Deweloper. Jeśli musisz wdrożyć wystąpienie, zapoznaj się z Tworzeniem wystąpienia usługi API Management.

  • Co najmniej jeden produkt w instancji usługi API Management, z przypisanym co najmniej jednym interfejsem API.

    • Produkt powinien znajdować się w stanie Opublikowany , aby można było uzyskać do niego dostęp deweloperów za pośrednictwem portalu deweloperów.
    • Do testowania możesz użyć domyślnego produktu Starter i interfejsu API echo dodanego do niego.
    • Jeśli chcesz utworzyć produkt, zobacz Tworzenie i publikowanie produktu.

  • Wystarczające uprawnienia w dzierżawie usługi Microsoft Entra do przypisania roli Administrator aplikacji , która wymaga co najmniej roli Administrator ról uprzywilejowanych .

  • Opcjonalnie dodaj co najmniej jednego użytkownika w wystąpieniu usługi API Management.

Konfigurowanie tożsamości zarządzanej

  1. Włącz tożsamość zarządzaną przypisaną przez system dla usługi API Management w wystąpieniu usługi API Management.

  2. Przypisz tożsamość roli RBAC administratora aplikacji w identyfikatorze Entra firmy Microsoft. Aby przypisać rolę:

    1. Zaloguj się do portalu i nawiguj do Microsoft Entra ID.
    2. W menu po lewej stronie wybierz pozycję Zarządzaj rolami>i administratorami.
    3. Wybierz pozycję Administrator aplikacji.
    4. W menu po lewej stronie wybierz pozycję Zarządzaj>przypisaniami>+ Dodaj przypisania.
    5. Na stronie Dodawanie przypisań wyszukaj tożsamość zarządzaną instancji usługi API Management, korzystając z nazwy (nazwę instancji usługi API Management). Wybierz tożsamość zarządzaną, a następnie wybierz pozycję Dodaj.

Włączanie dostępu opartego na aplikacji dla produktu

Wykonaj następujące kroki, aby włączyć dostęp oparty na aplikacji dla produktu. Produkt musi mieć włączone to ustawienie, aby było skojarzone z aplikacją kliencką w kolejnych krokach.

W poniższym przykładzie użyto produktu Starter , ale wybierz dowolny opublikowany produkt, który ma przypisany co najmniej jeden interfejs API.

  1. Zaloguj się do portalu, korzystając z następującego niestandardowego adresu URL dla funkcji aplikacji: https://portal.azure.com/?feature.customPortal=false&Microsoft_Azure_ApiManagement=aplikacje
  2. Przejdź do instancji usługi zarządzania API.
  3. W menu po lewej stronie w obszarze Interfejsy API wybierz pozycję Produkty.
  4. Wybierz produkt, który chcesz skonfigurować, na przykład produkt Starter .
  5. W menu po lewej stronie w obszarze Produkt wybierz pozycję Właściwości.
  6. W sekcji Dostęp oparty na aplikacji włącz ustawienie tokenu OAuth 2.0 (najbezpieczniejsze).
  7. Opcjonalnie włącz ustawienie Klucz subskrypcji . Jeśli włączysz zarówno dostęp oparty na aplikacji, jak i wymaganie dotyczące subskrypcji, brama usługi API Management może zaakceptować token OAuth 2.0 lub klucz subskrypcji w celu uzyskania dostępu do interfejsów API produktu.
  8. Wybierz Zapisz.

Zrzut ekranu przedstawiający włączanie dostępu opartego na aplikacji w portalu.

Wskazówka

Możesz również włączyć ustawienie tokenu OAuth 2.0 podczas tworzenia nowego produktu.

Umożliwienie dostępu poprzez aplikację tworzy aplikację zaplecza przedsiębiorstw w Microsoft Entra ID, reprezentującą produkt. Identyfikator aplikacji zaplecza jest wyświetlany na stronie Właściwości produktu.

Zrzut ekranu przedstawiający ustawienia aplikacji produktu w portalu.

Uwaga / Notatka

Ten identyfikator aplikacji jest ustawiany jako wartość Odbiorcy podczas tworzenia aplikacji klienckiej w celu uzyskania dostępu do produktu. Użyj również tej wartości podczas generowania tokenu w celu wywołania interfejsu API produktu.

(Opcjonalnie) Przeglądanie ustawień aplikacji produktu w identyfikatorze Entra firmy Microsoft

Opcjonalnie przejrzyj ustawienia aplikacji zaplecza biznesowego utworzonej w usłudze Microsoft Entra ID, aby reprezentować produkt.

Aplikacja ma następujący format: APIMProductApplication<product-name>. Jeśli na przykład nazwa produktu to Starter, nazwa aplikacji to APIMProductApplicationStarter. Aplikacja ma zdefiniowaną rolę Aplikacji .

Aby przejrzeć ustawienia aplikacji w obszarze Rejestracje aplikacji:

  1. Zaloguj się do portalu i przejdź do pozycji Microsoft Entra ID>Rejestracje aplikacji - zarządzanie.
  2. Wybierz pozycję Wszystkie aplikacje.
  3. Wyszukaj i wybierz aplikację utworzoną przez usługę API Management.
  4. W menu po lewej stronie w obszarze Zarządzanie wybierz pozycję Role aplikacji.
  5. Potwierdź rolę aplikacji ustawioną przez usługę Azure API Management, jak pokazano na poniższym zrzucie ekranu:

Zrzut ekranu przedstawiający role aplikacji w portalu.

Rejestrowanie aplikacji klienckiej w celu uzyskania dostępu do produktu

Teraz zarejestruj aplikację kliencką, która ogranicza dostęp do co najmniej jednego produktu.

  • Produkt musi mieć włączony dostęp oparty na aplikacji , aby był skojarzony z aplikacją kliencką.
  • Każda aplikacja kliencka ma jednego użytkownika (właściciela) w wystąpieniu usługi API Management. Tylko właściciel może uzyskiwać dostęp do interfejsów API produktów za pośrednictwem aplikacji.
  • Produkt może być skojarzony z więcej niż jedną aplikacją kliencką.

Aby zarejestrować aplikację kliencką:

  1. Zaloguj się do portalu pod następującym niestandardowym adresem URL funkcji aplikacji: https://portal.azure.com/?feature.customPortal=false&Microsoft_Azure_ApiManagement=aplikacje

  2. Przejdź do instancji usługi zarządzania API.

  3. W menu po lewej stronie w obszarze Interfejsy API wybierz pozycję Aplikacje>+ Zarejestruj aplikację.

  4. Na stronie Rejestrowanie aplikacji wprowadź następujące ustawienia aplikacji:

    • Nazwa: wprowadź nazwę aplikacji.
    • Właściciel: wybierz właściciela aplikacji z listy rozwijanej użytkowników w wystąpieniu usługi API Management.
    • Udziel dostępu do wybranych produktów: wybierz co najmniej jeden produkt w wystąpieniu usługi API Management, które zostało wcześniej włączone dla dostępu opartego na aplikacji.
    • Opis: opcjonalnie wprowadź opis.

    Zrzut ekranu przedstawiający ustawienia aplikacji w portalu.

  5. Wybierz pozycję Zarejestruj.

Aplikacja zostanie dodana do listy aplikacji na stronie Aplikacje . Wybierz aplikację, aby wyświetlić szczegóły, takie jak identyfikator klienta. Ten identyfikator jest potrzebny do wygenerowania tokenu w celu wywołania interfejsu API produktu.

Wskazówka

  • Po utworzeniu aplikacji opcjonalnie skojarz ją z innymi produktami. Wybierz aplikację na stronie Aplikacje , a następnie wybierz pozycję Szczegóły>produktów>+ Dodaj produkt.
  • Aplikację można również utworzyć lub skojarzyć, edytując produkt na stronie Produkty .

Generowanie tajnego klucza klienta

Aby aplikacja kliencka korzystała z przepływu poświadczeń klienta OAuth 2.0, należy wygenerować klucz tajny klienta. Wpis tajny jest ważny przez jeden rok, ale można go ponownie wygenerować w dowolnym momencie.

  1. Na stronie Aplikacje wybierz utworzoną aplikację.

  2. Na stronie Przegląd aplikacji obok Sekret klienta wybierz Dodaj sekret.

  3. Na stronie Nowy klucz tajny klienta wybierz pozycję Generuj.

    Wpis tajny klienta jest generowany i wyświetlany w polu Klucz tajny klienta . Pamiętaj, aby skopiować wartość wpisu tajnego i zapisać ją bezpiecznie. Po zamknięciu strony nie będzie można go ponownie pobrać.

  4. Wybierz Zamknij.

(Opcjonalnie) Przeglądanie ustawień aplikacji klienckiej w identyfikatorze Entra firmy Microsoft

Opcjonalnie przejrzyj ustawienia aplikacji klienckiej w identyfikatorze Entra firmy Microsoft.

Aplikacja ma następujący format: APIMApplication<product-name>. Jeśli na przykład nazwa produktu to Starter, nazwa aplikacji jest podobna do apiMApplicationStarter.

Aby przejrzeć ustawienia aplikacji w obszarze Rejestracje aplikacji:

  1. Zaloguj się do portalu i przejdź do pozycji Microsoft Entra ID>Rejestracje aplikacji - zarządzanie.

  2. Wybierz pozycję Wszystkie aplikacje.

  3. Wyszukaj i wybierz aplikację kliencą utworzoną przez usługę API Management.

  4. W menu po lewej stronie w obszarze Zarządzanie wybierz pozycję Uprawnienia interfejsu API.

  5. Upewnij się, że aplikacja ma uprawnienia do dostępu do aplikacji produktów zaplecza.

    Jeśli na przykład aplikacja kliencka udziela dostępu do produktu Starter , aplikacja ma uprawnienia Product.Starter.All w celu uzyskania dostępu do aplikacji APIMProductApplicationStarter .

    Zrzut ekranu przedstawiający uprawnienia interfejsu API w portalu.

Pobieranie ustawień aplikacji w portalu dla deweloperów

Użytkownicy mogą zalogować się do portalu deweloperów, aby wyświetlić aplikacje klienckie, których są właścicielami.

  1. Zaloguj się do portalu deweloperów (https://<your-apim-instance-name>.developer.azure-api.net) przy użyciu konta użytkownika ustawionego jako właściciel aplikacji klienckiej.

  2. W górnym menu nawigacji wybierz pozycję Aplikacje.

  3. Aplikacje, które użytkownik jest właścicielem, są wyświetlane na liście.

  4. Wybierz aplikację, aby wyświetlić jej szczegóły, takie jak identyfikator klienta, wpis tajny klienta i zakres. Te wartości są potrzebne do wygenerowania tokenu w celu wywołania interfejsów API produktu.

    Zrzut ekranu przedstawiający aplikacje klienckie w portalu dla deweloperów.

Tworzenie tokenu i używanie z wywołaniem interfejsu API

Po włączeniu dostępu opartego na aplikacji dla produktu i zarejestrowaniu aplikacji klienckiej deweloper lub aplikacja może wygenerować token w celu wywołania interfejsów API produktu. Token musi być uwzględniony w Authorization nagłówku żądania.

Na przykład deweloper lub aplikacja może uruchomić następujące skrypty programu Azure PowerShell, aby wywołać aplikację kliencką w celu wygenerowania tokenu, a następnie użyć tokenu do wywołania interfejsu API produktu w usłudze API Management.

Ostrzeżenie

Poniższe skrypty są przykładami tylko do celów testowych. W środowisku produkcyjnym użyj bezpiecznej metody do przechowywania i pobierania tajnego klucza klienta.

Wywoływanie aplikacji klienckiej w celu wygenerowania tokenu

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Wywoływanie interfejsu API produktu przy użyciu tokenu

Token wygenerowany w poprzednim kroku jest używany do wywoływania interfejsu API produktu. Token jest przekazywany w nagłówku Autoryzacja żądania. Wystąpienie usługi API Management weryfikuje token i autoryzuje dostęp do interfejsu API.

Poniższy skrypt przedstawia przykład użycia interfejsu API o nazwie "echo".

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Rozwiązywanie problemów

Wewnętrzny błąd serwera podczas rejestrowania aplikacji w portalu

Jeśli nie możesz wyświetlić listy aplikacji lub wystąpi wewnętrzny błąd serwera podczas rejestrowania aplikacji w portalu, sprawdź następujące kwestie:

Treści powiązane

  • Last updated on