HOWTO · Python

Solucione el error SSL: CERTIFICATE_VERIFY_FAILED en Python

Guía para diagnosticar y resolver de forma segura el error de verificación de certificados `SSL: CERTIFICATE_VERIFY_FAILED` en Python.

En esta página

SSL: CERTIFICATE_VERIFY_FAILED significa que Python no pudo determinar si el certificado presentado para una conexión TLS encadena con una autoridad de certificación de confianza y corresponde al host solicitado. Es un fallo de verificación en el cliente; no significa que una autoridad de certificación haya devuelto un error porque el dominio no existe.

TLS cifra el tráfico y autentica el servidor mediante su certificado. Mantén activada la verificación mientras identificas qué parte de esa comprobación de confianza ha fallado.

Qué significa SSL: CERTIFICATE_VERIFY_FAILED

El servidor presenta un certificado TLS durante la conexión. El cliente comprueba su período de validez, el nombre del host, la cadena de emisores y si esta conduce a un certificado raíz de confianza en el almacén de confianza del cliente. El módulo ssl de Python realiza estas comprobaciones cuando se usa un contexto SSL con verificación. Requests también verifica los certificados de forma predeterminada.

El error puede deberse a un problema en cualquiera de los extremos de la conexión. Por ejemplo, es posible que el servidor omita un certificado intermedio y que el entorno local de Python tenga un paquete de CA obsoleto. También pueden explicar el fallo un nombre de host que no coincide, un reloj del sistema incorrecto, una autoridad de certificación privada o un proxy que inspecciona TLS. El error por sí solo no permite saber cuál es la causa.

Diagnostica la causa

Comprueba los siguientes puntos con el mismo nombre de host y el mismo entorno de Python que usa la aplicación donde ocurre el fallo:

  1. Comprueba el certificado y la cadena del servidor. Confirma que el certificado esté vigente, corresponda al nombre de host de la URL e incluya los certificados intermedios necesarios para llegar a su emisor. Si funciona en un navegador u otro cliente, compara su configuración de confianza y su ruta de red; esa diferencia es una pista, no una prueba de que el servidor esté configurado correctamente.
  2. Comprueba el reloj. Asegúrate de que la fecha y la hora de la máquina o el contenedor sean correctas. Si el reloj se aleja mucho del período de validez del certificado, uno válido puede parecer vencido o todavía no válido.
  3. Identifica el entorno de Python y el cliente HTTP. Comprueba qué intérprete ejecuta la aplicación y si la solicitud que falla usa la biblioteca estándar, Requests u otro paquete. El Python del sistema, un entorno virtual, un contenedor y una aplicación empaquetada pueden usar distintos almacenes de confianza.
  4. Comprueba la fuente de confianza y la ruta de red. Averigua si el servidor usa una CA privada y si un proxy corporativo intercepta TLS. Pide al administrador de redes o seguridad el certificado de CA aprobado y las instrucciones para ese entorno. No descargues un certificado de una fuente no verificada solo para que desaparezca el error.

Si el certificado del servidor está vencido, corresponde a otro nombre de host o carece de certificados intermedios necesarios, pide al responsable del servidor que corrija el despliegue. Cambiar el paquete de CA del cliente no puede reparar una cadena del servidor defectuosa.

Corrige el certificado o el almacén de confianza

Si el problema está en el servidor, la solución duradera es que su responsable renueve el certificado o configure correctamente la cadena para el nombre de host solicitado. Probar con otro navegador puede ayudar a comparar el comportamiento, pero no repara el certificado ni hace segura una conexión que no es de confianza.

Para un servicio privado o un proxy aprobado que inspeccione TLS, consigue el certificado de CA raíz de la organización mediante su canal de distribución de confianza. Instálalo en el almacén de confianza que utilice el sistema operativo, el contenedor o el entorno de Python correspondiente, o configura la aplicación para que use ese paquete de CA. Sigue el procedimiento documentado por el administrador para confirmar el origen del certificado y el ámbito para el que está previsto.

Un paquete de CA obsoleto también puede provocar fallos cuando el servidor usa una CA pública más reciente que, por lo demás, es válida. Actualiza el almacén de confianza o el paquete de CA que utiliza la aplicación. Actualizar pip puede ayudar a que el propio pip resuelva los certificados de descarga de paquetes en algunas instalaciones de Python; actualizar certifi puede renovar el paquete que usa Requests cuando está configurado para utilizarlo. Estas actualizaciones no corrigen un certificado de servidor vencido, un nombre de host que no coincide, la falta de un certificado intermedio del servidor ni una CA específica de la organización que todavía no sea de confianza.

Configura Python y Requests para verificar los certificados

El módulo ssl de la biblioteca estándar de Python y Requests pueden usar distintas fuentes de confianza. ssl.create_default_context() carga los valores predeterminados disponibles para ese entorno de Python/OpenSSL, que pueden depender de su compilación y de la configuración de la plataforma. Normalmente, Requests verifica los certificados con el paquete de CA proporcionado por certifi; session.verify = True significa «usar el paquete predeterminado configurado para Requests», no «usar los valores predeterminados de ssl de Python» ni necesariamente el almacén del sistema operativo. Requests también puede obtener la ruta de un paquete mediante REQUESTS_CA_BUNDLE (o CURL_CA_BUNDLE), salvo que configures la sesión explícitamente.

Este breve ejemplo muestra que el contexto predeterminado de Python exige la verificación de certificados y constituye el caso de éxito autocontenido:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

import ssl

context = ssl.create_default_context()
print(context.verify_mode == ssl.CERT_REQUIRED)
True

Para una CA privada, indica a Python el paquete de CA de confianza mediante cafile y pasa ese contexto con verificación a la solicitud HTTPS de la biblioteca estándar. Sustituye ambos valores por la URL del servicio y la ruta del paquete que te haya proporcionado el administrador. Este ejemplo, que depende de un servicio externo, no se ha ejecutado aquí; captura los errores de conexión para que puedas ejecutarlo después de proporcionar tus propios valores.

import ssl
import urllib.error
import urllib.request

SERVICE_URL = "https://service.example"
CA_BUNDLE = "/path/to/organization-ca-bundle.pem"

try:
    context = ssl.create_default_context(cafile=CA_BUNDLE)
    with urllib.request.urlopen(SERVICE_URL, context=context, timeout=10) as response:
        print(response.status)
except (OSError, urllib.error.URLError) as error:
    print(f"Connection not completed: {type(error).__name__}: {error}")

La opción verify de Requests acepta la ruta de un paquete de CA. Asigna a la sesión el paquete proporcionado por la organización y usa esa misma sesión para la solicitud; la comprobación del certificado permanece activada. Sustituye la URL y la ruta por los valores de tu servicio. Este ejemplo, que depende de un servicio externo, tampoco se ha ejecutado aquí.

import requests

SERVICE_URL = "https://service.example"
CA_BUNDLE = "/path/to/organization-ca-bundle.pem"

session = requests.Session()
session.verify = CA_BUNDLE

try:
    response = session.get(SERVICE_URL, timeout=10)
    print(response.status_code)
except (OSError, requests.RequestException) as error:
    print(f"Connection not completed: {type(error).__name__}: {error}")

Usa un paquete de CA cuyo emisor hayas verificado mediante el canal de confianza de tu organización. Un paquete personalizado debe contener los certificados de CA necesarios para validar la cadena del servicio; configurar una CA no corrige un certificado vencido, un nombre de host que no coincide ni la falta de un certificado intermedio en el servidor. Si quieres que Requests use su paquete habitual, deja session.verify con su valor predeterminado en vez de asignarle True; para una CA de la organización, indica una ruta explícita. Actualizar certifi puede renovar las raíces públicas incluidas en Requests si esa es la fuente de confianza obsoleta, mientras que actualizar pip puede ayudar con las descargas de paquetes del propio pip. Ninguna de las dos actualizaciones cambia la configuración de confianza de ssl de Python en todos los entornos ni corrige un certificado de servidor defectuoso.

Por qué no debes desactivar la verificación de certificados

Si desactivas la verificación de certificados, un atacante o un proxy que no sea de confianza puede presentar un certificado de una identidad incorrecta y, aun así, conseguir que el cliente acepte la conexión. El cifrado por sí solo no demuestra que el otro extremo sea el servidor previsto. En ese caso, las credenciales, los tokens y los datos de respuesta podrían quedar expuestos o ser alterados.

No uses verify=False, un contexto SSL sin verificación ni una sustitución global del contexto HTTPS predeterminado de Python como solución. Esas opciones ocultan la señal que ayudaría a diagnosticar el problema y debilitan todas las conexiones afectadas. Restablece la verificación corrigiendo la cadena del servidor, el reloj o el almacén de confianza del cliente, o configurando explícitamente el paquete de CA de confianza.