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ć informacje na temat tworzenia magazynu kluczy, zobacz Szybki start: tworzenie magazynu kluczy przy użyciu witryny Azure Portal.

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

Konfigurowanie dostępu do magazynu kluczy

1. W portalu przejdź do skrytki kluczy.
2. W menu po lewej stronie wybierz pozycję Ustawienia>Konfiguracja dostępu. Zwróć uwagę na 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 wyświetl, a następnie wybierz pozycję Dalej.
4. Na karcie Główne 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 utworzyć certyfikat w magazynie kluczy 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.

Wymagania dotyczące zapory usługi Key Vault

Jeśli zapora usługi Key Vault jest włączona w magazynie kluczy, musisz spełnić następujące wymagania:

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

• W zaporze usługi Key Vault włącz opcję Zezwalaj zaufanym usługom firmy Microsoft na obejście tej zapory . Usługa API Management obsługuje łączność z zaufaną usługą w celu uzyskania dostępu do magazynu kluczy dla opcji płaszczyzny sterowania.

• 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 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 API Management w sieci wirtualnej.

Dodawanie certyfikatu magazynu kluczy

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

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

1. W portalu Azure przejdź do wystąpienia API Management.

2. W obszarze Zabezpieczenia wybierz pozycję Certyfikaty.

3. Wybierz pozycję Certyfikaty>+ Dodaj.

4. W polu Id (Identyfikator) wprowadź 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 skrytki kluczy, upewnij się, że nie zawiera on 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ść przypisaną przez system lub istniejącą tożsamość zarządzaną przypisaną przez użytkownika. Aby uzyskać więcej informacji, zobacz Używanie tożsamości zarządzanych w usłudze Azure API Management.

   Uwaga

   Tożsamość musi mieć uprawnienia do pobierania i wyświetlania listy certyfikatów z magazynu kluczy. Jeśli jeszcze nie skonfigurowano 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 portalu Azure przejdź do wystąpienia API Management.

2. W obszarze Zabezpieczenia wybierz pozycję Certyfikaty.

3. Wybierz pozycję Certyfikaty>+ Dodaj.

4. W polu Id (Identyfikator) wprowadź 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.

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 warstwach Deweloper, Podstawowa, Standardowa lub Premium, należy włączyć ustawienie Negocjować certyfikat klienta w bloku Domena niestandardowa, jak pokazano poniżej.

Zużycie, Podstawowa wersja 2, Standardowa v2 lub Warstwa Premium w wersji 2

Aby odbierać i weryfikować certyfikaty klienta w warstwie Zużycie, Podstawowa wersja 2, Standardowa v2 lub Premium v2, 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.

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>

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>

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>

Treści powiązane

• 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