Compartir vía

Protección de API mediante la autenticación de certificados de cliente en API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

API Management proporciona la capacidad de proteger el acceso a las API (es decir, de cliente a API Management) mediante certificados de cliente y autenticación MLS mutua. Puede validar los certificados presentados por el cliente que se conecta y comprobar las propiedades del certificado con los valores deseados mediante expresiones de directiva.

Para obtener información acerca de cómo proteger el acceso al servicio de back-end de una API mediante certificados de cliente (es decir, de API Management a back-end), consulte Protección de servicios back-end mediante la autenticación de certificados de cliente.

Para obtener información general conceptual sobre la autorización de API, consulte Autenticación y autorización para API en API Management.

Opciones de certificado

Para la validación de certificados, API Management puede comprobar los certificados administrados en la instancia de API Management. Si decide usar API Management para administrar certificados de cliente, tiene las siguientes opciones:

  • Hacer referencia a un certificado administrado en Azure Key Vault
  • Agregar un archivo de certificado directamente en API Management

Se recomienda el uso de certificados de Key Vault, ya que esto ayuda a mejorar la seguridad de API Management:

  • Los certificados almacenados en almacenes de claves se pueden reutilizar entre servicios.
  • Las directivas de acceso granular se pueden aplicar a los certificados almacenados en los almacenes de claves.
  • Los certificados actualizados en el almacén de claves se rotan automáticamente en API Management. Después de la actualización en el almacén de claves, un certificado en API Management se actualiza en un plazo de 4 horas. También puede actualizar manualmente el certificado mediante Azure Portal o a través de la API REST de administración.

Requisitos previos

  • Si todavía no ha creado una instancia de servicio de API Management, consulte Creación de una instancia de servicio de API Management.

  • Debe acceder al certificado y a la contraseña para su administración en Azure Key Vault o para cargarlos al servicio de API Management. El certificado debe estar en formato CER o PFX. Se admiten los certificados autofirmados.

    Si usa un certificado autofirmado, instale también certificados de entidad de certificación raíz e intermedios de confianza en la instancia de API Management.

    Nota:

    Los certificados de CA para la validación de certificados no se admiten en el nivel de consumo.

Requisitos previos para la integración de un almacén de claves

Nota:

Actualmente, esta característica no está disponible en las áreas de trabajo.

  1. Si aún no tiene un almacén de claves, créelo. Para conocer los pasos para crear un almacén de claves, vea Inicio rápido: Creación de un almacén de claves mediante Azure Portal.

    Para crear o importar un certificado en el almacén de claves, consulte Inicio rápido: Establecimiento y recuperación de un certificado de Azure Key Vault mediante Azure Portal.

  2. Habilite una identidad administrada asignada por el sistema o por el usuario en la instancia de API Management.

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.

Requisitos de firewall de Key Vault

Si el firewall de Key Vault está habilitado en el almacén de claves, los siguientes son requisitos adicionales:

  • Para acceder al almacén de claves, debe usar la identidad administrada asignada por el sistema de la instancia de API Management.

  • En el firewall de Key Vault, establezca la opción ¿Quiere permitir que los servicios de confianza de Microsoft puedan omitir este firewall?

  • Asegúrese de que la dirección IP del cliente local tenga permiso para acceder al almacén de claves temporalmente mientras selecciona un certificado o secreto para agregar a Azure API Management. Para más información, vea Configuración de redes de Azure Key Vault.

    Después de completar la configuración, puede bloquear la dirección del cliente en el firewall del almacén de claves.

Requisitos de red virtual

Si la instancia de API Management se ha implementado en una red virtual, configure también las siguientes opciones de red:

Para más información, vea Configuración de red al configurar Azure API Management en una red virtual.

Adición de un certificado del almacén de claves

Consulte Requisitos previos para la integración de un almacén de claves.

Importante

Al agregar un certificado de almacén de claves a la instancia de API Management, debe tener permisos para enumerar los secretos del almacén de claves.

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 agregar un certificado del almacén de claves a API Management:

  1. Vaya a la instancia de API Management en Azure Portal.

  2. En Seguridad, seleccione Certificados.

  3. Seleccione Certificados>+ Agregar.

  4. En Id. , introduzca el nombre que desee.

  5. En Certificado, seleccione Almacén de claves.

  6. Escriba el identificador de un certificado de almacén de claves o elija Seleccionar para seleccionar un certificado de un almacén de claves.

    Importante

    Si especifica usted mismo el identificador de un certificado del almacén de claves, asegúrese de que no tenga la información de versión. De lo contrario, el certificado no se rotará automáticamente en API Management después de una actualización en el almacén de claves.

  7. En Client identity (Identidad del cliente), seleccione una identidad asignada por el sistema o una identidad administrada existente asignada por el usuario. Obtenga información sobre cómo agregar o modificar identidades administradas en el servicio de API Management.

    Nota

    La identidad necesita permisos para obtener y enumerar los certificados del almacén de claves. Si aún no ha configurado el acceso al almacén de claves, API Management se lo pedirá para poder configurar automáticamente la identidad con los permisos necesarios.

  8. Seleccione Agregar.

    Captura de pantalla de la adición de un certificado del almacén de claves a API Management en el portal.

  9. Seleccione Guardar.

Carga de un certificado

Para cargar un certificado de cliente en API Management:

  1. Vaya a la instancia de API Management en Azure Portal.

  2. En Seguridad, seleccione Certificados.

  3. Seleccione Certificados>+ Agregar.

  4. En Id. , introduzca el nombre que desee.

  5. En Certificado, seleccione Personalizado.

  6. Navegue para seleccionar el archivo .pfx del certificado y escriba su contraseña.

  7. Seleccione Agregar.

    Captura de pantalla de la carga de un certificado cliente a API Management en el portal.

  8. Seleccione Guardar.

Nota

Si solo desea usar el certificado para autenticar al cliente con API Management, puede cargar un archivo CER.

Habilitación de la instancia de API Management que va a recibir y comprobar certificados de cliente

Niveles Desarrollador, Básico, Estándar y Prémium

Para recibir y comprobar certificados de cliente a través de HTTP/2 en los niveles Desarrollador, Básico, Estándar o Prémium, debe habilitar el valor Negociar certificado de cliente en la hoja Dominio personalizados, como se muestra a continuación.

Negociación del certificado de cliente

Consumo, nivel Básico v2, Estándar v2

Para recibir y verificar certificados de cliente en los niveles Consumo, Básico v2 o Estándar v2, debe habilitar la configuración Solicitar certificado de cliente en el panel Dominios personalizados, como se muestra a continuación.

Solicitar certificado de cliente

Directiva para validar certificados de cliente

Use la directiva validate-client-certificate para validar uno o varios atributos de un certificado de cliente que se usan para acceder a las API hospedadas en la instancia de API Management.

Configure la directiva para validar uno o varios atributos, incluidos el emisor de certificado, el asunto, la huella digital, si el certificado se valida con la lista de revocación en línea y otros.

Validación de certificados con variables de contexto

También puede crear expresiones de directiva con la variable context para comprobar los certificados de cliente. En los ejemplos de las secciones siguientes se muestran expresiones que usan la propiedad context.Request.Certificate y otras propiedades context.

Nota:

Es posible que la autenticación mutua de certificados no funcione correctamente cuando el punto de conexión de puerta de enlace de API Management se expone a través de Application Gateway. Esto se debe a que Application Gateway funciona como equilibrador de carga de nivel 7, estableciendo una conexión SSL distinta con el servicio de back-end de API Management. Por lo tanto, el certificado adjunto por el cliente en la solicitud HTTP inicial no se reenviará a APIM. Sin embargo, como solución alternativa, puede transmitir el certificado mediante la opción de variables de servidor. Para obtener instrucciones detalladas, consulte Variables de servidor de autenticación mutua.

Importante

  • A partir de mayo de 2021, la propiedad context.Request.Certificate solo solicita el certificado cuando hostnameConfiguration de la instancia de API Management establece la propiedad negotiateClientCertificate en True. De manera predeterminada, negotiateClientCertificate se establece en False.
  • Si la renegociación de TLS está deshabilitada en el cliente, es posible que vea errores de TLS al solicitar el certificado mediante la propiedad context.Request.Certificate. Si esto ocurriera, habilite la configuración de renegociación de TLS en el cliente.
  • La renegociación de certificaciones no se admite en los niveles v2 de API Management.

Comprobación del emisor y el asunto

Es posible configurar las directivas siguientes para comprobar el emisor y el firmante de un certificado de cliente:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Nota

Para deshabilitar la comprobación de la lista de revocación de certificados, use context.Request.Certificate.VerifyNoRevocation() en lugar de context.Request.Certificate.Verify(). Si el certificado de cliente es un certificado autofirmado, los certificados CA raíz (o intermedios) deben cargarse en API Management para que context.Request.Certificate.Verify() y context.Request.Certificate.VerifyNoRevocation() funcionen.

Comprobación de la huella digital

Es posible configurar las directivas siguientes para comprobar la huella digital de un certificado de cliente:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Nota

Para deshabilitar la comprobación de la lista de revocación de certificados, use context.Request.Certificate.VerifyNoRevocation() en lugar de context.Request.Certificate.Verify(). Si el certificado de cliente es un certificado autofirmado, los certificados CA raíz (o intermedios) deben cargarse en API Management para que context.Request.Certificate.Verify() y context.Request.Certificate.VerifyNoRevocation() funcionen.

Comprobación de una huella digital en relación con certificados cargados en API Management

En el ejemplo siguiente se muestra cómo comprobar la huella digital de un certificado de cliente en relación con los certificados cargados en API Management:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Nota

Para deshabilitar la comprobación de la lista de revocación de certificados, use context.Request.Certificate.VerifyNoRevocation() en lugar de context.Request.Certificate.Verify(). Si el certificado de cliente es un certificado autofirmado, los certificados CA raíz (o intermedios) deben cargarse en API Management para que context.Request.Certificate.Verify() y context.Request.Certificate.VerifyNoRevocation() funcionen.

Sugerencia

El problema de interbloqueo de certificados de cliente descrito en este artículo puede manifestarse de varias maneras, por ejemplo, las solicitudes se inmovilizan, las solicitudes resultan en un código de estado 403 Forbidden después de agotar el tiempo, context.Request.Certificate es null. Este problema afecta normalmente a las solicitudes POST y PUT con la longitud del contenido de aproximadamente 60 KB o más. Para evitar que este problema se produzca, active "Negociar certificado de cliente" para los nombres de host deseados en la hoja "Dominios personalizados", tal como se muestra en la primera imagen de este documento. Esta característica no está disponible en el nivel Consumo.

Pasos siguientes