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.

Personalizada

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.

Key Vault

Se recomienda usar Azure Key Vault para administrar certificados y configurarlos en autorenew.

Si usa Azure Key Vault para administrar un certificado TLS de dominio personalizado, asegúrese de que el certificado se inserta en Key Vault como un certificado, no como un secreto.

Precaución

Al usar un certificado del almacén de claves en API Management, tenga cuidado de no eliminar el certificado, el almacén de claves ni la identidad administrada que se usa para acceder al almacén de claves.

Para capturar un certificado TLS/SSL, API Management debe tener la lista y obtener los permisos de secretos en la instancia de Azure Key Vault que contiene el certificado.

• Cuando se usa Azure Portal para importar el certificado, todos los pasos de configuración necesarios se completan automáticamente.

• Cuando usa las herramientas de línea de comandos o Management API, estos permisos se deben conceder manualmente en dos pasos:

  1. En la página Identidades administradas de la instancia de API Management, habilite una identidad administrada asignada por el sistema o por el usuario. Anote el identificador de la entidad de seguridad en esa página.
  2. Asigne permisos a la identidad administrada para acceder al almacén de claves. Siga los pasos de la sección siguiente.

  Configuración del acceso al almacén de claves

  1. En el portal, vaya al almacén de claves.

  2. En el menú de la izquierda, seleccione Configuración de acceso y anote el modelo de permisos configurado.

  3. En función del modelo de permisos, configure una directiva de acceso al almacén de claves o el acceso de Azure RBAC para una identidad administrada de API Management.

     Para agregar una directiva de acceso al almacén de claves:
     

     1. En el menú de la izquierda, seleccione Directivas de acceso.
     2. En la página Directivas de acceso, seleccione +Crear.
     3. En la pestaña Permisos, en Permisos de secretos, seleccione Obtener y Lista, y luego Siguiente.
     4. En la pestaña Entidad de seguridad, seleccione una entidad de seguridad, busque el nombre del recurso de la identidad administrada y, después, seleccione Siguiente. Si usa una identidad asignada por el sistema, la entidad de seguridad es el nombre de la instancia de API Management.
     5. Seleccione Siguiente de nuevo. En la pestaña Revisar y crear, seleccione Crear.

     Para configurar el acceso de Azure RBAC:
     

     1. En el menú izquierdo, seleccione Control de acceso (IAM) .
     2. En la página Control de acceso (IAM), seleccione Agregar asignación de roles.
     3. En la pestaña Rol, seleccione Usuario de certificado de Key Vault.
     4. En la pestaña Miembros, seleccione Identidad administrada>+Seleccionar miembros.
     5. En la página Seleccionar identidad administrada, seleccione la identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario asociada a la instancia de API Management y, después, seleccione Seleccionar.
     6. Seleccione Revisar y asignar.

Si el certificado está establecido en autorenew y el nivel de API Management tiene un SLA (es decir, en todos los niveles, excepto el nivel de desarrollador), API Management seleccionará automáticamente la última versión sin tiempo de inactividad para el servicio.

Para obtener más información, vea Uso de identidades administradas en Azure API Management.

Administrado

API Management ofrece un certificado TLS administrado gratuito para el dominio, si no desea comprar ni administrar su propio certificado. El certificado se renueva automáticamente.

Nota:

El certificado TLS administrado gratuito está en versión preliminar. Actualmente, no está disponible en los niveles de servicio v2.

Limitaciones

• Actualmente solo se puede usar con el punto de conexión de puerta de enlace del servicio API Management.
• No se admite con la puerta de enlace autohospedada.
• No se admite en las siguientes regiones de Azure: Sur de Francia y Oeste de Sudáfrica.
• Actualmente solo está disponible en la nube de Azure.
• No admite nombres de dominio raíz (por ejemplo, contoso.com). Requiere un nombre completo como api.contoso.com.
• Solo admite nombres de dominio público
• Solo se puede configurar al actualizar una instancia de API Management existente, no al crear la instancia.

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

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

Personalizada

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.
10. Seleccione Agregar o Actualizar para un punto de conexión existente.
11. Seleccione Guardar.

Key Vault

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 Key Vault y, después, Seleccionar.
   1. En la lista desplegable, seleccione Suscripción.
   2. En la lista desplegable, seleccione Key Vault.
   3. Una vez cargados los certificados, seleccione el certificado en la lista desplegable. Haga clic en Seleccionar.
   4. En Identidad de cliente, seleccione una identidad asignada por el sistema o una identidad administrada asignada por el usuario habilitada en la instancia para acceder al almacén de claves.
7. 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.
8. Seleccione Agregar o Actualizar para un punto de conexión existente.
9. Seleccione Guardar.

Administrado

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 Administrado para habilitar un certificado gratuito administrado por API Management. El certificado administrado solo está disponible en versión preliminar para el punto de conexión de puerta de enlace.
7. Copie los valores siguientes y úselos para configurar DNS:
   • Registro TXT
   • Registro CNAME
8. 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.
9. Seleccione Agregar o Actualizar para un punto de conexión existente.
10. Seleccione Guardar.

Nota

El proceso de asignación del certificado puede tardar unos 15 minutos o más según el tamaño de la implementación. El nivel de desarrollador tiene un tiempo de inactividad, mientras que los niveles Básico y superiores no lo tienen.

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