Udostępnij za pośrednictwem

Subskrypcje w usłudze Azure API Management

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

W usłudze Azure API Management subskrypcje są najczęstszym sposobem, w jaki użytkownicy interfejsu API uzyskują dostęp do interfejsów API opublikowanych za pośrednictwem wystąpienia usługi API Management. Ten artykuł zawiera omówienie koncepcji.

Uwaga

Subskrypcja usługi API Management jest używana specjalnie do wywoływania interfejsów API za pośrednictwem usługi API Management przy użyciu klucza subskrypcji. Nie jest to samo co subskrypcja platformy Azure.

Co to są subskrypcje?

Publikując interfejsy API za pośrednictwem funkcji API Management, możesz łatwo zabezpieczyć dostęp do nich za pomocą kluczy subskrypcji. Deweloperzy, którzy muszą korzystać z opublikowanych interfejsów API, muszą dołączyć prawidłowy klucz subskrypcji do żądań HTTP podczas wywoływania tych interfejsów API. Bez prawidłowego klucza subskrypcji wywołania są następujące:

  • Odrzucone natychmiast przez bramę API Management.
  • Nie są przekazywane do usług zaplecza.

Aby uzyskać dostęp do interfejsów API, deweloperzy potrzebują subskrypcji i klucza subskrypcji. Subskrypcja jest nazwanym kontenerem dla pary kluczy subskrypcji.

W dodatku

  • Deweloperzy mogą pobierać subskrypcje bez konieczności zatwierdzania od wydawców interfejsu API.
  • Wydawcy interfejsu API mogą tworzyć subskrypcje bezpośrednio dla użytkowników interfejsu API.

Napiwek

Usługa API Management obsługuje również inne mechanizmy zabezpieczania dostępu do interfejsów API, w tym następujące przykłady:

Zarządzanie kluczami subskrypcji

Regularne ponowne generowanie kluczy jest typowym środkiem ostrożności. Podobnie jak większość usług platformy Azure wymagających klucza subskrypcji, usługa API Management generuje klucze w parach. Każda aplikacja korzystająca z usługi może przełączyć się z klucza A na klucz B i ponownie wygenerować klucz A z minimalnymi zakłóceniami i odwrotnie.

Ustawienie określonych kluczy zamiast ponownego generowania może być wykonywane przez wywołanie subskrypcji usługi Azure API Management — tworzenie lub aktualizowanie interfejsu API REST platformy Azure. W szczególności element properties.primaryKey i/lub properties.secondaryKey należy go ustawić w treści żądania HTTP.

Uwaga

  • Usługa API Management nie udostępnia wbudowanych funkcji do zarządzania cyklem życia kluczy subskrypcji, takich jak ustawianie dat wygaśnięcia lub automatyczne obracanie kluczy. Przepływy pracy można opracowywać w celu zautomatyzowania tych procesów przy użyciu narzędzi, takich jak program Azure PowerShell lub zestawy SDK platformy Azure.
  • Aby wymusić ograniczony czas dostępu do interfejsów API, wydawcy interfejsu API mogą mieć możliwość używania zasad z kluczami subskrypcji lub użyć mechanizmu zapewniającego wbudowane wygaśnięcie, takie jak uwierzytelnianie oparte na tokenach.

Zakres subskrypcji

Subskrypcje mogą być skojarzone z różnymi zakresami: produktem, wszystkimi interfejsami API lub indywidualnym interfejsem API.

Subskrypcje produktu

Tradycyjnie subskrypcje w usłudze API Management były skojarzone z pojedynczym zakresem produktu . Deweloperzy:

  • Znaleziono listę produktów w portalu dla deweloperów.
  • Przesłane żądania subskrypcji dotyczące produktów, których chcieli użyć.
  • Użyj kluczy w tych subskrypcjach (zatwierdzonych automatycznie lub przez wydawców interfejsu API), aby uzyskać dostęp do wszystkich interfejsów API w produkcie.

Obecnie portal dla deweloperów pokazuje tylko subskrypcje zakresu produktów w sekcji Profil użytkownika.

Subskrypcje produktu

Subskrypcje dla wszystkich interfejsów API lub pojedynczego interfejsu API

Możesz również utworzyć klucze, które udzielają dostępu do jednego z następujących:

  • Pojedynczy interfejs API lub
  • Wszystkie interfejsy API w wystąpieniu usługi API Management.

W takich przypadkach nie musisz najpierw tworzyć produktu i dodawać do niego interfejsy API.

Subskrypcja z dostępem wszystkim

Każde wystąpienie usługi API Management zawiera wbudowaną subskrypcję z dostępem do wszystkich interfejsów API, która udziela dostępu do wszystkich interfejsów API. Ta subskrypcja obejmująca zakres usług ułatwia właścicielom usług testowanie i debugowanie interfejsów API w konsoli testowej.

Ostrzeżenie

Subskrypcja all-access umożliwia dostęp do każdego interfejsu API w wystąpieniu usługi API Management i powinna być używana tylko przez autoryzowanych użytkowników. Nigdy nie używaj tej subskrypcji do rutynowego dostępu do interfejsu API ani osadzania klucza subskrypcji dostępu do wszystkich w aplikacjach klienckich.

Uwaga

Jeśli używasz subskrypcji o zakresie interfejsu API, subskrypcji wszystkich interfejsów API lub wbudowanej subskrypcji z dostępem do wszystkich, zasady skonfigurowane w zakresie produktu nie są stosowane do żądań z tej subskrypcji.

Subskrypcje autonomiczne

Usługa API Management umożliwia również autonomiczne subskrypcje, które nie są skojarzone z kontem dewelopera. Ta funkcja okazuje się przydatna w scenariuszach podobnych do kilku deweloperów lub zespołów korzystających z subskrypcji.

Tworzenie subskrypcji bez przypisywania właściciela sprawia, że jest to subskrypcja autonomiczna. Aby udzielić deweloperom i pozostałej części zespołu dostępu do autonomicznego klucza subskrypcji, wykonaj następujące czynności:

  • Ręcznie udostępnij klucz subskrypcji.
  • Użyj systemu niestandardowego, aby udostępnić klucz subskrypcji zespołowi.

Tworzenie subskrypcji i zarządzanie nimi w witrynie Azure Portal

Wydawcy interfejsu API mogą tworzyć subskrypcje bezpośrednio w witrynie Azure Portal.

Po utworzeniu w portalu subskrypcja jest w stanie Aktywny , co oznacza, że subskrybent może wywołać skojarzony interfejs API przy użyciu prawidłowego klucza subskrypcji. Możesz zmienić stan subskrypcji zgodnie z potrzebami. Możesz na przykład wstrzymać, anulować lub usunąć dowolną subskrypcję (w tym wbudowaną subskrypcję z dostępem wszystkim), aby uniemożliwić dostęp do interfejsu API.

Używanie klucza subskrypcji

Subskrybent może użyć klucza subskrypcji usługi API Management na jeden z dwóch sposobów:

  • Dodaj nagłówek HTTP Ocp-Apim-Subscription-Key do żądania, przekazując wartość prawidłowego klucza subskrypcji.

  • Uwzględnij parametr zapytania subscription-key i prawidłową wartość w adresie URL. Parametr zapytania jest sprawdzany tylko wtedy, gdy nagłówek nie jest obecny.

Napiwek

Ocp-Apim-Subscription-Key jest domyślną nazwą nagłówka klucza subskrypcji, a klucz-subskrypcji jest domyślną nazwą parametru zapytania. W razie potrzeby można zmodyfikować te nazwy w ustawieniach dla każdego interfejsu API. Na przykład w portalu zaktualizuj te nazwy na karcie Ustawienia interfejsu API.

Uwaga

W przypadku dołączania do nagłówka żądania lub parametru zapytania klucz subskrypcji jest domyślnie przekazywany do zaplecza i może być uwidoczniony w dziennikach monitorowania zaplecza lub w innych systemach. Jeśli jest to uważane za poufne dane, możesz skonfigurować zasady na końcu inbound sekcji, aby usunąć nagłówek klucza subskrypcji (set-header) lub parametr zapytania (set-query-parameter).

Włączanie lub wyłączanie wymagań dotyczących subskrypcji dla interfejsu API lub dostępu do produktu

Domyślnie podczas tworzenia interfejsu API klucz subskrypcji jest wymagany do uzyskiwania dostępu do interfejsu API. Podobnie podczas tworzenia produktu domyślnie klucz subskrypcji jest wymagany do uzyskania dostępu do dowolnego interfejsu API dodanego do produktu. W niektórych scenariuszach wydawca interfejsu API może chcieć opublikować produkt lub określony interfejs API do publicznej wiadomości bez konieczności używania subskrypcji. Chociaż wydawca może zdecydować się na włączenie niezabezpieczonego (anonimowego) dostępu do niektórych interfejsów API, zaleca się skonfigurowanie innego mechanizmu zabezpieczania dostępu klienta.

Uwaga

Podczas konfigurowania produktu lub interfejsu API, który nie wymaga subskrypcji, należy zachować ostrożność. Ta konfiguracja może być nadmiernie permisywna i może sprawić, że interfejs API będzie bardziej podatny na niektóre zagrożenia bezpieczeństwa interfejsu API.

Uwaga

Otwarte produkty mają wyłączone ustawienie Wymaga subskrypcji , co oznacza, że użytkownicy nie muszą go subskrybować. Z tego powodu otwarte produkty nie są wyświetlane na stronie Produkty portalu dla deweloperów.

Możesz wyłączyć wymaganie subskrypcji w momencie tworzenia interfejsu API lub produktu lub w późniejszym terminie.

Aby wyłączyć wymaganie dotyczące subskrypcji przy użyciu portalu:

  • Wyłącz wymaganie dotyczące produktu — na stronie Ustawienia produktu wyłącz opcję Wymaga subskrypcji
  • Wyłącz wymaganie dotyczące interfejsu API — na stronie Ustawienia interfejsu API wyłącz opcję Wymagana subskrypcja.

Po wyłączeniu wymagania dotyczącego subskrypcji można uzyskać dostęp do wybranego interfejsu API lub interfejsów API bez klucza subskrypcji.

Jak usługa API Management obsługuje żądania z kluczami subskrypcji lub bez tych kluczy

Żądanie interfejsu API z kluczem subskrypcji

Gdy funkcja API Management otrzyma żądanie API od klienta z kluczem subskrypcji, obsługuje żądanie zgodnie z poniższymi regułami:

  1. Najpierw sprawdź, czy jest to prawidłowy klucz skojarzony z aktywną subskrypcją:

    • Subskrypcja określona zakresem interfejsu API
    • Subskrypcja określona zakresem dla produktu przypisanego do interfejsu API
    • Subskrypcja określona zakresem wszystkich interfejsów API
    • Subskrypcja o zakresie usługi (wbudowana subskrypcja dostępu)

    Jeśli podano prawidłowy klucz dla aktywnej subskrypcji w odpowiednim zakresie, dostęp jest dozwolony. Zasady są stosowane w zależności od konfiguracji definicji zasad w tym zakresie.

  2. Jeśli klucz nie jest prawidłowy, ale produkt istnieje, który zawiera interfejs API, ale nie wymaga subskrypcji (otwartego produktu), zignoruj klucz i obsłuż jako żądanie interfejsu API bez klucza subskrypcji (zobacz poniżej).

  3. W przeciwnym razie dostęp zostanie zablokowany (błąd odmowy dostępu 401).

Żądanie interfejsu API bez klucza subskrypcji

Gdy funkcja API Management otrzyma żądanie API od klienta bez klucza subskrypcji, obsługuje żądanie zgodnie z tymi regułami:

  1. Najpierw sprawdź istnienie produktu, który zawiera interfejs API, ale nie wymaga subskrypcji ( otwartego produktu). Jeśli otwarty produkt istnieje, obsłuż żądanie w kontekście interfejsów API, zasad i reguł dostępu skonfigurowanych dla otwartego produktu. Interfejs API może być skojarzony z co najwyżej jednym otwartym produktem.
  2. Jeśli nie znaleziono otwartego produktu zawierającego interfejs API, sprawdź, czy interfejs API wymaga subskrypcji. Jeśli subskrypcja nie jest wymagana, obsłuż żądanie w kontekście tego interfejsu API i operacji.
  3. Jeśli nie znaleziono skonfigurowanego produktu lub interfejsu API, dostęp zostanie zablokowany (błąd odmowy dostępu 401).

Tabela podsumowania

Poniższa tabela zawiera podsumowanie sposobu obsługi żądań interfejsu API przez bramę z kluczami subskrypcji lub bez nich w różnych scenariuszach. Zanotowano konfiguracje, które mogą potencjalnie umożliwić niezamierzony, anonimowy dostęp do interfejsu API.

Wszystkie produkty przypisane do interfejsu API wymagają subskrypcji Interfejs API wymaga subskrypcji Wywołanie interfejsu API z kluczem subskrypcji Wywołanie interfejsu API bez klucza subskrypcji Typowe scenariusze
✔️ ✔️ Dozwolony dostęp:

• Klucz o zakresie produktu
• Klucz o zakresie interfejsu API
• Cały klucz o zakresie interfejsów API
• Klucz o zakresie usługi

Odmowa dostępu:

• Inny klucz, który nie ma zakresu dla odpowiedniego produktu lub interfejsu API		 Odmowa dostępu Chroniony dostęp do interfejsu API przy użyciu subskrypcji o zakresie produktu lub interfejsu API
✔️ ❌ Dozwolony dostęp:

• Klucz o zakresie produktu
• Klucz o zakresie interfejsu API
• Cały klucz o zakresie interfejsów API
• Klucz o zakresie usługi
• Inny klucz, który nie ma zakresu dla odpowiedniego produktu lub interfejsu API		 Dostęp dozwolony (kontekst interfejsu API) • Chroniony dostęp do interfejsu API z subskrypcją obejmującą zakres produktów

• Anonimowy dostęp do interfejsu API. Jeśli dostęp anonimowy nie jest zamierzony, skonfiguruj zasady na poziomie interfejsu API w celu wymuszania uwierzytelniania i autoryzacji.
❌1 ✔️ Dozwolony dostęp:

• Klucz o zakresie produktu
• Klucz o zakresie interfejsu API
• Cały klucz o zakresie interfejsów API
• Klucz o zakresie usługi

Odmowa dostępu:

• Inny klucz, który nie ma zakresu dla odpowiedniego produktu lub interfejsu API		 Dostęp dozwolony (otwarty kontekst produktu) • Chroniony dostęp do interfejsu API z subskrypcją o zakresie interfejsu API

• Anonimowy dostęp do interfejsu API. Jeśli dostęp anonimowy nie jest zamierzony, skonfiguruj przy użyciu zasad produktu w celu wymuszania uwierzytelniania i autoryzacji
❌1 ❌ Dozwolony dostęp:

• Klucz o zakresie produktu
• Klucz o zakresie interfejsu API
• Cały klucz o zakresie interfejsów API
• Klucz o zakresie usługi
• Inny klucz, który nie ma zakresu dla odpowiedniego produktu lub interfejsu API		 Dostęp dozwolony (otwarty kontekst produktu) Anonimowy dostęp do interfejsu API. Jeśli dostęp anonimowy nie jest zamierzony, skonfiguruj przy użyciu zasad produktu w celu wymuszania uwierzytelniania i autoryzacji

1 Otwarty produkt istnieje skojarzony z interfejsem API.

Kwestie wymagające rozważenia

  • Dostęp do interfejsu API w kontekście produktu jest taki sam, niezależnie od tego, czy produkt jest publikowany, czy nie. Cofanie publikowania produktu powoduje ukrycie go w portalu deweloperów, ale nie powoduje unieważnienia nowych ani istniejących kluczy subskrypcji.
  • Jeśli interfejs API nie wymaga uwierzytelniania subskrypcji, każde żądanie interfejsu API zawierające klucz subskrypcji jest traktowane tak samo jak żądanie bez klucza subskrypcji. Klucz subskrypcji jest ignorowany.
  • Dostęp do interfejsu API "kontekst" oznacza zasady i mechanizmy kontroli dostępu stosowane w określonym zakresie (na przykład interfejs API lub produkt).

Następne kroki

Uzyskaj więcej informacji na temat usługi API Management: