Настройте пользовательское доменное имя для экземпляра службы управления 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 битов
• должен содержать все промежуточные сертификаты и корневой сертификат в цепочке сертификатов.

Хранилище ключей

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

Если вы используете Azure Key Vault для управления сертификатом TLS личного домена, убедитесь, что сертификат вставлен в Key Vault как сертификат, а не как секрет.

Внимание

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

Чтобы получить сертификат TLS/SSL, служба управления API должна иметь список и получать разрешения на секреты в Azure Key Vault, содержащем сертификат.

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

• При использовании инструментов командной строки или API управления эти разрешения необходимо предоставить вручную в два этапа:

  1. На странице Управляемые удостоверения экземпляра Управления API включите управляемое удостоверение, назначаемое системой или пользователем. Обратите внимание на идентификатор субъекта на этой странице.
  2. Назначьте разрешения управляемому удостоверению для доступа к хранилищу ключей. Выполните действия, описанные в следующем разделе.

  Настройка доступа к хранилищу ключей

  1. На портале перейдите к хранилищу ключей.

  2. В меню слева выберите конфигурацию Access и запишите настроенную модель разрешений.

  3. В зависимости от модели разрешений настройте политику доступа к хранилищу ключей или доступ Azure RBAC для управляемого удостоверения Управление API.

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

     1. В меню слева выберите политики доступа.
     2. На странице политик доступа нажмите кнопку +Создать.
     3. На вкладке "Разрешения" в разделе "Разрешения секрета" выберите "Получить" и "Список", а затем нажмите кнопку "Далее".
     4. На вкладке "Субъект" выберите субъект, найдите имя ресурса управляемого удостоверения и нажмите кнопку "Далее". Если вы используете назначаемое системой удостоверение, субъектом является имя экземпляра Управления API.
     5. Снова выберите Далее. На вкладке Проверить и создать выберите Создать.

     Чтобы настроить доступ к Azure RBAC, выполните приведенные действия.
     

     1. В меню слева выберите Управление доступом (IAM).
     2. На странице управления доступом (IAM) выберите " Добавить назначение роли".
     3. На вкладке "Роль" выберите "Пользователь сертификата Key Vault".
     4. На вкладке "Члены" выберите "Управляемое удостоверение>" и "Выбрать участников".
     5. На странице "Выбор управляемого удостоверения" выберите управляемое удостоверение, назначаемое системой, или назначаемое пользователем управляемое удостоверение, связанное с экземпляром Управление API, а затем нажмите кнопку "Выбрать".
     6. Выберите Проверить + назначить.

Если для сертификата установлено значение autorenew, а для вашего уровня Управления API предусмотрено Соглашение об уровне обслуживания (доступное на всех уровнях кроме "Разработчик"), Управление API автоматически загрузит последнюю версию без простоя службы.

Дополнительные сведения см. в статье Использование управляемых удостоверений в Управлении API Azure.

Управляемый

Управление API предлагает бесплатный управляемый сертификат TLS для вашего домена, если вы не хотите приобретать собственный сертификат и управлять им. Сертификат автоматически продлевается.

Примечание.

Бесплатный управляемый сертификат TLS находится в предварительной версии. В настоящее время он недоступен на уровнях служб версии 2.

Ограничения

• Сейчас можно использовать только с конечной точкой шлюза службы "Управление API".
• Не поддерживается в локальном шлюзе
• Не поддерживается в следующих регионах Azure: Южная Франция и Западная часть ЮАР.
• Сейчас доступен только в облаке Azure.
• Не поддерживает корневые доменные имена (например, contoso.com). Требуется полное имя, например api.contoso.com.
• Поддерживает только общедоступные доменные имена
• Можно настроить только при обновлении существующего экземпляра Управления API, а не при добавлении нового.

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

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

Пользовательское

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

Хранилище ключей

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

Управляемый

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

Примечание.

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

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

Следующие шаги

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