Настройка доступа TLS к API для частного облака

Вы просматриваете документацию Apigee Edge .
Перейдите в документацию Apigee X.info

Виртуальный хост в Edge определяет домены и порты, через которые доступен API-прокси, и, соответственно, URL-адрес, который приложения используют для доступа к API-прокси.

Виртуальный хост также определяет, будет ли доступ к API-прокси осуществляться по протоколу HTTP или по зашифрованному протоколу HTTPS с использованием TLS. При настройке виртуального хоста для использования HTTPS и TLS вы создаете виртуальный хост в Edge и настраиваете для него хранилище ключей и хранилище доверенных сертификатов .

Узнать больше:

• О протоколе TLS/SSL
• Использование TLS с Edge
• О виртуальных хостах
• Настройка виртуальных хостов для частного облака
• Справочник свойств виртуального хоста
• Магазины ключей и магазины доверия

Что вам понадобится для создания виртуального хоста

Перед созданием виртуального хоста вам потребуется следующая информация:

• Общедоступное доменное имя виртуального хоста. Например, вам нужно знать, является ли общедоступное имя api.myCompany.com , myapi.myCompany.com и т. д. Эта информация используется при создании виртуального хоста, а также при создании DNS-записи для виртуального хоста.
• Для одностороннего TLS необходимо создать хранилище ключей, содержащее следующие данные:
  • TLS-сертификат — это либо сертификат, подписанный центром сертификации (ЦС), либо цепочка сертификатов, где последний сертификат подписан ЦС.
  • Закрытый ключ — Edge поддерживает ключи размером до 2048 бит. Кодовая фраза необязательна.
• Для двустороннего TLS-соединения вам потребуется хранилище ключей и хранилище доверенных сертификатов, в котором будет храниться сертификат клиента и, при необходимости, цепочка центров сертификации. Хранилище доверенных сертификатов необходимо, даже если сертификат подписан центром сертификации.

Дополнительную информацию о создании хранилищ ключей и доверенных сертификатов см. в разделах «Хранилища ключей» и «Хранилища доверенных сертификатов».

Конфигурация виртуального хоста для TLS

Для создания виртуального хоста необходимо создать XML-объект, определяющий этот виртуальный хост. В следующем XML-объекте используется элемент <SSLInfo> для определения виртуального хоста для односторонней конфигурации TLS по протоколу 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>

В этом примере элемент <Enabled> установлен в значение true, чтобы включить одностороннее TLS-соединение, а элементы <KeyStore> и KeyAlias> указывают хранилище ключей и ключ, используемые для TLS-соединения.

Для включения двусторонней TLS-аутентификации установите для элемента <ClientAuthEnabled> значение true и укажите хранилище доверенных сертификатов с помощью элемента <TrustStore> . Хранилище доверенных сертификатов содержит сертификат клиента и, при необходимости, цепочку центров сертификации сертификата.

Определение способа указания имени хранилища ключей и хранилища доверенных сертификатов в виртуальном хосте.

В приведенном выше примере с виртуальным хостом вы указали хранилище ключей, используя ссылку . Ссылка — это переменная, содержащая имя хранилища ключей, а не указывающая имя хранилища ключей напрямую.

Преимущество использования ссылки заключается в том, что вы можете изменить значение ссылки, чтобы изменить хранилище ключей, используемое виртуальным хостом, обычно потому, что срок действия сертификата в текущем хранилище ключей истекает в ближайшем будущем. Изменение значения ссылки не требует перезапуска пограничного маршрутизатора.

В качестве альтернативы можно использовать буквальное имя хранилища ключей в виртуальном хосте. Однако, если вы когда-либо измените имя хранилища ключей в виртуальном хосте, вам придется перезапустить пограничные маршрутизаторы.

Ограничения на использование ссылок на хранилища ключей и хранилища доверенных сертификатов.

При использовании ссылок на хранилища ключей и доверенных сертификатов необходимо учитывать следующее ограничение:

• Использовать ссылки на хранилища ключей и доверенных сертификатов в виртуальных хостах можно только при поддержке SNI и завершении SSL-соединения на маршрутизаторах Apigee.
• Если перед маршрутизаторами Apigee установлен балансировщик нагрузки, и вы завершаете TLS-соединение на балансировщике нагрузки, то вы не сможете использовать ссылки на хранилище ключей и хранилище доверенных сертификатов в виртуальных хостах.

Изменение существующего виртуального хоста для использования ссылок на хранилище ключей и хранилище доверенных сертификатов.

Компания Apigee настоятельно рекомендует виртуальным хостам использовать ссылки на хранилища ключей и доверенных сертификатов. Ссылки позволяют изменять хранилище ключей и доверенных сертификатов, используемые виртуальным хостом, без необходимости перезапуска пограничных маршрутизаторов.

Если ваши виртуальные хосты в настоящее время настроены на использование буквального имени хранилища ключей или хранилища доверенных сертификатов, вы можете преобразовать их для использования ссылок. Для этого обновите виртуальный хост, чтобы он использовал ссылки, а затем перезапустите пограничные маршрутизаторы.

Настройка алгоритмов шифрования и протоколов TLS для Edge 4.15.07 и более ранних версий.

Если вы используете Edge версии 4.15.07 и более ранних, то протокол TLS и используемые виртуальным хостом шифры задаются с помощью дочерних тегов <Ciphers> и <Protocols> тега <SSLInfo> . Эти теги описаны в таблице ниже.

Например:

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

В теге <Cipher> используется имя шифра в Java и JSSE. Например, для Java 8 см. http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites .

Указание алгоритмов шифрования и протоколов TLS для Edge версий 4.16.01–4.16.09

В версиях Edge 4.16.01–4.16.09 вы устанавливаете шифры и протоколы по умолчанию для виртуальных хостов глобально на маршрутизаторе. Эти значения по умолчанию затем применяются ко всем виртуальным хостам.

Используйте токены для указания протоколов и алгоритмов шифрования по умолчанию:

• Для указания протоколов по умолчанию используйте токен conf_load_balancing_load.balancing.driver.server.ssl.protocols .
• Чтобы указать алгоритмы шифрования по умолчанию для маршрутизатора, используйте токен conf_load_balancing_load.balancing.driver.server.ssl.ciphers

Значение по умолчанию для токена conf_load_balancing_load.balancing.driver.server.ssl.protocols :

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

Этот параметр указывает, что маршрутизатор поддерживает версии TLS 1.0, 1.1 и 1.2. Укажите список значений, разделенных пробелами, для токена.

Значение по умолчанию для токена conf_load_balancing_load.balancing.driver.server.ssl.ciphers следующее:

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

Этот параметр определяет:

• Требуется длина ключа 128 бит или более ( HIGH ).
• Исключить шифры без аутентификации ( !aNULL )
• Исключить наборы шифров, использующие MD5 ( !MD5 )
• Исключить наборы шифров, использующие DH (включая анонимный DH, эфемерный DH и фиксированный DH) И тройной DES ( !DH+3DES ).
• Исключить наборы шифров, использующие обмен ключами RSA И тройной DES ( !RSA+3DES )

Информацию о синтаксисе и допустимых значениях этого токена см. в разделе «Шифры OpenSSL» . Обратите внимание, что этот токен использует имена шифров OpenSSL, такие как AES128-SHA256, а не имена шифров Java/JSSE, такие как TLS_RSA_WITH_AES_128_CBC_SHA256.

Чтобы установить токен для маршрутизатора:

1. Отредактируйте файл /opt/apigee/customer/application/router.properties . Если этот файл не существует, создайте его.
2. Установите токен conf_load_balancing_load.balancing.driver.server.ssl.ciphers . Например, чтобы указать только TLSv1.2 и исключить наборы шифров, использующие предварительно согласованные ключи, добавьте !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. Убедитесь, что файл router.properties принадлежит пользователю apigee:

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

4. Перезагрузите маршрутизатор Edge:

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

5. Проверьте значение токена:

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

Настройка параметров виртуального хоста TLS для Edge версии 4.17.01 и более поздних версий.

Если вы используете Edge версии 4.17.01 и выше, вы можете задать некоторые свойства TLS для отдельного виртуального хоста, такие как протокол TLS и шифр, используя дочерний тег <Properties> тега <VirtualHost> . Описание этих тегов приведено в справочнике свойств виртуального хоста .

Например:

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

Информацию о синтаксисе и значениях, разрешенных токеном ssl_ciphers , см. в разделе «Шифры OpenSSL» . Обратите внимание, что этот токен использует имена шифров OpenSSL, такие как AES128-SHA256, а не имена шифров Java/JSSE, такие как TLS_RSA_WITH_AES_128_CBC_SHA256.

Создание виртуального хоста, использующего HTTPS.

В этом примере хранилище ключей указывается для виртуального хоста с помощью ссылки. Использование ссылки позволяет изменять хранилище ключей без необходимости перезапуска маршрутизатора.

Для создания виртуального хоста выполните следующие действия:

1. Создайте и настройте хранилище ключей с именем myTestKeystore , используя процедуру, описанную здесь: Хранилища ключей и хранилища доверенных сертификатов . Убедитесь, что хранилище ключей использует псевдоним myKeyAlias ​​для сертификата и закрытого ключа.

2. Используйте следующий POST-запрос API для создания ссылки с именем keystoreref на созданное вами выше хранилище ключей:

   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
   

   В ссылке указывается имя хранилища ключей и тип ссылки как KeyStore .

   Для просмотра справочной информации воспользуйтесь следующим вызовом API GET:

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

3. Создайте виртуальный хост, используя API создания виртуального хоста , где <ms-IP> — это IP-адрес или доменное имя узла сервера управления.

   Обязательно укажите правильную ссылку на хранилище ключей и псевдоним ключа:

   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. Создайте DNS-запись для виртуального хоста, соответствующую псевдониму хоста.

5. Если у вас уже есть API-прокси, добавьте виртуальный хост в элемент <HTTPConnection> в ProxyEndpoint. Виртуальный хост будет автоматически добавлен ко всем новым API-прокси.

   См. раздел «Обновление API-прокси после создания виртуального хоста» в разделе «О виртуальных хостах» .

После обновления API-прокси для использования виртуального хоста и создания DNS-записи для псевдонима хоста, вы можете получить доступ к API-прокси, как показано ниже:

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

Например:

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

Создание и изменение ссылок на хранилище ключей или хранилище доверенных сертификатов.

При желании вы можете настроить виртуальный хост на использование ссылки на хранилище ключей или доверенных сертификатов. Преимущество использования ссылки заключается в том, что вы можете обновить ссылку, указав на другое хранилище ключей или доверенных сертификатов, чтобы обновить TLS-сертификат без необходимости перезапуска маршрутизатора.

Например, ниже показан виртуальный хост, использующий ссылку на хранилище ключей:

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

Для создания ссылки с именем keystoreref используйте следующий 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

В ссылке указывается имя хранилища ключей и его тип.

Для просмотра справочной информации воспользуйтесь следующим вызовом API GET:

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

Чтобы впоследствии изменить ссылку и указать на другое хранилище ключей, убедившись, что псевдоним имеет то же имя, используйте следующий вызов 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