Apigee-Root-CA-Zertifikat und ‑Rotation

Diese Seite gilt für Apigee, aber nicht für Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird das Apigee-Root-Zertifizierungsstellenzertifikat beschrieben, mit dem TLS-Verbindungen zur Apigee-Laufzeit geschützt werden. Außerdem wird der Rotationsprozess erläutert. Außerdem werden die Zugriffsmuster, die von einer Rotation betroffen sind, und die Schritte aufgeführt, die Sie zur Vorbereitung Ihrer Anwendungen ausführen sollten.

Root-CA-Zertifikat

Jede Apigee-Organisation hat ein von Google verwaltetes Root-CA-Zertifikat, mit dem das vom Apigee-Laufzeit-Ingress für die TLS-Terminierung verwendete Serverzertifikat ausgestellt wird. Wenn ein Client eine HTTPS-Verbindung zu einer Apigee-Instanz öffnet, präsentiert der Server ein Zertifikat, das mit dieser Root-Zertifizierungsstelle verkettet ist. Clients, die das Serverzertifikat validieren, müssen der Stammzertifizierungsstelle vertrauen, entweder implizit (wenn der Traffic über einen vom Kunden verwalteten Load Balancer geleitet wird, der TLS beendet) oder explizit (wenn der Client direkt eine Verbindung zur Apigee-Laufzeit herstellt).

Das Stamm-CA-Zertifikat wird in der API-Antwort organizations.get im Feld caCertificates[] bereitgestellt. Das Feld ist ein Array, da bei einer Rotation sowohl das aktuelle als auch das nächste Stamm-CA-Zertifikat gleichzeitig zurückgegeben werden, damit Clients beiden vor der Umstellung vertrauen können.

Warum das Root-CA-Zertifikat rotiert wird

Das Apigee-Stamm-CA-Zertifikat hat eine lange, aber endliche Gültigkeitsdauer (in der Regel 10 Jahre). Sie wird vor Ablauf so rotiert, dass:

  • Das Zertifikat, mit dem die Apigee-Laufzeit geschützt wird, läuft während der Verwendung nie ab.
  • Die internen Kommunikationskanäle zwischen Apigee-Komponenten funktionieren weiterhin ohne Unterbrechung.

Die Rotation ist ein routinemäßiger, geplanter Vorgang. Apigee führt sie nach einem Zeitplan aus, der von Google Cloud gesteuert wird. Sie leiten die Rotation nicht ein und die Rotation ändert nicht den Apigee-Laufzeitendpunkt oder die Apigee API-Oberfläche.

Rotationsphasen und Zeitachse

Apigee rotiert das Root-CA-Zertifikat in vier Phasen. Jede Phase wird schrittweise angewendet, d. h. regionenweise in Ihrer Organisation, und es dauert eine Weile, bis sie abgeschlossen ist. In der Tabelle unten wird die für Kunden sichtbare Wirkung der einzelnen Phasen und der typische Zeitpunkt beschrieben, zu dem sie beginnt. Dieser wird relativ zum Ablaufdatum der aktuellen Root-Zertifizierungsstelle gemessen.

Phase Typisches Timing Inhalte von caCertificates[] Was passiert dann?
1. Neues Zertifikat veröffentlicht Etwa ein Jahr vor Ablauf des aktuellen Zertifikats Aktuell und neu (beide) Apigee generiert das neue Stamm-CA-Zertifikat und fügt es dem Truststore jeder Apigee-Komponente hinzu. Das neue Zertifikat wird auch in der Antwort organizations.get angezeigt, damit Sie es abrufen und bereitstellen können. In der Apigee-Laufzeit wird weiterhin ein von der aktuellen Stammzertifizierungsstelle signiertes Serverzertifikat präsentiert, sodass bestehende Clients noch nicht betroffen sind. Apigee sendet eine Kundenbenachrichtigung, wenn diese Phase beginnt.
2. Umstellung auf untergeordnetes Zertifikat Etwa 60 Tage vor Ablauf des aktuellen Zertifikats Aktuell und neu (beide) Die Apigee-Laufzeit beginnt mit der Präsentation eines neuen Serverzertifikats (untergeordnetes Zertifikat), das von der neuen Stammzertifizierungsstelle signiert ist. Clients, die nur der aktuellen Root-Zertifizierungsstelle vertrauen, bestehen die TLS-Validierung nicht, nachdem diese Phase in ihrer Region abgeschlossen ist. Clients, die beiden Zertifikaten (oder nur dem neuen) vertrauen, funktionieren weiterhin. Apigee sendet eine Kundenbenachrichtigung, wenn diese Phase beginnt.
3. Altes Zertifikat widerrufen Etwa 30 Tage vor Ablauf des aktuellen Zertifikats Nur neue Apigee entfernt die alte Stamm-CA aus internen Truststores und gibt sie nicht mehr über organizations.get zurück. Clients, die nur der alten Stamm-CA vertrauen, können keine Verbindung herstellen. Apigee sendet eine Kundenbenachrichtigung, wenn diese Phase beginnt.
4. Rotation abgeschlossen Am ursprünglichen Ablaufdatum Nur neue Apigee löscht die alte Stammzertifizierungsstelle endgültig und die Rotation ist abgeschlossen. Die neue Root-Zertifizierungsstelle ist jetzt die einzige Root-Zertifizierungsstelle und ein neuer Zyklus von etwa 10 Jahren beginnt. Apigee sendet eine Kundenbenachrichtigung, wenn diese Phase abgeschlossen ist.

Wer ist von einer Rotation betroffen?

Ob eine Rotation eine Aktion von Ihnen erfordert, hängt davon ab, wie Clients Ihre Apigee-Laufzeit erreichen:

Zugriffsmuster Ist eine Aktion erforderlich? Warum
Externes Routing (MIG) mit einem externen Google Cloud Application Load Balancer Nein Ihr externer Load Balancer beendet TLS mit einem Zertifikat, das Sie verwalten. Clients vertrauen Ihrem Zertifikat, nicht der Apigee-Stammzertifizierungsstelle. Die Rotation hat keine Auswirkungen auf diese Clients.
Internes Routing (VPC), TLS-Option 1 (interner HTTPS-Application Load Balancer) Nein Ihr interner Load Balancer beendet TLS mit einem Zertifikat, das Sie verwalten. Clients vertrauen Ihrem Zertifikat, nicht der Apigee-Stammzertifizierungsstelle. Die Rotation hat keine Auswirkungen auf diese Clients.
Internes Routing (VPC), TLS-Option 2 (interner standardmäßiger vollqualifizierter Domainname) Ja Clients stellen eine direkte Verbindung zum von Apigee verwalteten internen Load-Balancer her und validieren das von Apigee ausgestellte Serverzertifikat. Jeder Client muss der neuen Stamm-CA vor der Umstellung der Rotation vertrauen.
Direkte TCP-Verbindung zur Ingress-IP der Laufzeitinstanz (z. B. über einen internen TCP-Load-Balancer) Ja Clients validieren das von Apigee ausgestellte Serverzertifikat. Jeder Client muss der neuen Stamm-CA vor der Umstellung der Rotation vertrauen.
Nicht-TLS-Option (das Flag curl -k oder ein beliebiger Client, der die Zertifikatsvalidierung überspringt) Nein Der Client validiert das Serverzertifikat nicht, daher hat die Rotation keine funktionale Wirkung. Diese Option wird außerhalb von Testumgebungen nicht empfohlen.

Vorbereitung auf eine Rotation

Wenn Sie eines der Zugriffsmuster verwenden, für das eine Aktion erforderlich ist, führen Sie die folgenden Schritte vor dem Rotationsumstellungsdatum aus, das Sie in Ihrer Rotationsbenachrichtigung erhalten.

Schritt 1: Apigee-Laufzeitinstanzen ermitteln

Listen Sie die Apigee-Laufzeitinstanzen in Ihrer Organisation auf. Jede Instanz hat eine dedizierte Ingress-IP-Adresse, über die Clients mit direkter Verbindung den Host erreichen.

# 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)"'

Wenn Ihre Clients eine Verbindung zu einem anderen Host als diesen IP-Adressen herstellen (z. B. Ihr eigener DNS-Name vor einem internen Load Balancer), verwenden Sie diesen Host stattdessen.

Schritt 2: Aktuelle und zukünftige Stamm-CA-Zertifikate abrufen

Lesen Sie das Feld caCertificates[] aus organizations.get. Während einer Rotation enthält dieses Array sowohl die aktuelle als auch die neue Stammzertifizierungsstelle, jeweils Base64-codiert:

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

Decodieren Sie jeden Eintrag in das PEM-Format und prüfen Sie den Gültigkeitszeitraum, um das neue Zertifikat zu ermitteln:

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

Das Zertifikat mit dem späteren Datum notAfter ist die neue Stammzertifizierungsstelle.

Schritt 3: Neue Stammzertifizierungsstelle zu Ihren Truststores hinzufügen

Fügen Sie das neue Root-CA-Zertifikat jedem Client-Truststore hinzu, der derzeit der Apigee-Root-CA vertraut. Lassen Sie die aktuelle Stammzertifizierungsstelle bis zum Abschluss der Umstellung an ihrem Platz, damit Verbindungen während des Umstellungszeitraums weiterhin funktionieren. Nach der Umstellung können Sie die alte Stammzertifizierungsstelle aus Ihren Truststores entfernen.

Die genaue Vorgehensweise hängt vom Client ab. Häufige Fälle:

  • Fügen Sie das Zertifikat dem Truststore auf Betriebssystemebene hinzu (z. B. /etc/ssl/certs/ auf Debian-basierten Systemen, gefolgt von update-ca-certificates).
  • Das Zertifikat wird einem von der Anwendung verwalteten Truststore hinzugefügt, z. B. einem Java-cacerts-Schlüsselspeicher, einem Nginx-ssl_trusted_certificate-Bundle oder einem Envoy-validation_context-Trust-Bundle.
  • Fügen Sie das Zertifikat einem Kubernetes-Secret oder ConfigMap hinzu, das in Ihre Arbeitslast-Pods eingebunden ist.

Schritt 4: Prüfen, ob die Verbindung mit der neuen Stammzertifizierungsstelle funktioniert

Nachdem Sie die neue Root-CA bereitgestellt haben, prüfen Sie, ob eine HTTPS-Anfrage an die Apigee-Laufzeit erfolgreich ist, wenn Sie nur dem neuen Zertifikat vertrauen:

# 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

Wenn dieser Befehl erfolgreich ausgeführt wird, ist Ihr Client für die Umstellung bereit. Wenn der Test fehlschlägt, vertraut der Client der neuen Stamm-CA noch nicht. Wiederholen Sie Schritt 3.

Beispiel: Internes Routing (VPC), TLS-Option 2

In diesem Beispiel werden die Rotationsschritte für das Zugriffsmuster Internes Routing (VPC), TLS-Option 2, beschrieben. Dabei stellt der Client eine direkte Verbindung zum internen Apigee-Load-Balancer her und validiert das selbst signierte Apigee-Zertifikat. Dieses Zugriffsmuster ist am häufigsten von einer Rotation betroffen.

Vor der Umstellung:

  1. Rufen Sie die IP-Adresse des internen Apigee-Load-Balancers ab: 
    export INTERNAL_LOAD_BALANCER_IP=$(curl -H "$AUTH" \
  https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/instances -s \
  | jq -r '.instances[0].host')
  2. Rufen Sie die aktuellen und neuen Stammzertifizierungsstellen in separaten Dateien ab und identifizieren Sie die neue: 
    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. Erstellen Sie einen kombinierten Truststore, der sowohl die aktuelle als auch die neue Root-Zertifizierungsstelle enthält, und verwenden Sie ihn für Ihre Testanfrage: 
    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

    Wenn diese Anfrage erfolgreich ist, stellen Sie cacert-combined.crt als Client-Truststore bereit. Der kombinierte Truststore validiert weiterhin das aktuelle Zertifikat und nach der Umstellung das neue Zertifikat.

Bestätigen Sie nach der Umstellung (in der Regel innerhalb weniger Tage nach dem Umstellungsdatum) die Rotation, indem Sie prüfen, ob die Verbindung weiterhin erfolgreich ist, wenn Sie nur dem neuen Zertifikat vertrauen:

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

Wenn diese Anfrage erfolgreich ist, können Sie die alte Stammzertifizierungsstelle sicher aus Ihrem Truststore entfernen.

Benachrichtigungen

Apigee sendet zu Beginn jeder Rotationsphase eine Benachrichtigung an die Projektinhaber und Organisationsinhaber Ihres Google Cloud Projekts. Jede Benachrichtigung enthält den Namen der Phase, das Datum, an dem die Phase auf Ihre Organisation angewendet wird, und einen Link zu dieser Seite.

Benachrichtigung Empfohlene Kundenaktion
1. Neues Zertifikat veröffentlicht
(ca. 1 Jahr vor Ablauf)		 Rufen Sie die neue Root-CA von caCertificates[] ab und fügen Sie sie jedem Client-Truststore hinzu, der derzeit der Apigee-Root-CA vertraut. Informationen zur Vorbereitung auf eine Rotation
2. Umstellung auf untergeordnetes Zertifikat
(ca. 60 Tage vor Ablauf)		 Bestätigen Sie, dass alle Ihre Clients der neuen Root-CA vertrauen, bevor diese Phase auf Ihre Region angewendet wird. Danach können Clients, die nur der alten Stamm-CA vertrauen, keine Verbindung mehr herstellen.
3. Altes Zertifikat widerrufen
(ca. 30 Tage vor Ablauf)		 Sobald diese Phase auf alle Ihre Regionen angewendet wurde, können Sie die alte Stammzertifizierungsstelle gefahrlos aus Ihren Client-Truststores entfernen.
4. Rotation abgeschlossen
(am ursprünglichen Ablaufdatum)		 Es sind keine weiteren Schritte erforderlich. Die alte Stammzertifizierungsstelle wurde dauerhaft gelöscht und die neue Stammzertifizierungsstelle ist die einzige Stammzertifizierungsstelle für Ihre Organisation.

Wenn Sie keine Benachrichtigungen zur Rotation erhalten und eines der in Wer ist von einer Rotation betroffen? aufgeführten Zugriffsmuster verwenden, wenden Sie sich an den Apigee-Support, um die Benachrichtigungsempfänger für Ihre Organisation zu bestätigen.

Nächste Schritte