Поделиться через

Настройте пользовательское доменное имя для экземпляра службы управления API Azure

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни управления API

Когда вы создаете экземпляр службы "Управления API" в облаке Azure, Azure назначает ему поддомен azure-api.net (например, apim-service-name.azure-api.net). Вы также можете предоставить доступ к своим конечным точкам управления API, используя собственное доменное имя, например contoso.com. В этой статье показано, как сопоставить существующее пользовательское имя DNS с конечными точками, предоставляемыми экземпляром Управления API.

Important

Управление API принимает только запросы со значениями заголовка узла , соответствующими:

  • доменное имя шлюза по умолчанию;
  • любое настроенное пользовательское доменное имя шлюза.

Note

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

Important

Изменения инфраструктуры службы управления API (например, настройка пользовательских доменов, добавление сертификатов ЦС, масштабирование, конфигурация виртуальной сети, изменения зоны доступности и дополнения регионов) могут занять 15 минут или больше времени, в зависимости от уровня служб и размера развертывания. Ожидается больше времени для экземпляра с большим числом единиц масштабирования или конфигурацией с несколькими регионами. Изменения в управлении API внедряются постепенно и тщательно для сохранения производительности и доступности.

В то время как служба обновляется, другие изменения инфраструктуры служб не могут быть сделаны. Однако вы можете настроить API, продукты, политики и параметры пользователя. Служба не столкнется с простоем шлюза, а управление API будет продолжать обрабатывать запросы API без прерываний (за исключением уровня разработчика).

Prerequisites

  • Экземпляр управления API. Дополнительные сведения см. в разделе Создание экземпляра службы управления API Azure.

  • Пользовательское доменное имя, принадлежащее вам или вашей организации. В этой статье не приводятся инструкции по приобретению пользовательского доменного имени.

  • Действительный сертификат с открытым и закрытым ключом (PFX) (необязательно). Субъект или альтернативное имя субъекта (SAN) должны совпадать с доменным именем (это позволяет экземпляру Управления API безопасно предоставлять URL-адреса через TLS).

    См. параметры сертификата домена.

  • DNS-записи, размещенные на DNS-сервере, которые сопоставляют пользовательское доменное имя с доменным именем по умолчанию для вашего экземпляра Управления API. В этом разделе не приводятся инструкции по размещению DNS-записей.

    Дополнительные сведения о необходимых записях см. в разделе "Конфигурация DNS" далее в этой статье.

Конечные точки для личных доменов

Есть ряд конечных точек Управления API, которым вы можете назначить пользовательское доменное имя. Сейчас доступны следующие конечные точки:

Endpoint Default
Gateway По умолчанию: <apim-service-name>.azure-api.net. Шлюз — единственная конечная точка, доступная для настройки на уровне потребления.

Конфигурация конечной точки шлюза по умолчанию остается доступной после добавления домена пользовательского шлюза.
Портал разработчика (все уровни, кроме потребления) По умолчанию: <apim-service-name>.developer.azure-api.net
Управление (только классические уровни) По умолчанию: <apim-service-name>.management.azure-api.net
API конфигурации локального шлюза (версия 2) По умолчанию: <apim-service-name>.configuration.azure-api.net
SCM (только классические уровни) По умолчанию: <apim-service-name>.scm.azure-api.net

Considerations

  • Вы можете обновить любую конечную точку, поддерживаемую на уровне служб. Как правило, клиенты обновляют шлюз (этот URL-адрес используется для вызова API, предоставляемых через управление API) и портала разработчика (URL-адрес портала разработчика ).
  • Конечная точка шлюза по умолчанию остается доступной после настройки пользовательского доменного имени шлюза и не может быть удалена. Для других конечных точек управления API (например , портала разработчика), настроенных с помощью имени личного домена, конечная точка по умолчанию больше недоступна.
  • Только владельцы экземпляров управления API могут использовать конечные точки Management и SCM для внутреннего доступа. Этим конечным точкам реже назначается пользовательское доменное имя.
  • Уровни "Премиум " и "Разработчик " поддерживают настройку нескольких имен узлов для конечной точки шлюза .
  • Доменные имена с подстановочными знаками, такие как *.contoso.com, поддерживаются на всех уровнях, кроме уровня потребления. Определенный поддомен сертификат (например, api.contoso.com) будет иметь приоритет над подстановочным сертификатом (*.contoso.com) для запросов к api.contoso.com.
  • При настройке пользовательского домена для портала разработчика можно включить CORS для нового доменного имени. Это необходимо для посетителей портала разработчика использовать интерактивную консоль на справочных страницах API.

Варианты сертификатов домена

Управление API поддерживает пользовательские сертификаты TLS и сертификаты, импортированные из Azure Key Vault. Вы также можете активировать бесплатный управляемый сертификат.

Warning

Если вы хотите закрепить сертификат, следует использовать пользовательское доменное имя и пользовательский сертификат или сертификат Key Vault, а не сертификат по умолчанию или бесплатный управляемый сертификат. Мы не рекомендуем настраивать жесткую зависимость от сертификата, которым вы не управляете.

Если у вас уже есть закрытый сертификат от стороннего поставщика, вы можете его отправить в экземпляр Управления API. Он должен соответствовать следующим требованиям (бесплатный сертификат, управляемый службой "Управление API", уже им соответствует этим требованиям):

  • экспортирован как PFX-файл, зашифрованный с помощью TRIPLE DES и при необходимости защищенный паролем;
  • Содержит закрытый ключ длиной не менее 2048 битов
  • должен содержать все промежуточные сертификаты и корневой сертификат в цепочке сертификатов.

Настройка пользовательского доменного имени на портале

Выберите шаги в соответствии с сертификатом домена , который вы хотите использовать.

  1. Перейдите к экземпляру службы "Управление API" на портале Azure.
  2. В области навигации слева выберите "Личные домены".
  3. Нажмите кнопку +Добавить или выберите существующую конечную точку , которую требуется обновить.
  4. В окне справа выберите тип конечной точки для личного домена.
  5. В поле "Имя узла " укажите имя, которое вы хотите использовать. Например, api.contoso.com.
  6. В разделе "Сертификат" выберите "Настраиваемый"
  7. Выберите файл сертификата , чтобы выбрать и отправить сертификат.
  8. Загрузите допустимый файл .PFX и укажите его пароль, если сертификат защищен паролем.
  9. При настройке конечной точки шлюза выберите или отключите другие параметры при необходимости, включая согласование сертификата клиента или привязку SSL по умолчанию. Настройка домена шлюза с пользовательским сертификатом
  10. Выберите "Добавить" или выберите "Обновить " для существующей конечной точки.
  11. Select Save.

DNS configuration

  • Настройте запись CNAME для личного домена.
  • При использовании бесплатного управляемого сертификата Управления API также настройте запись типа TXT, чтобы установить владение доменом.

Note

бесплатный сертификат выдается DigiCert. Для некоторых доменов необходимо явно разрешить DigiCert в качестве издателя сертификата, создав запись домена CAA со значением: 0 issue digicert.com

CNAME record

Настройте запись CNAME, которая связывает имя личного домена (например, api.contoso.com) с именем узла службы "Управление API" (например, <apim-service-name>.azure-api.net). Запись CNAME обеспечивает более стабильную работу, чем запись A, в случае изменения IP-адреса. Дополнительные сведения см. в разделах IP-адреса службы "Управление API Azure" и Часто задаваемые вопросы об управлении API.

Note

Некоторые регистраторы доменов позволяют отображать поддомены только при использовании записи CNAME, например www.contoso.com, а не корневых имен, таких как contoso.com. Дополнительные сведения о записях CNAME см. в документации, предоставленной вашим регистратором, или в документе IETF — доменные имена: реализация и спецификация.

Caution

При использовании бесплатного управляемого сертификата и настройки записи CNAME с поставщиком DNS убедитесь, что он разрешается в имя узла<apim-service-name>.azure-api.net службы по умолчанию Управление API (). В настоящее время Управление API не обновляет сертификат автоматически, если запись CNAME не разрешает имя узла по умолчанию Управление API. Например, если вы используете бесплатный управляемый сертификат и используете Cloudflare в качестве поставщика DNS, убедитесь, что DNS-прокси не включен в записи CNAME.

TXT record

При включении бесплатного управляемого сертификата для Управления API также настройте запись типа TXT в свой зоне DNS, чтобы установить владение доменным именем.

  • Имя записи — это имя личного домена с префиксом apimuid. Пример: apimuid.api.contoso.com.
  • Значение — это идентификатор владения доменом, предоставленный экземпляром Управления API.

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

Вы также можете получить идентификатор владения доменом, вызвав REST API Get Domain Ownership Identifier.

Как прокси-сервер управления API отвечает с использованием SSL-сертификатов в подтверждении TLS

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

Клиенты, выполняющие вызов с заголовком SNI (Server Name Indication, указание имени сервера)

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

  • Личный домен (например, contoso.com)
  • Домен по умолчанию (например, apim-service-name.azure-api.net).

В зависимости от информации в заголовке SNI, служба управления API отвечает соответствующим сертификатом сервера.

Клиенты, осуществляющие вызов без заголовка SNI

Если вы используете клиент, который не отправляет заголовок SNI , управление API создает ответы на основе следующей логики:

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

  • Если служба настроила несколько пользовательских доменов для шлюза (поддерживается на уровне "Разработчик " и "Премиум "), можно назначить сертификат по умолчанию, установив для свойства defaultSslBinding значение true ("defaultSslBinding":"true"). На портале установите флажок привязки SSL по умолчанию .

    Если вы не задали свойство, сертификатом по умолчанию является сертификат, выданный домену шлюза по умолчанию по адресу *.azure-api.net.

Поддержка запросов PUT/POST с большим объемом полезных данных

Прокси-сервер управления API поддерживает запросы с большим объемом (>40 КБ) полезных данных при использовании клиентских сертификатов в HTTPS. Чтобы предотвратить замораживание запроса сервера, можно задать для свойства negotiateClientCertificate значение true ("negotiateClientCertificate": "true") в имени узла шлюза. На портале установите флажок "Согласование сертификата клиента ".

Если свойство имеет значение true, сертификат клиента запрашивается во время подключения SSL/TLS перед обменом HTTP-запросами. Так как параметр применяется на уровне имени узла шлюза , все запросы на подключение запрашивают сертификат клиента. Это ограничение можно обойти и настроить до 20 пользовательских доменов для шлюза (только для уровня "Премиум ").

Ограничение для имени личного домена на уровне "Стандартный" версии 2

В настоящее время на уровне Standard v2, Управление API требует общедоступное разрешаемое DNS-имя, чтобы разрешить трафик в конечную точку шлюза. Если вы настраиваете имя личного домена для конечной точки шлюза, это имя должно быть общедоступным, не ограничено частной зоной DNS.

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

Устранение неполадок. Сбой смены сертификата имени узла из Azure Key Vault

Из-за изменения конфигурации или проблемы с подключением ваш экземпляр службы "Управление API" может не иметь возможности получить сертификат хоста из Azure Key Vault после обновления или смены сертификата. В этом случае экземпляр службы управления API продолжает использовать кэшированный сертификат, пока он не получит обновленный сертификат. Если срок действия кэшированного сертификата истекает, рабочий трафик в шлюз будет заблокирован. Любая вышестоящая служба, например Шлюз приложений, использующая конфигурацию сертификата имени узла, также может блокировать трафик среды выполнения к шлюзу при использовании кэшированного сертификата с истекшим сроком действия.

Чтобы устранить эту проблему, убедитесь, что хранилище ключей существует, и сертификат хранится в хранилище ключей. Если экземпляр службы управления API развернут в виртуальной сети, подтвердите исходящее подключение к тегу службы AzureKeyVault. Проверьте, существует ли управляемое удостоверение, используемое для доступа к хранилищу ключей. Подтвердите разрешения для управляемого удостоверения на доступ к хранилищу ключей. Подробные инструкции по настройке личного домена см. в разделе "Настройка личного домена— Key Vault" ранее в этой статье. После восстановления конфигурации сертификат имени узла будет обновляться в службе управления API в течение 4 часов.

Related content

Обновление и масштабирование службы