Konfigurowanie niestandardowej nazwy domeny dla wystąpienia usługi Azure API Management

DOTYCZY: Wszystkie warstwy usługi API Management

Podczas tworzenia wystąpienia usługi Azure API Management w chmurze platformy Azure platforma Azure przypisuje jej poddomenę azure-api.net (na przykład apim-service-name.azure-api.net). Punkty końcowe usługi API Management można również uwidocznić przy użyciu własnej niestandardowej nazwy domeny, takiej jak contoso.com. W tym artykule pokazano, jak zamapować istniejącą niestandardową nazwę DNS na punkty końcowe uwidocznione przez wystąpienie usługi API Management.

Ważne

Usługa API Management akceptuje tylko żądania z zgodnymi wartościami nagłówka hosta:

• Domyślna nazwa domeny bramy
• Dowolna ze skonfigurowanych niestandardowych nazw domen bramy

Wymagania wstępne

• Wystąpienie usługi API Management. Aby uzyskać więcej informacji, zobacz Tworzenie wystąpienia usługi Azure API Management.

• Niestandardowa nazwa domeny, która jest własnością Ciebie lub Twojej organizacji. Ten artykuł nie zawiera instrukcji dotyczących uzyskiwania niestandardowej nazwy domeny.

• Opcjonalnie prawidłowy certyfikat z kluczem publicznym i prywatnym (. PFX). Alternatywna nazwa podmiotu lub podmiotu (SAN) musi być zgodna z nazwą domeny (umożliwia to wystąpieniu usługi API Management bezpieczne uwidacznienie adresów URL za pośrednictwem protokołu TLS).

  Zobacz Opcje certyfikatu domeny.

• Rekordy DNS hostowane na serwerze DNS, aby zamapować niestandardową nazwę domeny na domyślną nazwę domeny wystąpienia usługi API Management. Ten temat nie zawiera instrukcji dotyczących hostowania rekordów DNS.

  Aby uzyskać więcej informacji na temat wymaganych rekordów, zobacz Konfiguracja DNS w dalszej części tego artykułu.

Punkty końcowe dla domen niestandardowych

Istnieje kilka punktów końcowych usługi API Management, do których można przypisać niestandardową nazwę domeny. Obecnie dostępne są następujące punkty końcowe:

Punkt końcowy	Wartość domyślna
Brama	Wartość domyślna to: <apim-service-name>.azure-api.net. Brama jest jedynym punktem końcowym dostępnym do skonfigurowania w warstwie Zużycie. Domyślna konfiguracja punktu końcowego bramy pozostaje dostępna po dodaniu niestandardowej domeny bramy.
Portal dla deweloperów	Wartość domyślna to: <apim-service-name>.developer.azure-api.net
Zarządzanie	Wartość domyślna to: <apim-service-name>.management.azure-api.net
Interfejs API konfiguracji (wersja 2)	Wartość domyślna to: <apim-service-name>.configuration.azure-api.net
SCM	Wartość domyślna to: <apim-service-name>.scm.azure-api.net

Kwestie wymagające rozważenia

• Możesz zaktualizować dowolny z punktów końcowych obsługiwanych w warstwie usługi. Zazwyczaj klienci aktualizują bramę (ten adres URL jest używany do wywoływania interfejsów API uwidocznionych za pośrednictwem usługi API Management) oraz portal deweloperów (adres URL portalu deweloperów).
• Domyślny punkt końcowy bramy pozostaje dostępny po skonfigurowaniu niestandardowej nazwy domeny bramy i nie można go usunąć. W przypadku innych punktów końcowych usługi API Management (takich jak portal dla deweloperów) skonfigurowanych przy użyciu niestandardowej nazwy domeny domyślny punkt końcowy nie jest już dostępny.
• Tylko właściciele wystąpienia usługi API Management mogą używać punktów końcowych Zarządzanie i SCM wewnętrznie. Do tych punktów końcowych rzadziej jest przypisywana niestandardowa nazwa domeny.
• Warstwy Premium i Deweloper obsługują konfigurowanie wielu nazw hostów dla punktu końcowego Brama.
• Nazwy domen z symbolami wieloznacznymi, takie jak *.contoso.com, są obsługiwane we wszystkich warstwach z wyjątkiem warstwy Zużycie. Określony certyfikat poddomeny (na przykład api.contoso.com) ma pierwszeństwo przed certyfikatem wieloznacznymi (*.contoso.com) dla żądań api.contoso.com.

Opcje certyfikatu domeny

Usługa API Management obsługuje niestandardowe certyfikaty protokołu TLS lub certyfikaty zaimportowane z usługi Azure Key Vault. Możesz również włączyć bezpłatny certyfikat zarządzany.

Ostrzeżenie

Jeśli potrzebujesz przypinania certyfikatu, użyj niestandardowej nazwy domeny i niestandardowego lub certyfikatu usługi Key Vault, a nie domyślnego certyfikatu lub bezpłatnego certyfikatu zarządzanego. Nie zalecamy wdrażania silnej zależności od certyfikatu, którym nie zarządzasz.

Okres niestandardowy

Jeśli masz już certyfikat prywatny od dostawcy innej firmy, możesz przekazać go do wystąpienia usługi API Management. Musi spełniać następujące wymagania. (Jeśli włączysz bezpłatny certyfikat zarządzany przez usługę API Management, spełnia już te wymagania).

• Wyeksportowany jako plik PFX, zaszyfrowany przy użyciu potrójnego DES i opcjonalnie chroniony hasłem.
• Zawiera klucz prywatny o długości co najmniej 2048 bitów
• Zawiera wszystkie certyfikaty pośrednie i certyfikat główny w łańcuchu certyfikatów.

Magazyn kluczy

Zalecamy używanie usługi Azure Key Vault do zarządzania certyfikatami i ustawiania ich na .autorenew

Jeśli używasz usługi Azure Key Vault do zarządzania certyfikatem TLS domeny niestandardowej, upewnij się, że certyfikat został wstawiony do usługi Key Vault jako certyfikat, a nie wpis tajny.

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 pobrać certyfikat TLS/SSL, usługa API Management musi mieć listę i uzyskać uprawnienia do wpisów tajnych w usłudze Azure Key Vault zawierającej certyfikat.

• W przypadku importowania certyfikatu przy użyciu witryny Azure Portal wszystkie niezbędne kroki konfiguracji są wykonywane automatycznie.

• Jeśli używasz narzędzi wiersza polecenia lub interfejsu API zarządzania, te uprawnienia muszą zostać przyznane ręcznie, w dwóch krokach:

  1. Na stronie Tożsamości zarządzane wystąpienia usługi API Management włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika. Zanotuj identyfikator podmiotu zabezpieczeń na tej stronie.
  2. Przypisz uprawnienia do tożsamości zarządzanej, aby uzyskać dostęp do magazynu kluczy. Wykonaj kroki opisane w poniższej sekcji.

  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.

Jeśli certyfikat jest ustawiony na autorenew wartość , a warstwa usługi API Management ma umowę SLA (czyli we wszystkich warstwach z wyjątkiem warstwy dewelopera), usługa API Management automatycznie pobierze najnowszą wersję bez przestoju w usłudze.

Aby uzyskać więcej informacji, zobacz Używanie tożsamości zarządzanych w usłudze Azure API Management.

Zarządzany

Usługa API Management oferuje bezpłatny, zarządzany certyfikat TLS dla twojej domeny, jeśli nie chcesz kupować własnego certyfikatu i zarządzać nim. Certyfikat jest odnawiany automatycznie.

Uwaga

Bezpłatny zarządzany certyfikat TLS jest w wersji zapoznawczej. Obecnie jest niedostępna w warstwach usług w wersji 2.

Ograniczenia

• Obecnie można używać tylko z punktem końcowym bramy usługi API Management
• Nieobsługiwane w przypadku bramy hostowanej samodzielnie
• Nieobsługiwane w następujących regionach świadczenia usługi Azure: Francja Południowa i Republika Południowej Afryki Zachodnia
• Obecnie dostępne tylko w chmurze platformy Azure
• Nie obsługuje nazw domen głównych (na przykład contoso.com). Wymaga w pełni kwalifikowanej nazwy, takiej jak api.contoso.com.
• Obsługuje tylko nazwy domen publicznych
• Można skonfigurować tylko podczas aktualizowania istniejącego wystąpienia usługi API Management, a nie podczas tworzenia wystąpienia

Ustawianie niestandardowej nazwy domeny — portal

Wybierz kroki zgodnie z certyfikatem domeny, którego chcesz użyć.

Okres niestandardowy

1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
2. W obszarze nawigacji po lewej stronie wybierz pozycję Domeny niestandardowe.
3. Wybierz pozycję +Dodaj lub wybierz istniejący punkt końcowy , który chcesz zaktualizować.
4. W oknie po prawej stronie wybierz typ punktu końcowego dla domeny niestandardowej.
5. W polu Nazwa hosta określ nazwę, której chcesz użyć. Na przykład api.contoso.com.
6. W obszarze Certyfikat wybierz pozycję Niestandardowe
7. Wybierz pozycję Plik certyfikatu, aby wybrać i przekazać certyfikat.
8. Przekaż prawidłowy element . Plik PFX i podaj hasło, jeśli certyfikat jest chroniony hasłem.
9. Podczas konfigurowania punktu końcowego bramy wybierz lub usuń zaznaczenie innych opcji w razie potrzeby, w tym negocjowanego certyfikatu klienta lub domyślnego powiązania SSL.
10. Wybierz pozycję Dodaj lub wybierz pozycję Aktualizuj dla istniejącego punktu końcowego.
11. Wybierz pozycję Zapisz.

Magazyn kluczy

1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
2. W obszarze nawigacji po lewej stronie wybierz pozycję Domeny niestandardowe.
3. Wybierz pozycję +Dodaj lub wybierz istniejący punkt końcowy , który chcesz zaktualizować.
4. W oknie po prawej stronie wybierz typ punktu końcowego dla domeny niestandardowej.
5. W polu Nazwa hosta określ nazwę, której chcesz użyć. Na przykład api.contoso.com.
6. W obszarze Certyfikat wybierz pozycję Key Vault, a następnie wybierz pozycję Wybierz.
   1. Wybierz pozycję Subskrypcja z listy rozwijanej.
   2. Wybierz magazyn kluczy z listy rozwijanej.
   3. Po załadowaniu certyfikatów wybierz pozycję Certyfikat z listy rozwijanej. Kliknij opcję Wybierz.
   4. W obszarze Tożsamość klienta wybierz tożsamość przypisaną przez system lub tożsamość zarządzaną przypisaną przez użytkownika włączoną w wystąpieniu, aby uzyskać dostęp do magazynu kluczy.
7. Podczas konfigurowania punktu końcowego bramy wybierz lub usuń zaznaczenie innych opcji w razie potrzeby, w tym negocjowanego certyfikatu klienta lub domyślnego powiązania SSL.
8. Wybierz pozycję Dodaj lub wybierz pozycję Aktualizuj dla istniejącego punktu końcowego.
9. Wybierz pozycję Zapisz.

Zarządzany

1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
2. W obszarze nawigacji po lewej stronie wybierz pozycję Domeny niestandardowe.
3. Wybierz pozycję +Dodaj lub wybierz istniejący punkt końcowy , który chcesz zaktualizować.
4. W oknie po prawej stronie wybierz typ punktu końcowego dla domeny niestandardowej.
5. W polu Nazwa hosta określ nazwę, której chcesz użyć. Na przykład api.contoso.com.
6. W obszarze Certyfikat wybierz pozycję Zarządzane , aby włączyć bezpłatny certyfikat zarządzany przez usługę API Management. Certyfikat zarządzany jest dostępny tylko w wersji zapoznawczej dla punktu końcowego bramy.
7. Skopiuj następujące wartości i użyj ich do skonfigurowania systemu DNS:
   • Rekordy TXT
   • Rekord CNAME
8. Podczas konfigurowania punktu końcowego bramy wybierz lub usuń zaznaczenie innych opcji w razie potrzeby, w tym negocjowanego certyfikatu klienta lub domyślnego powiązania SSL.
9. Wybierz pozycję Dodaj lub wybierz pozycję Aktualizuj dla istniejącego punktu końcowego.
10. Wybierz pozycję Zapisz.

Uwaga

Proces przypisywania certyfikatu może potrwać 15 minut lub więcej w zależności od rozmiaru wdrożenia. Warstwa dewelopera ma przestój, natomiast warstwy Podstawowa i wyższa nie.

Konfiguracja DNS

• Skonfiguruj rekord CNAME dla domeny niestandardowej.
• W przypadku korzystania z bezpłatnego certyfikatu zarządzanego usługi API Management skonfiguruj również rekord TXT w celu ustanowienia własności domeny.

Uwaga

Bezpłatny certyfikat jest wystawiany przez firmę DigiCert. W przypadku niektórych domen należy jawnie zezwolić firmie DigiCert na wystawcę certyfikatów, tworząc rekord domeny CAA z wartością : 0 issue digicert.com.

Rekord CNAME

Skonfiguruj rekord CNAME wskazujący nazwę domeny niestandardowej (na przykład api.contoso.com) na nazwę hosta usługi API Management (na przykład <apim-service-name>.azure-api.net). Rekord CNAME jest bardziej stabilny niż rekord A w przypadku zmiany adresu IP. Aby uzyskać więcej informacji, zobacz adresy IP usługi Azure API Management i często zadawane pytania dotyczące usługi API Management.

Uwaga

Niektórzy rejestratorzy domen umożliwiają mapowanie domen podrzędnych tylko w przypadku używania rekordu CNAME, takiego jak , i nie nazw głównych, takich jak www.contoso.comcontoso.com. Aby uzyskać więcej informacji na temat rekordów CNAME, zobacz dokumentację dostarczoną przez rejestratora lub nazwy domen IETF — implementacja i specyfikacja.

Uwaga

W przypadku korzystania z bezpłatnego certyfikatu zarządzanego i konfigurowania rekordu CNAME u dostawcy DNS upewnij się, że jest rozpoznawany jako domyślna nazwa hosta usługi API Management (<apim-service-name>.azure-api.net). Obecnie usługa API Management nie odnawia automatycznie certyfikatu, jeśli rekord CNAME nie jest rozpoznawany jako domyślna nazwa hosta usługi API Management. Jeśli na przykład używasz bezpłatnego, zarządzanego certyfikatu i używasz usługi Cloudflare jako dostawcy DNS, upewnij się, że serwer proxy DNS nie jest włączony w rekordzie CNAME.

Rekordy TXT

Po włączeniu bezpłatnego zarządzanego certyfikatu usługi API Management skonfiguruj również rekord TXT w strefie DNS, aby ustanowić własność nazwy domeny.

• Nazwa rekordu to niestandardowa nazwa domeny poprzedzona prefiksem apimuid. Przykład: apimuid.api.contoso.com.
• Wartość jest identyfikatorem własności domeny dostarczonym przez wystąpienie usługi API Management.

Gdy używasz portalu do konfigurowania bezpłatnego certyfikatu zarządzanego dla domeny niestandardowej, nazwa i wartość niezbędnego rekordu TXT są wyświetlane automatycznie.

Identyfikator własności domeny można również uzyskać, wywołując interfejs API REST Uzyskiwanie własności domeny.

Jak serwer proxy usługi API Management reaguje przy użyciu certyfikatów SSL w uzgadnianiu protokołu TLS

Podczas konfigurowania domeny niestandardowej dla punktu końcowego bramy można ustawić dodatkowe właściwości określające sposób reagowania usługi API Management przy użyciu certyfikatu serwera w zależności od żądania klienta.

Klienci wywołujący z nagłówkiem SNI (Server Name Indication)

Jeśli masz jedną lub wiele domen niestandardowych skonfigurowanych dla punktu końcowego bramy, usługa API Management może odpowiadać na żądania HTTPS:

• Domena niestandardowa (na przykład contoso.com)
• Domena domyślna (na przykład apim-service-name.azure-api.net).

Na podstawie informacji w nagłówku SNI usługa API Management odpowiada za pomocą odpowiedniego certyfikatu serwera.

Klienci wywołujący bez nagłówka SNI

Jeśli używasz klienta, który nie wysyła nagłówka SNI , usługa API Management tworzy odpowiedzi na podstawie następującej logiki:

• Jeśli usługa ma tylko jedną domenę niestandardową skonfigurowaną dla bramy, domyślnym certyfikatem jest certyfikat wystawiony dla domeny niestandardowej bramy.

• Jeśli usługa skonfigurowała wiele domen niestandardowych dla bramy (obsługiwanej w warstwie Deweloper i Premium ), możesz wyznaczyć certyfikat domyślny, ustawiając właściwość defaultSslBinding na true ("defaultSslBinding":"true"). W portalu zaznacz pole wyboru Domyślne powiązanie SSL.

  Jeśli właściwość nie zostanie ustawiona, domyślnym certyfikatem jest certyfikat wystawiony dla domyślnej domeny bramy hostowanej pod adresem *.azure-api.net.

Obsługa żądania PUT/POST z dużym ładunkiem

Serwer proxy usługi API Management obsługuje żądania z dużymi ładunkami (>40 KB) w przypadku używania certyfikatów po stronie klienta w protokole HTTPS. Aby zapobiec zamrożeniu żądania serwera, możesz ustawić właściwość negotiateClientCertificate na true ("negotiateClientCertificate": "true") na nazwę hosta bramy. W portalu zaznacz pole wyboru Negocjuj certyfikat klienta.

Jeśli właściwość ma wartość true, certyfikat klienta jest wymagany w czasie połączenia SSL/TLS przed wymianą żądań HTTP. Ponieważ ustawienie ma zastosowanie na poziomie nazwy hosta bramy, wszystkie żądania połączenia żądają certyfikatu klienta. Możesz obejść to ograniczenie i skonfigurować maksymalnie 20 domen niestandardowych dla bramy (tylko obsługiwane w warstwie Premium ).

Następne kroki

Uaktualnianie i skalowanie usługi