À propos du certificat et de la rotation de l'autorité de certification racine Apigee

Cette page s'applique à Apigee, mais pas à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page décrit le certificat de l'autorité de certification (CA) racine Apigee qui sécurise les connexions TLS au runtime Apigee, et explique le processus de rotation. Il répertorie également les schémas d'accès affectés par une rotation et les étapes à suivre pour préparer vos applications.

À propos du certificat de l'autorité de certification racine

Chaque organisation Apigee dispose d'un certificat d'autorité de certification racine géré par Google, qui émet le certificat de serveur utilisé par l'entrée du runtime Apigee pour l'arrêt TLS. Lorsqu'un client ouvre une connexion HTTPS à une instance Apigee, le serveur présente un certificat qui est associé à cette autorité de certification racine. Les clients qui valident le certificat de serveur doivent faire confiance à l'autorité de certification racine, de manière implicite (lorsque le trafic transite par un équilibreur de charge géré par le client qui met fin à TLS) ou de manière explicite (lorsque le client se connecte directement au runtime Apigee).

Le certificat CA racine est exposé dans la réponse de l'API organizations.get, dans le champ caCertificates[]. Le champ est un tableau, car lors d'une rotation, les certificats CA racine actuels et à venir sont renvoyés en même temps afin que les clients puissent faire confiance aux deux avant le basculement.

Pourquoi le certificat de l'autorité de certification racine est-il remplacé ?

Le certificat CA racine Apigee a une période de validité longue, mais finie (généralement 10 ans). Il est renouvelé avant son expiration pour que :

  • Le certificat qui sécurise l'environnement d'exécution Apigee n'expire jamais lorsqu'il est utilisé.
  • Les canaux de communication internes entre les composants Apigee continuent de fonctionner sans interruption.

La rotation est une opération de routine planifiée. Apigee l'exécute selon une programmation que Google Cloud contrôle. Vous n'initiez pas la rotation, et celle-ci ne modifie pas, en soi, le point de terminaison d'exécution Apigee ni la surface de l'API Apigee.

Étapes et calendrier de la rotation

Apigee fait pivoter le certificat CA racine en quatre étapes. Chaque étape est progressive : elle est appliquée région par région dans votre organisation et prend du temps. Le tableau ci-dessous décrit l'effet visible par le client de chaque étape et le moment typique où elle commence, mesuré par rapport à la date d'expiration de l'autorité de certification racine actuelle.

Étape Timing habituel Contenu de caCertificates[] Qu'est-ce qui change ?
1. Nouveau certificat publié Environ un an avant l'expiration du certificat actuel Actuel et nouveau (les deux) Apigee génère le nouveau certificat d'autorité de certification racine et l'ajoute au truststore de chaque composant appartenant à Apigee. Le nouveau certificat apparaît également dans la réponse organizations.get afin que vous puissiez le récupérer et le préparer. Le runtime Apigee continue de présenter un certificat de serveur signé par l'autorité de certification racine actuelle. Les clients existants ne sont donc pas encore affectés. Apigee envoie une notification au client lorsque cette étape commence.
2. Bascule du certificat d'entité finale Environ 60 jours avant l'expiration du certificat actuel Actuel et nouveau (les deux) L'exécution Apigee commence à présenter un nouveau certificat de serveur (feuille) signé par la nouvelle autorité de certification racine. Les clients qui ne font confiance qu'à l'autorité de certification racine actuelle échouent à la validation TLS une fois cette étape terminée dans leur région. Les clients qui font confiance aux deux certificats (ou uniquement au nouveau) continuent de fonctionner. Apigee envoie une notification au client lorsque cette étape commence.
3. Ancien certificat retiré Environ 30 jours avant l'expiration du certificat actuel Neufs uniquement Apigee supprime l'ancienne autorité de certification racine des magasins de confiance internes et cesse de la renvoyer à partir de organizations.get. Les clients qui ne font toujours confiance qu'à l'ancienne autorité de certification racine ne peuvent pas se connecter. Apigee envoie une notification au client lorsque cette étape commence.
4. Rotation terminée À la date d'expiration initiale Neufs uniquement Apigee supprime définitivement l'ancienne autorité de certification racine et la rotation est terminée. La nouvelle autorité de certification racine est désormais la seule autorité de certification racine, et un nouveau cycle d'environ 10 ans commence. Apigee envoie une notification au client lorsque cette étape est terminée.

Qui est concerné par une rotation ?

La nécessité d'une action de votre part lors d'une rotation dépend de la façon dont les clients accèdent à votre environnement d'exécution Apigee :

Modèle d'accès Action requise ? Pourquoi
Routage externe (MIG) avec un équilibreur de charge d'application externe Google Cloud Non Votre équilibreur de charge externe met fin à la connexion TLS à l'aide d'un certificat que vous gérez. Les clients font confiance à votre certificat, et non à l'AC racine Apigee. La rotation n'a aucun effet sur ces clients.
Routage interne (VPC), option TLS 1 (équilibreur de charge d'application HTTPS interne) Non Votre équilibreur de charge interne met fin au protocole TLS à l'aide d'un certificat que vous gérez. Les clients font confiance à votre certificat, et non à l'AC racine Apigee. La rotation n'a aucun effet sur ces clients.
Routage interne (VPC), option TLS 2 (nom de domaine complet interne par défaut) Oui Les clients se connectent directement à l'équilibreur de charge interne géré par Apigee et valident le certificat de serveur émis par Apigee. Chaque client doit faire confiance à la nouvelle autorité de certification racine avant la bascule de la rotation.
Connexion TCP directe à l'adresse IP d'entrée de l'instance d'exécution (par exemple, via un équilibreur de charge TCP interne) Oui Les clients valident le certificat de serveur émis par Apigee. Chaque client doit faire confiance à la nouvelle autorité de certification racine avant la bascule de la rotation.
Option non TLS (indicateur curl -k ou tout client qui ignore la validation du certificat) Non Le client ne valide pas le certificat du serveur. La rotation n'a donc aucun effet fonctionnel. Cette option n'est pas recommandée en dehors des environnements de test.

Se préparer à une rotation

Si vous utilisez l'un des modèles d'accès qui nécessitent une action, suivez ces étapes avant la date de bascule de la rotation que vous recevez dans votre notification de rotation.

Étape 1 : Découvrir les instances d'exécution Apigee

Répertoriez les instances d'exécution Apigee de votre organisation. Chaque instance dispose d'une adresse IP d'entrée dédiée, qui est l'hôte auquel les clients à connexion directe accèdent.

# 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 vos clients se connectent à un hôte autre que ces adresses IP (par exemple, votre propre nom DNS devant un équilibreur de charge interne), utilisez cet hôte à la place.

Étape 2 : Récupérez les certificats d'autorité de certification racine actuels et à venir

Lisez le champ caCertificates[] à partir de organizations.get. Lors d'une rotation, ce tableau contient à la fois l'autorité de certification racine actuelle et la nouvelle, chacune encodée en base64 :

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

Décodez chaque entrée au format PEM et vérifiez la période de validité pour identifier le nouveau certificat :

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

Le certificat dont la date notAfter est la plus récente est la nouvelle autorité de certification racine.

Étape 3 : Ajoutez la nouvelle CA racine à vos magasins de confiance

Ajoutez le nouveau certificat d'autorité de certification racine à chaque truststore client qui fait actuellement confiance à l'autorité de certification racine Apigee. Conservez l'autorité de certification racine actuelle jusqu'à la fin de la transition afin que les connexions continuent de fonctionner pendant la période de transition. Après la bascule, vous pouvez supprimer l'ancienne autorité de certification racine de vos truststores.

La procédure exacte dépend du client. Voici quelques cas courants :

  • Ajoutez le certificat au truststore au niveau de l'OS (par exemple, /etc/ssl/certs/ sur les systèmes basés sur Debian, suivi de update-ca-certificates).
  • Ajoutez le certificat à un truststore géré par l'application (par exemple, un keystore Java cacerts, un bundle Nginx ssl_trusted_certificate ou un bundle de confiance Envoy validation_context).
  • Ajoutez le certificat à un Secret ou un ConfigMap Kubernetes monté dans vos pods de charge de travail.

Étape 4 : Vérifiez que la connexion fonctionne avec la nouvelle CA racine

Après avoir préparé la nouvelle autorité de certification racine, vérifiez qu'une requête HTTPS envoyée à l'exécution Apigee aboutit lorsque vous n'accordez votre confiance qu'au nouveau certificat :

# 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 cette commande aboutit, votre client est prêt pour la bascule. Si elle échoue, cela signifie que le client n'approuve pas encore la nouvelle autorité de certification racine. Revenez à l'étape 3.

Exemple : Routage interne (VPC), option TLS 2

Cet exemple illustre les étapes de rotation pour le modèle d'accès documenté dans Routage interne (VPC), option TLS 2, où le client se connecte directement à l'équilibreur de charge interne Apigee et valide le certificat autosigné Apigee. Il s'agit du modèle d'accès le plus souvent affecté par une rotation.

Avant la bascule :

  1. Obtenez l'adresse IP de l'équilibreur de charge interne 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. Récupérez les CA racine actuelles et nouvelles dans des fichiers distincts, puis identifiez la nouvelle : 
    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. Créez un truststore combiné contenant l'autorité de certification racine actuelle et la nouvelle, puis utilisez-le pour votre demande de test : 
    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 cette requête aboutit, déployez cacert-combined.crt en tant que truststore client. Le truststore combiné continue de valider le certificat actuel aujourd'hui et validera le nouveau certificat après la transition.

Après la bascule (généralement quelques jours après la date de bascule), confirmez la rotation en vérifiant que la connexion fonctionne toujours lorsque vous n'accordez votre confiance qu'au nouveau certificat :

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 cette requête aboutit, vous pouvez supprimer l'ancienne autorité de certification racine de votre magasin de clés sécurisé.

Notifications

Apigee envoie une notification aux propriétaires du projet Google Cloud et de l'organisation au début de chaque étape de rotation. Chaque notification inclut le nom de la phase, la date à laquelle elle sera appliquée à votre organisation et un lien vers cette page.

Notification Action recommandée pour le client
1. Nouveau certificat publié
(environ un an avant l'expiration)		 Récupérez la nouvelle autorité de certification racine à partir de caCertificates[] et ajoutez-la à chaque truststore client qui fait actuellement confiance à l'autorité de certification racine Apigee. Consultez Comment se préparer à une rotation.
2. Bascule du certificat d'entité finale
(~60 jours avant l'expiration)		 Avant que cette étape ne soit appliquée à votre région, assurez-vous que tous vos clients font confiance à la nouvelle autorité de certification racine. Après cette étape, les clients qui ne font confiance qu'à l'ancienne autorité de certification racine ne pourront plus se connecter.
3. Ancien certificat retiré
(environ 30 jours avant l'expiration)		 Une fois cette étape appliquée à toutes vos régions, vous pouvez supprimer en toute sécurité l'ancienne autorité de certification racine de vos magasins de confiance client.
4. Rotation terminée
(à la date d'expiration initiale)		 Aucune action n'est requise. L'ancienne autorité de certification racine a été définitivement supprimée, et la nouvelle est la seule autorité de certification racine pour votre organisation.

Si vous ne recevez pas de notifications de rotation et que vous utilisez l'un des modèles d'accès listés dans Qui est concerné par une rotation ?, contactez l'assistance Apigee pour confirmer les destinataires des notifications pour votre organisation.

Étapes suivantes