Zabezpieczanie usług zaplecza przy użyciu uwierzytelniania certyfikatu klienta w usłudze Azure API Management

2025-06-02

DOTYCZY: Wszystkich poziomów zarządzania API

Usługa API Management umożliwia zabezpieczanie dostępu do usługi zaplecza interfejsu API przy użyciu certyfikatów klienta i wzajemnego uwierzytelniania TLS. W tym artykule pokazano, jak zarządzać certyfikatami w usłudze API Management przy użyciu witryny Azure Portal. Wyjaśniono również, jak skonfigurować interfejs API do używania certyfikatu w celu uzyskania dostępu do usługi zaplecza.

Certyfikaty usługi API Management można również zarządzać przy użyciu interfejsu API REST usługi API Management.

Opcje certyfikatu

Usługa API Management oferuje dwie opcje zarządzania certyfikatami używanymi do zabezpieczania dostępu do usług zaplecza:

Odwołuj się do certyfikatu zarządzanego w usłudze Azure Key Vault.
Dodaj plik certyfikatu bezpośrednio w usłudze API Management.

Zalecamy używanie certyfikatów magazynu kluczy, ponieważ to poprawia bezpieczeństwo zarządzania API.

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 skarbcach kluczy.
Certyfikaty aktualizowane w magazynie kluczy są automatycznie rotowane w usłudze API Management. Po aktualizacji w magazynie kluczy certyfikat w usłudze API Management zostanie zaktualizowany w ciągu czterech 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

Uwaga / Notatka

Zalecamy użycie modułu Azure Az PowerShell do interakcji z Azure. Aby rozpocząć, zobacz Instalowanie programu Azure PowerShell. Aby dowiedzieć się, jak przeprowadzić migrację do modułu Az PowerShell, zobacz Migracja programu Azure PowerShell z modułu AzureRM do modułu Az.

Jeśli jeszcze nie utworzono wystąpienia usługi API Management, zobacz Tworzenie wystąpienia usługi API Management.
Skonfiguruj uwierzytelnianie certyfikatu klienta usługi zaplecza. Aby uzyskać informacje na temat konfigurowania uwierzytelniania certyfikatów w usłudze Azure App Service, zobacz Konfigurowanie wzajemnego uwierzytelniania TLS w usłudze App Service.
Upewnij się, że masz dostęp do certyfikatu i hasła do zarządzania w magazynie kluczy platformy Azure lub certyfikatu do przekazania do usługi API Management. Certyfikat musi być w formacie PFX. Certyfikaty z podpisem własnym są dozwolone.

Jeśli używasz certyfikatu z podpisem własnym:
- Zainstaluj zaufane certyfikaty głównego i pośredniego CA w wystąpieniu usługi API Management.
  
  Uwaga / Notatka
  
  Certyfikaty urzędu certyfikacji do weryfikacji certyfikatów nie są obsługiwane w warstwie Zużycie.
- Wyłącz walidację łańcucha certyfikatów. Zobacz Wyłączanie walidacji łańcucha certyfikatów dla certyfikatów z podpisem własnym w dalszej części tego artykułu.

Wymagania wstępne dotyczące integracji z sejfem kluczy

Uwaga / Notatka

Obecnie ta funkcja nie jest dostępna w obszarach roboczych.

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

W portalu przejdź do skrytki kluczy.
W menu po lewej stronie wybierz pozycję Konfiguracja dostępu. Zwróć uwagę na skonfigurowany model uprawnień .
W zależności od modelu uprawnień skonfiguruj albo politykę dostępu do magazynu kluczy, albo dostęp platformy Azure RBAC dla zarządzanej tożsamości w usłudze API Management.

Aby dodać zasady dostępu do magazynu kluczy:

W menu po lewej stronie wybierz pozycję Zasady dostępu.
Na stronie Zasady dostępu wybierz pozycję + Utwórz.
Na karcie Uprawnienia w obszarze Uprawnienia w obszarze Uprawnienia tajne wybierz pozycję Pobierz i wyświetl, a następnie wybierz pozycję Dalej.
Na karcie Podmiot wybierz pozycję Podmiot, wyszukaj nazwę zasobu tożsamości zarządzanej, a następnie wybierz Dalej. Jeśli używasz tożsamości przypisanej przez system, podmiot to nazwa wystąpienia usługi API Management.
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 .
Upewnij się, że twój lokalny adres IP klienta może tymczasowo uzyskać dostęp do sejfu kluczy, podczas wybierania certyfikatu lub tajemnicy, które mają zostać dodane do usługi zarządzania API Azure. 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ń (NSG), aby zezwolić na ruch wychodzący do tagów usług AzureKeyVault i AzureActiveDirectory.

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

Dodaj certyfikat do skarbca kluczy

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

Ważne

Aby dodać certyfikat magazynu kluczy do wystąpienia usługi API Management, musisz mieć uprawnienia do przeglądania tajemnic w magazynie kluczy.

Ostrzeżenie

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:

W portalu Azure przejdź do wystąpienia API Management.
W obszarze Zabezpieczenia wybierz pozycję Certyfikaty.
Wybierz pozycję Certyfikaty>+ Dodaj.
W polu Id (Identyfikator) wprowadź nazwę.
W obszarze Certyfikat wybierz pozycję Magazyn kluczy.
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 odnawiany w usłudze zarządzania API po aktualizacji w skarbcu kluczy.
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 / Notatka

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ń.
Wybierz Dodaj.
Wybierz Zapisz.

Przekaż certyfikat

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

W portalu Azure przejdź do wystąpienia API Management.
W obszarze Zabezpieczenia wybierz pozycję Certyfikaty.
Wybierz pozycję Certyfikaty>+ Dodaj.
W polu Id (Identyfikator) wprowadź nazwę.
W Certyfikacie wybierz Niestandardowe.
Przeglądaj, aby wybrać plik certyfikatu .pfx i wprowadź hasło tego pliku.
Wybierz Dodaj.
Wybierz Zapisz.

Po przesłaniu certyfikatu pojawi się w oknie Certyfikaty. Jeśli masz wiele certyfikatów, zanotuj odcisk certyfikatu, który właśnie przesłałeś. Będzie on potrzebny do skonfigurowania interfejsu API do używania certyfikatu klienta na potrzeby uwierzytelniania bramy.

Konfigurowanie interfejsu API do używania certyfikatu klienta na potrzeby uwierzytelniania bramy

W portalu Azure przejdź do wystąpienia API Management.
W obszarze Interfejsy API wybierz pozycję Interfejsy API.
Wybierz interfejs API z listy.
Na karcie Projektowanie wybierz ikonę ołówka w sekcji Zaplecze .
W obszarze Poświadczenia bramy wybierz Certyfikat klienta, a następnie wybierz twój certyfikat z listy Certyfikat klienta.
Wybierz Zapisz.

Ostrzeżenie

Ta zmiana obowiązuje natychmiast. Wywołania operacji interfejsu API będą używać certyfikatu do uwierzytelniania na serwerze backendowym.

Wskazówka

Po określeniu certyfikatu do uwierzytelniania bramy dla usługi zaplecza API, staje się on częścią reguł dla tego API i może być wyświetlany w edytorze zasad.

Wyłączanie walidacji łańcucha certyfikatów dla certyfikatów z podpisem własnym

Jeśli używasz certyfikatów z podpisem własnym, musisz wyłączyć walidację łańcucha certyfikatów, aby umożliwić usłudze API Management komunikację z systemem zaplecza. W przeciwnym razie otrzymasz kod błędu 500. Aby wyłączyć tę walidację, możesz użyć polecenia cmdlet programu PowerShell New-AzApiManagementBackend (dla nowego zaplecza) lub Set-AzApiManagementBackend (dla istniejącego zaplecza) i ustawić parametr -SkipCertificateChainValidation na True:

$context = New-AzApiManagementContext -ResourceGroupName 'ContosoResourceGroup' -ServiceName 'ContosoAPIMService'
New-AzApiManagementBackend -Context  $context -Url 'https://contoso.com/myapi' -Protocol http -SkipCertificateChainValidation $true

Walidację łańcucha certyfikatów można również wyłączyć przy użyciu REST API Backend.

Usuwanie certyfikatu klienta

Aby usunąć certyfikat, wybierz pozycję Usuń w menu wielokropka (...):

Usuwanie certyfikatu