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

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

Важно!

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

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

Предварительные требования

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

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

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

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

    См. раздел Варианты сертификатов домена.

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

    Дополнительные сведения о требуемых записях см. в разделе Настройка DNS далее в этой статье.

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

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

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

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

Рекомендации

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

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

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

Предупреждение

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

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

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

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

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

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

Примечание

Назначение сертификата может занять 15 или более минут в зависимости от размера развертывания. У уровня "Разработчик" есть время простоя, а уровня "Базовый" и выше — нет.

Как прокси-сервер управления 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 личных доменов для домена (поддерживается только на уровне Премиум) и обойти это ограничение.

Настройка DNS

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

Примечание

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

Запись CNAME

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

Примечание

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

Запись типа TXT

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

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

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

Вы также можете получить идентификатор владения доменом, вызвав соответствующий REST API.

Дальнейшие действия

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