Настройте пользовательское доменное имя для экземпляра службы управления API Azure
ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API
Когда вы создаете экземпляр службы "Управления API" в облаке Azure, Azure назначает ему поддомен azure-api.net (например, apim-service-name.azure-api.net). Вы также можете предоставить доступ к своим конечным точкам управления API, используя собственное доменное имя, например contoso.com. В этой статье показано, как сопоставить существующее пользовательское имя DNS с конечными точками, предоставляемыми экземпляром Управления API.
Внимание
Управление API принимает только запросы, в которых заголовок хоста совпадает со следующим:
- доменное имя шлюза по умолчанию;
- любое настроенное пользовательское доменное имя шлюза.
Примечание.
В настоящее время имена пользовательских доменов не поддерживаются в шлюзе рабочей области.
Необходимые компоненты
Экземпляр управления API. Дополнительные сведения см. в статье о создании экземпляра управления API Azure.
Пользовательское доменное имя, принадлежащее вам или вашей организации. В этой статье не приводятся инструкции по приобретению пользовательского доменного имени.
Действительный сертификат с открытым и закрытым ключом (PFX) (необязательно). Субъект или альтернативное имя субъекта (SAN) должны совпадать с доменным именем (это позволяет экземпляру Управления API безопасно предоставлять URL-адреса через TLS).
См. раздел Варианты сертификатов домена.
DNS-записи, размещенные на DNS-сервере, которые сопоставляют пользовательское доменное имя с доменным именем по умолчанию для вашего экземпляра Управления API. В этом разделе не приводятся инструкции по размещению DNS-записей.
Дополнительные сведения о требуемых записях см. в разделе Настройка DNS далее в этой статье.
Конечные точки для личных доменов
Есть ряд конечных точек Управления API, которым вы можете назначить пользовательское доменное имя. Сейчас доступны следующие конечные точки:
| Конечная точка | По умолчанию. |
|---|---|
| Шлюз | По умолчанию: <apim-service-name>.azure-api.net. Шлюз — единственная конечная точка, доступная для настройки на уровне потребления.Конфигурация конечной точки шлюза по умолчанию остается доступной после добавления домена пользовательского шлюза. |
| Developer portal | По умолчанию: <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 |
Рекомендации
- Вы можете обновить любую конечную точку, поддерживаемую на уровне служб. Обычно клиенты обновляют Шлюз (этот URL-адрес используется для вызова API, предоставляемого через Управление API) и Портал разработчика (URL-адрес портала разработчика).
- Конечная точка шлюза по умолчанию остается доступной после настройки имени домена пользовательского шлюза и не может быть удалена. Для других конечных точек Управление API (например, портала разработчика), настроенных с помощью имени личного домена, конечная точка по умолчанию больше недоступна.
- Только владельцы экземпляров управления API могут использовать конечные точки Управления и SCM для внутренних целей. Этим конечным точкам реже назначается пользовательское доменное имя.
- Уровни Премиум и Разработчик поддерживают установку нескольких имен узлов для конечной точки Шлюз.
- Доменные имена с подстановочными знаками, такие как
*.contoso.com, поддерживаются на всех уровнях, кроме уровня потребления. Определенный поддомен сертификат (например, api.contoso.com) будет иметь приоритет над подстановочным сертификатом (*.contoso.com) для запросов к api.contoso.com.
Варианты сертификатов домена
Управление API поддерживает пользовательские сертификаты TLS и сертификаты, импортированные из Azure Key Vault. Вы также можете активировать бесплатный управляемый сертификат.
Предупреждение
Если вы хотите закрепить сертификат, следует использовать пользовательское доменное имя и пользовательский сертификат или сертификат Key Vault, а не сертификат по умолчанию или бесплатный управляемый сертификат. Мы не рекомендуем настраивать жесткую зависимость от сертификата, которым вы не управляете.
Если у вас уже есть закрытый сертификат от стороннего поставщика, вы можете его отправить в экземпляр Управления API. Он должен соответствовать следующим требованиям (бесплатный сертификат, управляемый службой "Управление API", уже им соответствует этим требованиям):
- экспортирован как PFX-файл, зашифрованный с помощью TRIPLE DES и при необходимости защищенный паролем;
- Содержит закрытый ключ длиной не менее 2048 битов
- должен содержать все промежуточные сертификаты и корневой сертификат в цепочке сертификатов.
Настройка пользовательского доменного имени на портале
Выберите шаги в соответствии с сертификатом домена, который вы хотите использовать.
- Перейдите к своему экземпляру управления API на портале Azure.
- В области навигации слева выберите Личные домены.
- Выберите +Добавить или укажите существующую конечную точку, которую вы хотите обновить.
- В окне справа выберите Тип конечной точки для личного домена.
- В поле Hostname укажите имя, которое вы хотите использовать. Например,
api.contoso.com. - В списке Сертификат выберите Пользовательский.
- Выберите Файла сертификата, чтобы указать отправляемый сертификат.
- Загрузите действительный файл .PFX и укажите его Пароль, если сертификат защищен паролем.
- При настройке конечной точки шлюза по мере необходимости установите или снимите флажки для других параметров, например Согласовать сертификат клиента или Привязка SSL по умолчанию.
- Выберите Добавить или Обновить для существующей конечной точки.
- Выберите Сохранить.
DNS configuration (Настройка 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 — реализация и спецификация.
Внимание
При использовании бесплатного управляемого сертификата и настройки записи CNAME с поставщиком DNS убедитесь, что он разрешается в имя узла<apim-service-name>.azure-api.net службы по умолчанию Управление API (). В настоящее время Управление API не обновляет сертификат автоматически, если запись CNAME не разрешает имя узла по умолчанию Управление API. Например, если вы используете бесплатный управляемый сертификат и используете Cloudflare в качестве поставщика DNS, убедитесь, что DNS-прокси не включен в записи CNAME.
Запись TXT
При включении бесплатного управляемого сертификата для Управления API также настройте запись типа TXT в свой зоне DNS, чтобы установить владение доменным именем.
- Имя записи — это имя личного домена с префиксом
apimuid. Пример:apimuid.api.contoso.com. - Значение — это идентификатор владения доменом, предоставленный экземпляром Управления API.
Если для настройки бесплатного управляемого сертификата для личного домена вы использовали портал, имя и значение необходимой записи типа TXT отображаются автоматически.
Вы также можете получить идентификатор владения доменом, вызвав соответствующий REST API.
Как прокси-сервер управления 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 личных доменов для домена (поддерживается только на уровне Премиум) и обойти это ограничение.