Informazioni sulla rotazione e sul certificato CA radice Apigee

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive il certificato dell'autorità di certificazione (CA) radice di Apigee che protegge le connessioni TLS al runtime Apigee e spiega la procedura di rotazione. Vengono inoltre elencati i pattern di accesso interessati da una rotazione e i passaggi da seguire per preparare le applicazioni.

Informazioni sul certificato CA radice

Ogni organizzazione Apigee ha un certificato CA radice gestito da Google che emette il certificato del server utilizzato dall'ingresso del runtime Apigee per la terminazione TLS. Quando un client apre una connessione HTTPS a un'istanza Apigee, il server presenta un certificato concatenato a questa CA radice. I client che convalidano il certificato del server devono considerare attendibile la CA radice, in modo implicito (quando il traffico passa attraverso un bilanciatore del carico gestito dal cliente che termina TLS) o esplicito (quando il client si connette direttamente al runtime Apigee).

Il certificato CA radice è esposto nella risposta dell'API organizations.get nel campo caCertificates[]. Il campo è un array perché, durante una rotazione, vengono restituiti contemporaneamente sia i certificati CA radice attuali sia quelli futuri, in modo che i client possano considerare attendibili entrambi prima del cutover.

Perché il certificato CA radice viene ruotato

Il certificato CA radice di Apigee ha un periodo di validità lungo ma finito (in genere 10 anni). Viene ruotato prima della scadenza in modo che:

  • Il certificato che protegge il runtime Apigee non scade mai durante l'utilizzo.
  • I canali di comunicazione interni tra i componenti Apigee continuano a funzionare senza interruzioni.

La rotazione è un'operazione di routine pianificata. Apigee lo esegue in base a una pianificazione che Google Cloud controlla. Non avvii la rotazione e la rotazione non modifica di per sé l'endpoint runtime di Apigee o la superficie API Apigee.

Fasi di rotazione e tempistiche

Apigee ruota il certificato CA radice in quattro fasi. Ogni fase è graduale: viene applicata regione per regione all'interno dell'organizzazione e richiede tempo per essere completata. La tabella seguente descrive l'effetto visibile ai clienti di ogni fase e il momento tipico in cui inizia, misurato rispetto alla data di scadenza dell'attuale CA radice.

Fase Tempistiche tipiche Che cosa contiene caCertificates[] Che cosa succede
1. Nuovo certificato pubblicato Circa un anno prima della scadenza del certificato attuale Corrente e nuovo (entrambi) Apigee genera il nuovo certificato CA radice e lo aggiunge al truststore di ogni componente di proprietà di Apigee. Il nuovo certificato viene visualizzato anche nella risposta organizations.get, in modo che tu possa recuperarlo e prepararlo. Il runtime di Apigee continua a presentare un certificato del server firmato dalla CA radice corrente, quindi i client esistenti non sono ancora interessati. Apigee invia una notifica al cliente all'inizio di questa fase.
2. Transizione al certificato end-entity Circa 60 giorni prima della scadenza del certificato attuale Corrente e nuovo (entrambi) Il runtime Apigee inizia a presentare un nuovo certificato del server (foglia) firmato dalla nuova CA radice. I client che considerano attendibile solo la CA radice attuale non superano la convalida TLS dopo il completamento di questa fase nella loro regione. I client che considerano attendibili entrambi i certificati (o solo quello nuovo) continuano a funzionare. Apigee invia una notifica al cliente all'inizio di questa fase.
3. Certificato precedente ritirato Circa 30 giorni prima della scadenza del certificato attuale Solo nuovi Apigee rimuove la vecchia CA radice dagli store attendibili interni e smette di restituirla da organizations.get. I client che considerano attendibile solo la vecchia CA radice non possono connettersi. Apigee invia una notifica al cliente all'inizio di questa fase.
4. Rotazione completata Alla data di scadenza originale Solo nuovi Apigee elimina definitivamente la vecchia CA radice e la rotazione è terminata. La nuova CA principale è ora l'unica CA principale e inizia un nuovo ciclo di circa 10 anni. Apigee invia una notifica al cliente al termine di questa fase.

Chi è interessato da una rotazione

Se una rotazione richiede un intervento da parte tua dipende da come i client raggiungono il runtime Apigee:

Pattern di accesso Azione richiesta? Perché
Routing esterno (MIG) con un bilanciatore del carico delle applicazioni esterno Google Cloud No Il bilanciatore del carico esterno termina TLS utilizzando un certificato che gestisci. I client si fidano del tuo certificato, non della CA radice di Apigee. La rotazione non ha alcun effetto su questi client.
Routing interno (VPC), opzione TLS 1 (bilanciatore del carico delle applicazioni HTTPS interno) No Il bilanciatore del carico interno termina TLS utilizzando un certificato che gestisci. I client si fidano del tuo certificato, non della CA radice di Apigee. La rotazione non ha alcun effetto su questi client.
Routing interno (VPC), opzione TLS 2 (nome di dominio completo predefinito interno) Sì I client si connettono direttamente al bilanciatore del carico interno gestito da Apigee e convalidano il certificato del server emesso da Apigee. Ogni client deve considerare attendibile la nuova CA radice prima del cutover della rotazione.
Connessione TCP diretta all'IP di ingresso dell'istanza di runtime (ad esempio tramite un bilanciatore del carico TCP interno) Sì I client convalidano il certificato server emesso da Apigee. Ogni client deve considerare attendibile la nuova CA radice prima del cutover della rotazione.
Opzione non TLS (il flag curl -k o qualsiasi client che ignora la convalida del certificato) No Il client non convalida il certificato del server, quindi la rotazione non ha alcun effetto funzionale. Questa opzione non è consigliata al di fuori degli ambienti di test.

Come prepararsi a una rotazione

Se utilizzi uno dei pattern di accesso che richiedono un'azione, segui questi passaggi prima della data di cutover della rotazione che ricevi nella notifica di rotazione.

Passaggio 1: scopri le istanze del runtime Apigee

Elenca le istanze di runtime Apigee nella tua organizzazione. Ogni istanza ha un IP in entrata dedicato, ovvero l'host a cui si connettono i client direct-connect.

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

Se i tuoi client si connettono a un host diverso da questi IP (ad esempio, il tuo nome DNS davanti a un bilanciatore del carico interno), utilizza quell'host invece.

Passaggio 2: recupera i certificati CA radice attuali e futuri

Leggi il campo caCertificates[] da organizations.get. Durante una rotazione, questo array contiene sia la CA radice attuale che quella nuova, ciascuna codificata in base64:

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

Decodifica ogni voce in formato PEM e controlla il periodo di validità per identificare il nuovo certificato:

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

Il certificato con la data notAfter successiva è la nuova CA radice.

Passaggio 3: aggiungi la nuova CA principale ai truststore

Aggiungi il nuovo certificato CA radice a ogni truststore client che attualmente considera attendibile la CA radice Apigee. Mantieni l'attuale CA radice fino al completamento del trasferimento, in modo che le connessioni continuino a funzionare durante la finestra di trasferimento. Dopo il cutover, puoi rimuovere la vecchia CA radice dai truststore.

La procedura esatta dipende dal client. I casi più comuni includono:

  • Aggiunta del certificato all'archivio attendibile a livello di sistema operativo (ad esempio, /etc/ssl/certs/ su sistemi basati su Debian seguito da update-ca-certificates).
  • Aggiunta del certificato a un truststore gestito dall'applicazione (ad esempio, un keystore Java cacerts, un bundle Nginx ssl_trusted_certificate o un bundle di attendibilità Envoy validation_context).
  • Aggiunta del certificato a un Secret o a un ConfigMap montato nei pod dei carichi di lavoro.

Passaggio 4: verifica che la connessione funzioni con la nuova CA principale

Dopo aver eseguito lo staging della nuova CA radice, verifica che una richiesta HTTPS al runtime Apigee vada a buon fine quando consideri attendibile solo il nuovo certificato:

# 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

Se questo comando ha esito positivo, il client è pronto per il cutover. Se non riesce, il client non considera ancora attendibile la nuova CA radice. Ritorna al passaggio 3.

Esempio: routing interno (VPC), opzione TLS 2

Questo esempio mostra i passaggi di rotazione per il pattern di accesso documentato in Routing interno (VPC), opzione TLS 2, in cui il client si connette direttamente al bilanciatore del carico interno di Apigee e convalida il certificato autofirmato di Apigee. Questo è il pattern di accesso più comunemente interessato da una rotazione.

Prima del cutover:

  1. Ottieni l'IP del bilanciatore del carico interno di 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 le CA radice attuali e nuove in file separati e identifica quella nuova: 
    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 truststore combinato che contenga sia la CA radice attuale sia quella nuova e utilizzalo per la richiesta di 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

    Se questa richiesta ha esito positivo, implementa cacert-combined.crt come truststore client. Il truststore combinato continua a convalidare il certificato attuale oggi e convaliderà il nuovo certificato dopo il cutover.

Dopo il cutover (in genere entro pochi giorni dalla data del cutover), conferma la rotazione verificando che la connessione funzioni ancora quando consideri attendibile solo il nuovo certificato:

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

Quando questa richiesta va a buon fine, puoi rimuovere in tutta sicurezza la vecchia CA radice dal tuo truststore.

Notifiche

Apigee invia una notifica ai proprietari del progetto e dell'organizzazione del tuo Google Cloud progetto all'inizio di ogni fase di rotazione. Ogni notifica include il nome della fase, la data in cui la fase verrà applicata alla tua organizzazione e un link a questa pagina.

Notifica Azione consigliata per il cliente
1. Nuovo certificato pubblicato
(circa 1 anno prima della scadenza)		 Recupera la nuova CA radice da caCertificates[] e aggiungila a ogni truststore client che attualmente considera attendibile la CA radice Apigee. Consulta Come prepararsi a una rotazione.
2. Transizione al certificato end-entity
(~60 giorni prima della scadenza)		 Prima che questa fase venga applicata alla tua regione, verifica che tutti i tuoi client considerino attendibile la nuova CA radice. Dopo questa fase, i client che considerano attendibile solo la vecchia CA radice non possono connettersi.
3. Ritiro del vecchio certificato
(~30 giorni prima della scadenza)		 Una volta applicata questa fase a tutte le tue regioni, puoi rimuovere in sicurezza la vecchia CA radice dai truststore client.
4. Rotazione completata
(alla data di scadenza originale)		 Non occorre alcun intervento. La vecchia CA principale è stata eliminata definitivamente e la nuova CA principale è l'unica CA principale per la tua organizzazione.

Se non ricevi notifiche di rotazione e utilizzi uno dei pattern di accesso elencati in Chi è interessato da una rotazione, contatta l'assistenza Apigee per confermare i destinatari delle notifiche per la tua organizzazione.

Passaggi successivi