Jak zabezpieczać interfejsy API przy użyciu uwierzytelniania za pomocą certyfikatów klienta w usłudze API Management

DOTYCZY: Wszystkie warstwy usługi API Management

Usługa API Management zapewnia możliwość zabezpieczenia dostępu do interfejsów API (czyli klienta do usługi API Management) przy użyciu certyfikatów klienta i wzajemnego uwierzytelniania TLS. Aby zweryfikować certyfikaty prezentowane przez klienta nawiązującego połączenie i sprawdzić właściwości certyfikatu względem żądanych wartości, można użyć wyrażeń zasad.

Aby uzyskać informacje na temat zabezpieczania dostępu do usługi zaplecza interfejsu API przy użyciu certyfikatów klienta (czyli usługi API Management do zaplecza), zobacz Jak zabezpieczyć usługi zaplecza przy użyciu uwierzytelniania certyfikatu klienta.

Aby zapoznać się z koncepcyjnym omówieniem autoryzacji interfejsu API, zobacz Uwierzytelnianie i autoryzacja interfejsów API w usłudze API Management.

Opcje certyfikatu

W celu weryfikacji certyfikatu usługa API Management może sprawdzać certyfikaty zarządzane w danym wystąpieniu usługi API Management. Jeśli zdecydujesz się na zarządzanie certyfikatami klienta przy użyciu usługi API Management, dostępne są następujące opcje:

• Odwołanie do certyfikatu zarządzanego w usłudze Azure Key Vault
• Dodanie pliku certyfikatu bezpośrednio w usłudze API Management

Korzystanie z certyfikatów magazynu kluczy jest zalecane, ponieważ pomaga zwiększyć bezpieczeństwo usługi API Management:

• Certyfikaty przechowywane w magazynach kluczy mogą być ponownie używane w usługach
• Szczegółowe zasady dostępu można stosować do certyfikatów przechowywanych w magazynach kluczy
• Certyfikaty aktualizowane w magazynie kluczy są automatycznie obracane w usłudze API Management. Po aktualizacji w magazynie kluczy certyfikat w usłudze API Management zostanie zaktualizowany w ciągu 4 godzin. Możesz również ręcznie odświeżyć certyfikat przy użyciu witryny Azure Portal lub interfejsu API REST zarządzania.

Wymagania wstępne

• Jeśli jeszcze nie utworzono wystąpienia usługi API Management, zobacz Tworzenie wystąpienia usługi API Management.

• Musisz mieć dostęp do certyfikatu i hasła do zarządzania w magazynie kluczy platformy Azure lub przekazać go do usługi API Management. Certyfikat musi być w formacie CER lub PFX. Certyfikaty z podpisem własnym są dozwolone.

  Jeśli używasz certyfikatu z podpisem własnym, zainstaluj również zaufane certyfikaty głównego i pośredniego urzędu certyfikacji w wystąpieniu usługi API Management.

  Uwaga

  Certyfikaty urzędu certyfikacji do weryfikacji certyfikatu nie są obsługiwane w warstwie Zużycie.

Wymagania wstępne dotyczące integracji z magazynem kluczy

1. Jeśli nie masz jeszcze magazynu kluczy, utwórz go. Aby uzyskać instrukcje tworzenia magazynu kluczy, zobacz Szybki start: tworzenie magazynu kluczy przy użyciu witryny Azure Portal.

   Aby utworzyć lub zaimportować certyfikat do magazynu kluczy, zobacz Szybki start: ustawianie i pobieranie certyfikatu z usługi Azure Key Vault przy użyciu witryny Azure Portal.

2. Włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika w wystąpieniu usługi API Management.

Konfigurowanie dostępu do magazynu kluczy

1. W portalu przejdź do magazynu kluczy.

2. W menu po lewej stronie wybierz pozycję Konfiguracja dostępu i zanotuj skonfigurowany model uprawnień.

3. W zależności od modelu uprawnień skonfiguruj zasady dostępu magazynu kluczy lub dostęp RBAC platformy Azure dla tożsamości zarządzanej usługi API Management.

   Aby dodać zasady dostępu do magazynu kluczy:
   

   1. W menu po lewej stronie wybierz pozycję Zasady dostępu.
   2. Na stronie Zasady dostępu wybierz pozycję + Utwórz.
   3. Na karcie Uprawnienia w obszarze Uprawnienia w obszarze Uprawnienia tajne wybierz pozycję Pobierz i listę, a następnie wybierz pozycję Dalej.
   4. Na karcie Podmiot zabezpieczeń wybierz jednostkę, wyszukaj nazwę zasobu tożsamości zarządzanej, a następnie wybierz pozycję Dalej. Jeśli używasz tożsamości przypisanej przez system, podmiot zabezpieczeń to nazwa wystąpienia usługi API Management.
   5. Ponownie wybierz przycisk Dalej . Na karcie Przeglądanie i tworzenie wybierz pozycję Utwórz.

   Aby skonfigurować dostęp RBAC platformy Azure:
   

   1. W menu po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami)..
   2. Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz pozycję Dodaj przypisanie roli.
   3. Na karcie Rola wybierz pozycję Użytkownik wpisów tajnych usługi Key Vault.
   4. Na karcie Członkowie wybierz pozycję Tożsamość> zarządzana+ Wybierz członków.
   5. Na stronie Wybieranie tożsamości zarządzanej wybierz tożsamość zarządzaną przypisaną przez system lub tożsamość zarządzaną przypisaną przez użytkownika skojarzona z wystąpieniem usługi API Management, a następnie wybierz pozycję Wybierz.
   6. Wybierz Przejrzyj + przypisz.

Wymagania dotyczące zapory usługi Key Vault

Jeśli zapora usługi Key Vault jest włączona w magazynie kluczy, są spełnione następujące dodatkowe wymagania:

• Aby uzyskać dostęp do magazynu kluczy, musisz użyć przypisanej przez system tożsamości zarządzanej wystąpienia usługi API Management.

• W zaporze usługi Key Vault włącz opcję Zezwalaj zaufanym usługom firmy Microsoft na obejście tej zapory .

• Upewnij się, że lokalny adres IP klienta może tymczasowo uzyskać dostęp do magazynu kluczy podczas wybierania certyfikatu lub wpisu tajnego, który ma zostać dodany do usługi Azure API Management. Aby uzyskać więcej informacji, zobacz Konfigurowanie ustawień sieci usługi Azure Key Vault.

  Po zakończeniu konfiguracji możesz zablokować adres klienta w zaporze magazynu kluczy.

Wymagania dotyczące sieci wirtualnej

Jeśli wystąpienie usługi API Management zostało wdrożone w sieci wirtualnej, skonfiguruj również następujące ustawienia sieciowe:

• Włącz punkt końcowy usługi w usłudze Azure Key Vault w podsieci usługi API Management.
• Skonfiguruj regułę sieciowej grupy zabezpieczeń, aby zezwolić na ruch wychodzący do tagów usługi AzureKeyVault i AzureActiveDirectory.

Aby uzyskać szczegółowe informacje, zobacz Konfiguracja sieci podczas konfigurowania usługi Azure API Management w sieci wirtualnej.

Dodawanie certyfikatu magazynu kluczy

Zobacz Wymagania wstępne dotyczące integracji magazynu kluczy.

Ważne

Podczas dodawania certyfikatu magazynu kluczy do wystąpienia usługi API Management musisz mieć uprawnienia do wyświetlania listy wpisów tajnych z magazynu kluczy.

Uwaga

W przypadku korzystania z certyfikatu magazynu kluczy w usłudze API Management należy zachować ostrożność, aby nie usuwać certyfikatu, magazynu kluczy lub tożsamości zarządzanej używanej do uzyskiwania dostępu do magazynu kluczy.

Aby dodać certyfikat magazynu kluczy do usługi API Management:

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.

2. W obszarze Zabezpieczenia wybierz pozycję Certyfikaty.

3. Wybierz pozycję Certyfikaty>+ Dodaj.

4. W polu Id (Identyfikator) wprowadź wybraną nazwę.

5. W obszarze Certyfikat wybierz pozycję Magazyn kluczy.

6. Wprowadź identyfikator certyfikatu magazynu kluczy lub wybierz pozycję Wybierz , aby wybrać certyfikat z magazynu kluczy.

   Ważne

   Jeśli samodzielnie wprowadzisz identyfikator certyfikatu magazynu kluczy, upewnij się, że nie ma informacji o wersji. W przeciwnym razie certyfikat nie będzie automatycznie obracany w usłudze API Management po aktualizacji w magazynie kluczy.

7. W obszarze Tożsamość klienta wybierz tożsamość zarządzaną przypisaną przez system lub istniejącą tożsamość zarządzaną przypisaną przez użytkownika. Dowiedz się, jak dodawać lub modyfikować tożsamości zarządzane w usłudze API Management.

   Uwaga

   Tożsamość musi mieć uprawnienia do pobierania i wyświetlania listy certyfikatów z magazynu kluczy. Jeśli nie skonfigurowano jeszcze dostępu do magazynu kluczy, usługa API Management wyświetli monit o automatyczne skonfigurowanie tożsamości przy użyciu niezbędnych uprawnień.

8. Wybierz Dodaj.

   

9. Wybierz pozycję Zapisz.

Przekaż certyfikat

Aby przekazać certyfikat klienta do usługi API Management:

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.

2. W obszarze Zabezpieczenia wybierz pozycję Certyfikaty.

3. Wybierz pozycję Certyfikaty>+ Dodaj.

4. W polu Id (Identyfikator) wprowadź wybraną nazwę.

5. W obszarze Certyfikat wybierz pozycję Niestandardowy.

6. Przejdź do wybrania pliku pfx certyfikatu i wprowadź jego hasło.

7. Wybierz Dodaj.

   

8. Wybierz pozycję Zapisz.

Uwaga

Jeśli chcesz użyć certyfikatu tylko do uwierzytelniania klienta za pomocą usługi API Management, możesz przekazać plik CER.

Włączanie wystąpienia usługi API Management w celu odbierania i weryfikowania certyfikatów klienta

Deweloper, Podstawowa, Standardowa lub Premium

Aby odbierać i weryfikować certyfikaty klienta za pośrednictwem protokołu HTTP/2 w bloku Domena niestandardowa, Podstawowa, Podstawowa, Podstawowa, Standardowa, Standardowa, Standardowa v2 lub Premium, należy włączyć ustawienie Certyfikat klienta Negocjuj w bloku Domena niestandardowa, jak pokazano poniżej.

Warstwa Zużycie

Aby odbierać i weryfikować certyfikaty klienta w warstwie Zużycie, należy włączyć ustawienie Żądaj certyfikatu klienta w bloku Domeny niestandardowe, jak pokazano poniżej.

Zasady do weryfikowania certyfikatów klienta

Użyj zasad validate-client-certificate, aby zweryfikować co najmniej jeden atrybut certyfikatu klienta używanego do uzyskiwania dostępu do interfejsów API hostowanych w wystąpieniu usługi API Management.

Skonfiguruj zasady, aby zweryfikować co najmniej jeden atrybut, w tym wystawcę certyfikatu, podmiot, odcisk palca, czy certyfikat jest weryfikowany na liście odwołania online i innych.

Walidacja certyfikatu ze zmiennymi kontekstowymi

Możesz również utworzyć wyrażenia zasad ze zmienną , context aby sprawdzić certyfikaty klienta. Przykłady w poniższych sekcjach pokazują wyrażenia używające context.Request.Certificate właściwości i innych context właściwości.

Uwaga

Wzajemne uwierzytelnianie certyfikatów może nie działać poprawnie, gdy punkt końcowy bramy usługi API Management jest uwidoczniony za pośrednictwem usługi Application Gateway. Dzieje się tak, ponieważ usługa Application Gateway działa jako moduł równoważenia obciążenia warstwy 7, ustanawiając odrębne połączenie SSL z usługą API Management zaplecza. W związku z tym certyfikat dołączony przez klienta w początkowym żądaniu HTTP nie będzie przekazywany do usługi APIM. Jednak jako obejście problemu można przesłać certyfikat przy użyciu opcji zmienne serwera. Aby uzyskać szczegółowe instrukcje, zapoznaj się ze zmiennymi serwera wzajemnego uwierzytelniania.

Ważne

• Od maja 2021 r context.Request.Certificate . właściwość żąda certyfikatu tylko wtedy, gdy wystąpienie hostnameConfiguration usługi API Management ustawia negotiateClientCertificate właściwość na true. Domyślnie negotiateClientCertificate jest ustawiona wartość Fałsz.
• Jeśli renegocjacja protokołu TLS jest wyłączona w kliencie, podczas żądania certyfikatu context.Request.Certificate przy użyciu właściwości mogą wystąpić błędy protokołu TLS. W takim przypadku włącz ustawienia renegocjacji PROTOKOŁU TLS w kliencie.
• Renegocjacja certyfikatów nie jest obsługiwana w warstwach usługi API Management w wersji 2.

Sprawdzanie wystawcy i podmiotu

Poniższe zasady można skonfigurować do sprawdzania wystawcy i podmiotu certyfikatu klienta:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Uwaga

Aby wyłączyć sprawdzanie listy odwołania certyfikatówcontext.Request.Certificate.Verify(), użyj polecenia context.Request.Certificate.VerifyNoRevocation() zamiast . Jeśli certyfikat klienta jest certyfikatem z podpisem własnym, certyfikaty głównego (lub pośredniego) urzędu certyfikacji muszą zostać przekazane do usługi API Management i context.Request.Certificate.Verify()context.Request.Certificate.VerifyNoRevocation() do pracy.

Sprawdzanie odcisku palca

Poniższe zasady można skonfigurować pod kątem sprawdzania odcisku palca certyfikatu klienta:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Uwaga

Aby wyłączyć sprawdzanie listy odwołania certyfikatówcontext.Request.Certificate.Verify(), użyj polecenia context.Request.Certificate.VerifyNoRevocation() zamiast . Jeśli certyfikat klienta jest certyfikatem z podpisem własnym, certyfikaty głównego (lub pośredniego) urzędu certyfikacji muszą zostać przekazane do usługi API Management i context.Request.Certificate.Verify()context.Request.Certificate.VerifyNoRevocation() do pracy.

Sprawdzanie odcisku palca względem certyfikatów przekazanych do usługi API Management

W poniższym przykładzie pokazano, jak sprawdzić odcisk palca certyfikatu klienta względem certyfikatów przekazanych do usługi API Management:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Uwaga

Aby wyłączyć sprawdzanie listy odwołania certyfikatówcontext.Request.Certificate.Verify(), użyj polecenia context.Request.Certificate.VerifyNoRevocation() zamiast . Jeśli certyfikat klienta jest certyfikatem z podpisem własnym, certyfikaty głównego (lub pośredniego) urzędu certyfikacji muszą zostać przekazane do usługi API Management i context.Request.Certificate.Verify()context.Request.Certificate.VerifyNoRevocation() do pracy.

Napiwek

Problem z zakleszczeniem certyfikatu klienta opisany w tym artykule może manifestować się na kilka sposobów, np. żądania zawieszają się, żądania powodują kod 403 Forbidden stanu po upłynął limit czasu, context.Request.Certificate to null. Ten problem zwykle dotyczy żądań POST o PUT długości zawartości o długości około 60 KB lub większej. Aby zapobiec wystąpieniu tego problemu, włącz ustawienie "Negocjuj certyfikat klienta" dla żądanych nazw hostów w bloku "Domeny niestandardowe", jak pokazano na pierwszym obrazie tego dokumentu. Ta funkcja nie jest dostępna w warstwie Zużycie.

Następne kroki

• Jak zabezpieczyć usługi zaplecza przy użyciu uwierzytelniania certyfikatu klienta
• Jak dodać niestandardowy certyfikat urzędu certyfikacji w usłudze Azure API Management
• Dowiedz się więcej o zasadach w usłudze API Management