Konfigurowanie dostępu TLS do interfejsu API dla chmury prywatnej

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Host wirtualny w Edge określa domeny i porty, na których jest dostępny serwer proxy interfejsu API, a także URL, którego aplikacje używają, aby uzyskać dostęp do serwera proxy interfejsu API.

Host wirtualny określa też, czy dostęp do serwera proxy interfejsu API jest możliwy przez protokół HTTP czy zaszyfrowany protokół HTTPS z protokołem TLS. Podczas konfigurowania hosta wirtualnego do korzystania z HTTPS i TLS tworzysz hosta wirtualnego w Edge i konfigurujesz hosta wirtualnego tak, aby używał keystore i Truststore.

Więcej informacji:

• Informacje o TLS/SSL
• Używanie TLS w przeglądarce Edge
• Informacje o hostach wirtualnych
• Konfigurowanie hostów wirtualnych dla chmury Private Cloud
• Dokumentacja właściwości hosta wirtualnego
• Magazyny kluczy i magazyny zaufania

Co jest potrzebne do utworzenia hosta wirtualnego

Zanim utworzysz hosta wirtualnego, przygotuj te informacje:

• Dostępna publicznie nazwa domeny hosta wirtualnego. Sprawdź na przykład, czy publicznie dostępna nazwa to api.myCompany.com, myapi.myCompany.com itp. Te informacje są używane podczas tworzenia hosta wirtualnego oraz rekordu DNS dla hosta wirtualnego.
• W przypadku jednokierunkowego protokołu TLS musisz utworzyć magazyn kluczy, w którym znajduje się ten magazyn:
  • Certyfikat TLS – certyfikat podpisany przez urząd certyfikacji lub łańcuch certyfikatów, w którym ostatni certyfikat jest podpisany przez urząd certyfikacji.
  • Klucz prywatny – Edge obsługuje rozmiar kluczy do 2048 bitów. Hasło jest opcjonalne.
• W przypadku dwukierunkowego protokołu TLS musisz mieć magazyn kluczy oraz magazyn zaufania, w którym będzie przechowywać certyfikat klienta oraz (opcjonalnie) łańcuch urzędów certyfikacji. Magazyn zaufania jest potrzebny, nawet jeśli certyfikat został podpisany przez urząd certyfikacji.

Więcej informacji o tworzeniu magazynów kluczy i magazynów zaufania znajdziesz w artykule o magazynach kluczy i magazynach zaufania.

Konfiguracja hosta wirtualnego na potrzeby TLS

Aby utworzyć hosta wirtualnego, utwórz obiekt XML określający hosta wirtualnego. Poniższy obiekt XML używa elementu <SSLInfo> do definiowania hosta wirtualnego dla jednokierunkowej konfiguracji TLS przez HTTPS:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

W tym przykładzie element <Enabled> ma wartość true, aby włączyć jednokierunkowe szyfrowanie TLS, a elementy <KeyStore> i <KeyAlias> określają magazyn kluczy i klucz używane przez połączenie TLS.

Aby włączyć dwukierunkowe szyfrowanie TLS, ustaw element <ClientAuthEnabled> na true i określ magazyn zaufania za pomocą elementu <TrustStore>. Magazyn zaufania przechowuje certyfikat klienta i opcjonalnie łańcuch urzędów certyfikacji.

Określam, jak określić nazwę magazynu kluczy i magazynu zaufanych certyfikatów na hoście wirtualnym

W powyższym przykładzie z hostem wirtualnym do określenia magazynu kluczy określono za pomocą odwołania. Odwołanie to zmienna zawierająca nazwę magazynu kluczy, a nie podana bezpośrednio nazwa tego magazynu.

Zaletą korzystania z pliku referencyjnego jest to, że możesz zmienić jego wartość, aby zmienić magazyn kluczy używany przez hosta wirtualnego. Zwykle dlatego, że certyfikat w bieżącym magazynie kluczy wkrótce wygaśnie. Zmiana wartości odwołania nie wymaga ponownego uruchomienia routera brzegowego.

Możesz też użyć literału nazwy magazynu kluczy na hoście wirtualnym. Jeśli jednak zmienisz hosta wirtualnego, aby zmienić nazwę magazynu kluczy, konieczne będzie ponowne uruchomienie routerów brzegowych.

Ograniczenia korzystania z odwołań do magazynów kluczy i magazynu zaufania

Gdy używasz odwołań do magazynów kluczy i magazynów zaufania, musisz wziąć pod uwagę te ograniczenia:

• Odwołań do magazynu kluczy i magazynu zaufania możesz używać tylko na hostach wirtualnych, jeśli obsługujesz SNI i wyłączysz SSL na routerach Apigee.
• Jeśli masz system równoważenia obciążenia przed routerami Apigee i wyłączysz TLS w systemie równoważenia obciążenia, nie możesz używać odwołań do magazynu kluczy ani magazynu zaufanych certyfikatów na hostach wirtualnych.

Modyfikowanie istniejącego hosta wirtualnego tak, aby można było używać odwołań do magazynu kluczy i magazynu zaufanych

Apigee zdecydowanie zaleca, aby hosty wirtualne używały odniesień do magazynów kluczy i magazynów zaufania. Odniesienia pozwalają zmienić magazyn kluczy i magazyn zaufania używane przez hosta wirtualnego bez konieczności ponownego uruchamiania routerów brzegowych.

Jeśli hosty wirtualne są obecnie skonfigurowane tak, aby używać nazwy literału magazynu kluczy lub magazynu zaufanych, możesz je przekonwertować, aby używać odwołań. Aby to zrobić, zaktualizuj hosta wirtualnego, aby używał odwołań, a następnie ponownie uruchom routery brzegowe.

Konfigurowanie mechanizmów szyfrowania i protokołów TLS w Edge 4.15.07 i starszych

Jeśli używasz Edge w wersji 4.15.07 lub starszej, skonfiguruj protokół TLS i mechanizmy szyfrowania używane przez hosta wirtualnego za pomocą tagów podrzędnych <Ciphers> i <Protocols> tagu <SSLInfo>. Ich opis znajdziesz w tabeli poniżej.

Na przykład:

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

Tag <Cipher> używa nazwy szyfrowania w Javie i JSSE. Na przykład w przypadku Javy 8 zobacz http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites.

Określanie mechanizmów szyfrowania i protokołów TLS w przypadku Edge w wersji od 4.16.01 do 4.16.09

W wersjach Edge od 4.16.01 do 4.16.09 ustawiasz domyślne mechanizmy szyfrowania i protokoły dla hostów wirtualnych globalnie w routerze. Te ustawienia domyślne są następnie stosowane do wszystkich hostów wirtualnych.

Użyj tokenów, aby określić domyślne protokoły i mechanizmy szyfrowania:

• Aby określić protokoły domyślne, użyj tokena conf_load_balancing_load.balancing.driver.server.ssl.protocols
• Aby określić domyślne mechanizmy szyfrowania routera, użyj tokena conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Wartość domyślna tokena conf_load_balancing_load.balancing.driver.server.ssl.protocols to:

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

To ustawienie określa, że router obsługuje TLS 1.0, 1.1 i 1.2. Podaj listę wartości dla tokena rozdzielaną spacjami.

Wartość domyślna tokena conf_load_balancing_load.balancing.driver.server.ssl.ciphers to:

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

To ustawienie określa:

• Wymagana długość klucza co najmniej 128 bitów (HIGH).
• Wyklucz mechanizmy szyfrowania bez uwierzytelniania (!aNULL)
• Wyklucz zestawy szyfrów korzystające z MD5 (!MD5)
• Wyklucz zestawy szyfrów używające DH (w tym anonimowego DH, efemerycznego i stałego DH) ORAZ potrójnego DES (!DH+3DES)
• Wyklucz zestawy szyfrów korzystające z wymiany kluczy RSA i potrójnego algorytmu DES (!RSA+3DES)

Informacje na temat składni i wartości dozwolonych przez ten token znajdziesz w artykule na temat szyfrów OpenSSL. Pamiętaj, że ten token używa nazw szyfrów OpenSSL, takich jak AES128-SHA256, a nie nazw szyfrów Java/JSSE, takich jak TLS_RSA_WITH_AES_128_CBC_SHA256.

Aby ustawić token dla routera:

1. Edytuj plik /opt/apigee/customer/application/router.properties. Jeśli taki plik nie istnieje, utwórz go.
2. Ustaw token conf_load_balancing_load.balancing.driver.server.ssl.ciphers. Aby na przykład określić tylko protokół TLSv1.2 i wykluczyć zestawy szyfrów korzystające z kluczy PSK, dodaj !PSK:

   conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
   conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK

3. Upewnij się, że plik router.properties należy do apigee:

   chown apigee:apigee /opt/apigee/customer/application/router.properties

4. Ponownie uruchom router brzegowy:

   /opt/apigee/apigee-service/bin/apigee-service edge-router restart

5. Sprawdź wartość tokena:

   /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Ustawianie parametrów hosta wirtualnego TLS dla Edge w wersji 4.17.01 i nowszych

Jeśli używasz Edge w wersji 4.17.01 lub nowszej, możesz ustawić niektóre właściwości TLS dla pojedynczego hosta wirtualnego, takie jak protokół TLS i szyfr, przy użyciu tagu podrzędnego <Properties> tagu <VirtualHost>. Te tagi opisaliśmy w dokumentacji właściwości hosta wirtualnego.

Na przykład:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

Informacje o składni i wartościach dozwolonych przez token ssl_ciphers znajdziesz w artykule o szyfrach OpenSSL. Pamiętaj, że ten token używa nazw szyfrów OpenSSL, takich jak AES128-SHA256, a nie nazw szyfrów Java/JSSE, takich jak TLS_RSA_WITH_AES_128_CBC_SHA256.

Tworzenie hosta wirtualnego korzystającego z protokołu HTTPS

W tym przykładzie przy użyciu odwołania określamy magazyn kluczy dla hosta wirtualnego. Używanie referencji umożliwia zmianę magazynu kluczy bez konieczności ponownego uruchamiania routerów.

Aby utworzyć hosta wirtualnego, wykonaj te czynności:

1. Utwórz i skonfiguruj magazyn kluczy o nazwie myTestKeystore, wykonując czynności opisane tutaj: magazyny kluczy i magazyny zaufania. Sprawdź, czy magazyn kluczy używa aliasu myKeyAlias na potrzeby certyfikatu i klucza prywatnego.

2. Za pomocą tego wywołania interfejsu POST API utwórz odniesienie o nazwie keystoreref do utworzonego powyżej magazynu kluczy:

   curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
     -d '<ResourceReference name="keystoreref">
       <Refers>myTestKeystore</Refers>
       <ResourceType>KeyStore</ResourceType>
     </ResourceReference>'
     -u email:password
   

   Odwołanie określa nazwę magazynu kluczy i typ odwołania jako KeyStore.

   Aby wyświetlić dokumentację, użyj tego wywołania interfejsu GET API:

   curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
   

3. Utwórz hosta wirtualnego przy użyciu interfejsu API Create a Virtual Host (Utwórz wirtualny host), gdzie <ms-IP> to adres IP lub nazwa domeny węzła serwera zarządzania.

   Pamiętaj, aby określić prawidłowe odwołanie do magazynu kluczy i alias klucza:

   curl -X POST -H "Content-Type:application/xml" \
     http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
     -d '<VirtualHost  name="newTLSTrustStore2">
       <HostAliases>
         <HostAlias>apiTLS.myCompany.com</HostAlias>
       </HostAliases>
       <Interfaces/>
       <Port>9005</Port>
       <OCSPStapling>off</OCSPStapling>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://keystoreref</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u email:password

4. Utwórz rekord DNS dla hosta wirtualnego zgodnego z aliasem hosta.

5. Jeśli masz istniejące serwery proxy interfejsu API, dodaj hosta wirtualnego do elementu <HTTPConnection> w punkcie ProxyEndpoint. Host wirtualny jest automatycznie dodawany do wszystkich nowych serwerów proxy interfejsu API.

   Zapoznaj się z artykułem Aktualizowanie serwera proxy interfejsu API po utworzeniu hosta wirtualnego w artykule Informacje o hostach wirtualnych.

Po zaktualizowaniu serwera proxy interfejsu API w celu używania hosta wirtualnego i utworzeniu rekordu DNS dla aliasu hosta możesz uzyskać dostęp do serwera proxy interfejsu API w następujący sposób:

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

Na przykład:

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

Tworzenie i modyfikowanie odwołań do magazynu kluczy lub magazynu zaufania

Opcjonalnie możesz skonfigurować hosta wirtualnego tak, aby używał referencji do magazynu kluczy lub magazynu zaufanych. Zaletą korzystania z pliku referencyjnego jest to, że możesz zaktualizować odwołanie, aby wskazywały inny magazyn kluczy lub magazyn zaufania, aby zaktualizować certyfikat TLS bez konieczności ponownego uruchamiania routera.

Na przykład poniżej widać host wirtualny, który używa odwołania do magazynu kluczy:

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

Aby utworzyć referencję o nazwie keystoreref, użyj tego wywołania interfejsu POST API:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

Odwołanie określa nazwę magazynu kluczy i jego typ.

Aby wyświetlić dokumentację, użyj tego wywołania interfejsu GET API:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Aby później zmienić odwołanie, tak aby wskazywały inny magazyn kluczy, i upewnić się, że alias ma taką samą nazwę, użyj tego wywołania PUT:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password