Как настроить доступ к API по протоколу TLS для частного облака

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

Виртуальный хост в 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>. В хранилище доверенных сертификатов содержится сертификат клиента и, при необходимости, цепочка сертификатов ЦС.

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

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

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

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

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

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

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

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

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

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

Настройка шифров и протоколов 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 и алгоритм Triple 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. Чтобы создать ссылку 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
   

   В ссылке указывается название хранилища ключей и тип ссылки 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 Create a Virtual Host (Создать виртуальный хост), где <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, используйте следующий вызов API POST:

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