Compartir por


Configuración de un nombre de dominio personalizado para la instancia de Azure API Management

SE APLICA A: todos los niveles de API Management

Cuando se crea una instancia de servicio de Azure API Management en la nube de Azure, Azure le asigna un subdominio azure-api.net (por ejemplo, apim-service-name.azure-api.net). También puede exponer los puntos de conexión de API Management con su propio nombre de dominio personalizado, como contoso.com . En este artículo se muestra cómo asignar un nombre DNS personalizado existente a los puntos de conexión expuestos por una instancia de API Management.

Importante

API Management solo acepta solicitudes con valores de encabezado host que coincidan con:

  • Nombre de dominio predeterminado de la puerta de enlace
  • Cualquiera de los nombres de dominio personalizados configurados de la puerta de enlace

Nota:

Actualmente, no se admiten nombres de dominio personalizados en una puerta de enlace del espacio de trabajo.

Requisitos previos

  • Una instancia de API Management Para más información, vea Creación de una instancia de Azure API Management.

  • Nombre de dominio personalizado que propiedad de su organización o suyo. En este artículo no se dan instrucciones para adquirir un nombre de dominio personalizado.

  • Opcionalmente, un certificado válido con una clave pública y privada (.PFX). El firmante o el nombre alternativo del firmante (SAN) debe coincidir con el nombre de dominio. De este modo, API Management puede exponer de forma segura direcciones URL mediante TLS.

    Vea Opciones de certificado de dominio.

  • Los registros DNS hospedados en un servidor DNS para asignar el nombre de dominio personalizado al nombre de dominio predeterminado de una instancia de API Management. En este tema no se proporcionan instrucciones para hospedar los registros DNS.

    Para más información sobre los registros requeridos, vea Configuración de DNS más adelante en este artículo.

Puntos de conexión para dominios personalizados

Hay varios puntos de conexión de API Management a los que puede asignar un nombre de dominio personalizado. En la actualidad, están disponibles los siguientes:

Punto de conexión Valor predeterminado
Puerta de enlace El valor predeterminado es <apim-service-name>.azure-api.net. La puerta de enlace es el único punto de conexión disponible para la configuración en el nivel Consumo.

La configuración predeterminada del punto de conexión de puerta de enlace sigue estando disponible después de agregar un dominio de puerta de enlace personalizada.
Portal para desarrolladores El valor predeterminado es <apim-service-name>.developer.azure-api.net.
Administración El valor predeterminado es <apim-service-name>.management.azure-api.net.
API de configuración (v2) El valor predeterminado es <apim-service-name>.configuration.azure-api.net.
SCM El valor predeterminado es <apim-service-name>.scm.azure-api.net.

Consideraciones

  • Puede actualizar cualquiera de los puntos de conexión admitidos en el nivel de servicio. Por lo general, los clientes actualizan Puerta de enlace (esta dirección URL se utiliza para llamar a las API expuestas a través de API Management) y Portal para desarrolladores (dirección URL del portal para desarrolladores).
  • El punto de conexión predeterminado de Puerta de enlace sigue estando disponible después de configurar un nombre de dominio de puerta de enlace personalizada y no se puede eliminar. Para otros puntos de conexión de API Management (como el portal para desarrolladores) que se configuran con un nombre de dominio personalizado, el punto de conexión predeterminado ya no está disponible.
  • Solo los propietarios de instancias de API Management pueden usar los puntos de conexión de administración y SCM internamente. A estos puntos de conexión se les asigna con menos frecuencia un nombre de dominio personalizado.
  • Los niveles Premium y Desarrollador admiten la configuración de varios nombres de host para el punto de conexión Puerta de enlace.
  • Los nombres de dominio con caracteres comodín, como *.contoso.com, se admiten en todos los niveles, salvo en el nivel de consumo. Un certificado de subdominio específico (por ejemplo, api.contoso.com) tendría prioridad sobre un certificado de carácter comodín (*.contoso.com) para las solicitudes a api.contoso.com.

Opciones de certificado de dominio

API Management admite certificados TLS personalizados o certificados importados desde Azure Key Vault. También puede habilitar un certificado administrado gratuito.

Advertencia

Si necesita anclar certificados, use un nombre de dominio personalizado y un certificado personalizado o de Key Vault, no el certificado predeterminado ni el certificado administrado gratuito. No se recomienda adoptar una dependencia permanente de un certificado que no administre.

Si ya tiene un certificado privado de un proveedor de terceros, puede cargarlo en la instancia de API Management. Debe cumplir los siguientes requisitos. (Si habilita el certificado gratuito administrado por API Management, ya cumple estos requisitos).

  • Se exporta como un archivo PFX cifrado mediante Triple DES u opcionalmente protegido con contraseña.
  • Contener una clave privada con una longitud de al menos 2048 bits
  • Contiene todos los certificados intermedios y el certificado raíz de la cadena de certificados.

Configuración de un nombre de dominio personalizado (portal)

Elija los pasos según el certificado de dominio que desea usar.

  1. Vaya a la instancia de API Management en Azure Portal.
  2. En el panel de navegación izquierdo, seleccione Dominios personalizados.
  3. Seleccione +Agregar o seleccione un punto de conexión existente que quiera actualizar.
  4. En la ventana de la derecha, seleccione el Tipo de punto de conexión para el dominio personalizado.
  5. En el campo Nombre de host, especifique el nombre que desee usar. Por ejemplo, api.contoso.com.
  6. En Certificado, seleccione Personalizado.
  7. Seleccione Archivo de certificado para seleccionar y cargar un certificado.
  8. Cargue un archivo .PFX válido y proporcione su contraseña si el certificado está protegido con una contraseña.
  9. Al configurar un punto de conexión de puerta de enlace, seleccione o anule la selección de otras opciones según sea necesario, incluidas Negociar certificado de cliente o Enlace SSL predeterminado. Configuración del dominio de puerta de enlace con el certificado personalizado
  10. Seleccione Agregar o Actualizar para un punto de conexión existente.
  11. Seleccione Guardar.

Configuración de DNS

  • Configure un registro CNAME para el dominio personalizado.
  • Al usar el certificado administrado gratuito de API Management, configure también un registro TXT para establecer la titularidad del dominio.

Nota

El certificado gratuito lo emite DigiCert. En algunos dominios, debe permitir explícitamente DigiCert como emisor de certificados mediante la creación de un registro de dominio de CAA con el valor 0 issue digicert.com.

Registro CNAME

Configure un registro CNAME que apunta desde el nombre de dominio personalizado (por ejemplo, api.contoso.com) al nombre de host del servicio API Management (por ejemplo, <apim-service-name>.azure-api.net). Un registro CNAME es más estable que un registro A en caso de que cambie la dirección IP. Para más información, vea Direcciones IP de Azure API Management y P+F de Azure API Management.

Nota

Algunos registradores de dominio solo permiten asignar subdominios cuando se usa un registro CNAME, como www.contoso.com, y no nombres raíz, como contoso.com. Para obtener más información sobre los registros CNAME, consulte la documentación que proporciona el registrador o Nombres de dominio IETF: implementación y especificación.

Precaución

Al usar el certificado administrado gratuito y configurar un registro CNAME con el proveedor de DNS, asegúrese de que se resuelve en el nombre de host de servicio predeterminado de API Management (<apim-service-name>.azure-api.net). Actualmente, API Management no renueva automáticamente el certificado si el registro CNAME no se resuelve en el nombre de host de API Management predeterminado. Por ejemplo, si usa el certificado administrado gratuito y usa Cloudflare como proveedor de DNS, asegúrese de que el proxy DNS no está habilitado en el registro CNAME.

Registro TXT

Al habilitar el certificado administrado gratuito para API Management, configure también un registro TXT en la zona DNS para establecer la propiedad del nombre de dominio.

  • El nombre del registro es el nombre de dominio personalizado precedido de apimuid. Ejemplo: apimuid.api.contoso.com.
  • El valor es un identificador de propiedad de dominio proporcionado por la instancia de API Management.

Cuando se usa el portal para configurar el certificado administrado gratuito para el dominio personalizado, se muestran automáticamente el nombre y el valor del registro TXT necesario.

También puede obtener un identificador de propiedad de dominio llamando a la API de REST Get Domain Ownership Identifier.

Respuesta del servidor proxy de API Management con certificados SSL en el protocolo de enlace TLS

Al configurar un dominio personalizado para el punto de conexión de puerta de enlace, puede establecer propiedades adicionales que determinen cómo responde API Management con un certificado de servidor, en función de la solicitud de cliente.

Clientes que llaman con el encabezado Indicación de nombre de servidor (SNI)

Si tiene uno o varios dominios personalizados configurados para el punto de conexión de puerta de enlace, API Management puede responder a solicitudes HTTPS desde:

  • Dominio personalizado (por ejemplo, contoso.com)
  • Dominio predeterminado (por ejemplo, apim-service-name.azure-api.net).

En función de la información del encabezado SNI, API Management responde con el certificado de servidor adecuado.

Clientes que llaman sin encabezado SNI

Si el usuario usa un cliente que no envía el encabezado SNI, API Management crea respuestas basadas en la lógica siguiente:

  • Si el servicio tiene un solo dominio personalizado configurado para la puerta de enlace, el certificado predeterminado es el que se emite al dominio personalizado de la puerta de enlace.

  • Si el servicio ha configurado varios dominios personalizados para la puerta de enlace (admitidos en el nivel Desarrollador y Premium), puede designar el certificado predeterminado estableciendo la propiedad defaultSslBinding en true ("defaultSslBinding":"true"). En el portal, active la casilla Enlace SSL predeterminado.

    Si no establece la propiedad, el certificado predeterminado es el que se emite al dominio de puerta de enlace predeterminada hospedado en *.azure-api.net.

Compatibilidad para la solicitud PUT/POST con una carga grande

El servidor proxy de API Management admite solicitudes con cargas grandes (>40 KB) cuando se usan certificados del lado cliente en HTTPS. Para evitar que la solicitud del servidor se quede congelada, puede establecer la propiedad negotiateClientCertificate en true ("negotiateClientCertificate": "true") en el nombre de host de puerta de enlace. En el portal, active la casilla Negociar certificado de cliente.

Si la propiedad está establecida en true, el certificado de cliente se solicita en el tiempo de conexión SSL/TLS, antes de intercambiar cualquier solicitud HTTP. Puesto que la configuración se aplica al nivel de Nombre de host de la puerta de enlace, todas las solicitudes de conexión piden el certificado de cliente. Puede evitar esta limitación y configurar hasta 20 dominios personalizados para la puerta de enlace (solo se admite en el nivel Prémium).

Pasos siguientes

Actualización y escalado del servicio