Acerca del certificado de la AC raíz de Apigee y su rotación

Esta página se aplica a Apigee, pero no a Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se describe el certificado de la autoridad de certificación raíz de Apigee que protege las conexiones TLS al entorno de ejecución de Apigee y se explica el proceso de rotación. También se enumeran los patrones de acceso que se ven afectados por una rotación y los pasos que debes seguir para preparar tus aplicaciones.

Acerca del certificado de la AC raíz

Cada organización de Apigee tiene un certificado de la AC raíz administrado por Google que emite el certificado de servidor que utiliza la entrada de Apigee Runtime para la finalización de TLS. Cuando un cliente abre una conexión HTTPS a una instancia de Apigee, el servidor presenta un certificado que se encadena a esta CA raíz. Los clientes que validan el certificado del servidor deben confiar en la CA raíz, ya sea de forma implícita (cuando el tráfico fluye a través de un balanceador de cargas administrado por el cliente que finaliza TLS) o explícita (cuando el cliente se conecta directamente al tiempo de ejecución de Apigee).

El certificado de la AC raíz se expone en la respuesta de la API de organizations.get en el campo caCertificates[]. El campo es un array porque, durante una rotación, se devuelven al mismo tiempo los certificados de CA raíz actuales y los próximos para que los clientes puedan confiar en ambos antes de la migración de sistemas.

Por qué se rota el certificado de la AC raíz

El certificado de la AC raíz de Apigee tiene un período de validez largo, pero finito (por lo general, 10 años). Se rota antes de que venza para que se cumplan las siguientes condiciones:

  • El certificado que protege el entorno de ejecución de Apigee nunca vence mientras está en uso.
  • Los canales de comunicación internos entre los componentes de Apigee siguen funcionando sin interrupciones.

La rotación es una operación de rutina planificada. Apigee lo ejecuta según un programa que Google Cloud controla. No inicias la rotación, y esta no cambia por sí sola el extremo del entorno de ejecución de Apigee ni la superficie de la API de Apigee.

Etapas y cronograma de la rotación

Apigee rota el certificado de la AC raíz en cuatro etapas. Cada etapa es gradual: se aplica región por región en toda tu organización y lleva tiempo completarla. En la siguiente tabla, se describe el efecto visible para el cliente de cada etapa y el momento típico en el que comienza, medido en relación con la fecha de vencimiento de la CA raíz actual.

Etapa Tiempos típicos Qué hay en caCertificates[] Qué ocurre
1. Se publicó un certificado nuevo Aproximadamente 1 año antes de que venza el certificado actual Actuales y nuevos (ambos) Apigee genera el nuevo certificado de la AC raíz y lo agrega al almacén de certificados de confianza de cada componente propiedad de Apigee. El certificado nuevo también aparece en la respuesta de organizations.get para que puedas recuperarlo y prepararlo. El entorno de ejecución de Apigee sigue presentando un certificado de servidor firmado por la CA raíz actual, por lo que los clientes existentes aún no se ven afectados. Apigee envía una notificación al cliente cuando comienza esta etapa.
2. Migración del certificado de hoja Aproximadamente 60 días antes de que venza el certificado actual Actuales y nuevos (ambos) El tiempo de ejecución de Apigee comienza a presentar un nuevo certificado de servidor (hoja) firmado por la nueva CA raíz. Los clientes que solo confían en la CA raíz actual fallarán la validación de TLS después de que se complete esta etapa en su región. Los clientes que confían en ambos certificados (o solo en el nuevo) seguirán funcionando. Apigee envía una notificación al cliente cuando comienza esta etapa.
3. Se retiró el certificado anterior Aproximadamente 30 días antes de que venza el certificado actual Solo nuevos Apigee quita la AC raíz anterior de los almacenes de confianza internos y deja de devolverla desde organizations.get. Los clientes que aún confían solo en la CA raíz anterior no se pueden conectar. Apigee envía una notificación al cliente cuando comienza esta etapa.
4. Se completó la rotación En la fecha de vencimiento original Solo nuevos Apigee borra de forma permanente la CA raíz anterior y la rotación finaliza. La nueva CA raíz ahora es la única, y comienza un nuevo ciclo de aproximadamente 10 años. Apigee envía una notificación al cliente cuando se completa esta etapa.

A quiénes afecta una rotación

Si una rotación requiere que tomes medidas, depende de cómo los clientes acceden a tu entorno de ejecución de Apigee:

Patrón de acceso ¿Se requiere alguna acción? Por qué
Enrutamiento externo (MIG) con un balanceador de cargas de aplicaciones externo de Google Cloud No Tu balanceador de cargas externo finaliza la conexión TLS con un certificado que administras. Los clientes confían en tu certificado, no en la AC raíz de Apigee. La rotación no afecta a estos clientes.
Enrutamiento interno (VPC), opción 1 de TLS (balanceador de cargas de aplicaciones HTTPS interno) No Tu balanceador de cargas interno finaliza la conexión TLS con un certificado que tú administras. Los clientes confían en tu certificado, no en la AC raíz de Apigee. La rotación no afecta a estos clientes.
Enrutamiento interno (VPC), opción 2 de TLS (nombre de dominio interno predeterminado completamente calificado) Sí Los clientes se conectan directamente al balanceador de cargas interno administrado por Apigee y validan el certificado del servidor emitido por Apigee. Cada cliente debe confiar en la nueva CA raíz antes de la migración de la rotación.
Conexión TCP directa a la IP de entrada de la instancia de ejecución (por ejemplo, a través de un balanceador de cargas TCP interno) Sí Los clientes validan el certificado de servidor emitido por Apigee. Cada cliente debe confiar en la nueva CA raíz antes de la migración de sistemas de la rotación.
Opción sin TLS (la marca curl -k o cualquier cliente que omita la validación del certificado) No El cliente no valida el certificado del servidor, por lo que la rotación no tiene ningún efecto funcional. Esta opción no se recomienda fuera de los entornos de prueba.

Cómo prepararse para una rotación

Si usas uno de los patrones de acceso que requieren acción, sigue estos pasos antes de la fecha de migración de sistemas de rotación que recibas en la notificación de rotación.

Paso 1: Descubre las instancias del entorno de ejecución de Apigee

Enumera las instancias del entorno de ejecución de Apigee en tu organización. Cada instancia tiene una IP de entrada dedicada, que es el host al que llegan los clientes de conexión directa.

# Ensure $AUTH and $PROJECT_ID are set in your environment
curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances \
  | jq -r '.instances[] | "\(.name)\t\(.host)"'

Si tus clientes se conectan a un host que no sea estas IPs (por ejemplo, tu propio nombre de DNS delante de un balanceador de cargas interno), usa ese host.

Paso 2: Recupera los certificados de CA raíz actuales y próximos

Lee el campo caCertificates[] de organizations.get. Durante una rotación, este array contiene la CA raíz actual y la nueva, ambas codificadas en base64:

curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

Decodifica cada entrada al formato PEM y, luego, inspecciona el período de validez para identificar el certificado nuevo:

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
  echo "==> ${f%.b64}.crt"
  openssl x509 -in "${f%.b64}.crt" -noout -subject -issuer -dates
done

El certificado con la fecha notAfter posterior es la nueva CA raíz.

Paso 3: Agrega la nueva CA raíz a tus almacenes de confianza

Agrega el nuevo certificado de la AC raíz a cada almacén de certificados de confianza del cliente que actualmente confíe en la CA raíz de Apigee. Mantén la CA raíz actual hasta que se complete el cambio, de modo que las conexiones sigan funcionando durante la ventana de cambio. Después de la migración de sistemas, puedes quitar la CA raíz anterior de tus almacenes de certificados de confianza.

El procedimiento exacto depende del cliente. Los casos comunes incluyen los siguientes:

  • Agrega el certificado al almacén de certificados de confianza a nivel del SO (por ejemplo, /etc/ssl/certs/ en sistemas basados en Debian seguido de update-ca-certificates).
  • Agrega el certificado a un almacén de certificados de confianza administrado por la aplicación (por ejemplo, un almacén de claves cacerts de Java, un paquete ssl_trusted_certificate de Nginx o un paquete de confianza validation_context de Envoy).
  • Agregar el certificado a un Secret o ConfigMap de Kubernetes que se encuentre montado en los Pods de tu carga de trabajo

Paso 4: Verifica que la conexión funcione con la nueva CA raíz

Después de transferir la nueva CA raíz, verifica que una solicitud HTTPS al entorno de ejecución de Apigee se realice correctamente cuando solo confíes en el nuevo certificado:

# Ensure $ENV_GROUP_HOSTNAME and $INTERNAL_LOAD_BALANCER_IP are set
curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

Si este comando se ejecuta correctamente, tu cliente estará listo para la migración de sistemas. Si falla, el cliente aún no confía en la nueva CA raíz. Vuelve al paso 3.

Ejemplo: Enrutamiento interno (VPC), opción 2 de TLS

En este ejemplo, se muestran los pasos de rotación para el patrón de acceso que se documenta en Enrutamiento interno (VPC), opción 2 de TLS, en el que el cliente se conecta directamente al balanceador de cargas interno de Apigee y valida el certificado autofirmado de Apigee. Este es el patrón de acceso más afectado por una rotación.

Antes de la migración de sistemas:

  1. Obtén la IP del balanceador de cargas interno de Apigee: 
    export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \
  | jq -r '.instances[0].host')
  2. Recupera las CA raíz actuales y nuevas en archivos separados, y luego identifica la nueva: 
    curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID \
  | jq -r '.caCertificates[]' \
  | awk '/-----BEGIN/{i++}{print > ("ca_" i ".b64")}'

for f in ca_*.b64; do
  base64 -d "$f" > "${f%.b64}.crt"
done

# Identify the new root CA (latest notAfter):
openssl x509 -in ca_1.crt -noout -dates
openssl x509 -in ca_2.crt -noout -dates
  3. Crea un almacén de confianza combinado que contenga la CA raíz actual y la nueva, y úsalo para tu solicitud de prueba: 
    cat ca_1.crt ca_2.crt > cacert-combined.crt

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert cacert-combined.crt \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

    Si esta solicitud se realiza correctamente, implementa cacert-combined.crt como tu almacén de confianza del cliente. El almacén de confianza combinado seguirá validando el certificado actual hoy y validará el certificado nuevo después de la transición.

Después de la migración de sistemas (por lo general, unos días después de la fecha de la migración de sistemas), confirma la rotación verificando que la conexión siga funcionando cuando solo confíes en el certificado nuevo:

curl -is -H "Host: $ENV_GROUP_HOSTNAME" \
  https://example.$PROJECT_ID.apigee.internal/PROXY_BASEPATH \
  --cacert NEW_CA_FILE \
  --resolve example.$PROJECT_ID.apigee.internal:443:$INTERNAL_LOAD_BALANCER_IP

Cuando esta solicitud se realice correctamente, podrás quitar de forma segura la CA raíz anterior de tu almacén de confianza.

Notificaciones

Apigee envía una notificación a los propietarios del proyecto y de la organización de tu proyecto Google Cloud al comienzo de cada etapa de rotación. Cada notificación incluye el nombre de la etapa, la fecha en que se aplicará a tu organización y un vínculo a esta página.

Notificación Acción recomendada para el cliente
1. Se publicó un certificado nuevo
(alrededor de 1 año antes del vencimiento)		 Recupera la nueva CA raíz de caCertificates[] y agrégala a cada almacén de certificados de confianza del cliente que actualmente confía en la CA raíz de Apigee. Consulta Cómo prepararse para una rotación.
2. Migración de sistemas del certificado de entidad final
(aproximadamente 60 días antes del vencimiento)		 Confirma que todos tus clientes confían en la nueva CA raíz antes de que esta etapa se aplique a tu región. Después de esta etapa, los clientes que solo confían en la CA raíz anterior no podrán conectarse.
3. Se retiró el certificado anterior
(alrededor de 30 días antes del vencimiento)		 Una vez que se haya aplicado esta etapa a todas tus regiones, podrás quitar de forma segura la CA raíz anterior de los almacenes de confianza de tu cliente.
4. Se completó la rotación
(en la fecha de vencimiento original)		 No se requiere ninguna acción. La CA raíz anterior se borró de forma permanente, y la nueva es la única CA raíz de tu organización.

Si no recibes notificaciones de rotación y usas uno de los patrones de acceso que se indican en ¿A quién afecta una rotación?, comunícate con el equipo de asistencia de Apigee para confirmar los destinatarios de las notificaciones de tu organización.

¿Qué sigue?