Usa il tuo certificato ACM per il TLS reciproco di backend in API Gateway

Puoi configurare API Gateway per presentare il tuo CA-signed certificato ai servizi di backend. Importa il tuo certificato in AWS Certificate Manager (ACM) o emettine uno tramite. Autorità di certificazione privata AWS Quindi, collega il certificato ACM ARN alla tua fase API.

Prerequisiti

Prima di configurare un certificato client ACM, devi disporre di quanto segue:

• AWS Certificate Manager accesso nella stessa regione della tua API.

• Autorizzazioni IAM: acm:ImportCertificate e acm:DescribeCertificate (per l'importazione dell'opzione A), o acm:RequestCertificate (per l'opzione B), o acm-pca:IssueCertificateacm-pca:GetCertificate, e acm:ImportCertificate (per l'opzione C).

• Un'API REST implementata in una fase.

Fase 1: Importa un certificato o emettine uno tramite Autorità di certificazione privata AWS

Puoi importare un certificato dalla tua PKI esistente o emettere un nuovo certificato tramite Autorità di certificazione privata AWS. Entrambi i percorsi producono un certificato ACM ARN da utilizzare nel passaggio successivo.

Nota

I certificati pubblici ACM non sono supportati per l'autenticazione del client backend. A partire dall'11 giugno 2025, AWS Certificate Manager non emette più certificati pubblici con l'uso clientAuth esteso delle chiavi (EKU). Questa funzionalità richiede l'EKU, quindi utilizza un certificato che importi in ACM o uno emesso tramite. Autorità di certificazione privata AWS

Nota

Crea il certificato ACM nella stessa AWS regione dell'API REST che lo utilizzerà. I certificati ACM sono risorse regionali, quindi il certificato deve esistere nella regione dell'API.

Opzione A: importazione dalla tua PKI esistente

Per importare un certificato client e la relativa chiave privata in ACM, esegui il comando seguente. Per ulteriori informazioni, consulta Importazione di certificati nella Guida per l'utente di AWS Certificate Manager .

aws acm import-certificate \
  --certificate fileb://client-cert.pem \
  --private-key fileb://private-key.pem \
  --certificate-chain fileb://ca-chain.pem \
  --region region

Il comando restituisce il certificato ACM ARN. Registrate questo valore per il passaggio successivo.

Opzione B: richiedi un certificato tramite Autorità di certificazione privata AWS (ACM-managed)

Per richiedere un certificato privato che ACM gestisce e può rinnovare automaticamente, esegui il seguente comando. Per ulteriori informazioni, consulta Richiesta di un certificato privato nella Guida per l'utente. AWS Certificate Manager

aws acm request-certificate \
  --domain-name www.example.com \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --region region

Il comando restituisce il certificato ACM ARN. Registrate questo valore per il passaggio successivo.

Opzione C: emissione tramite Autorità di certificazione privata AWS e importazione in ACM

Se hai bisogno di un controllo diretto sui parametri del certificato (come estensioni personalizzate o algoritmi di firma), puoi emettere un certificato tramite ACM Autorità di certificazione privata AWS e poi importarlo in ACM. I certificati importati in questo modo non vengono rinnovati automaticamente da ACM. Assicurati che il certificato soddisfi i requisiti del certificato. Per ulteriori informazioni sull'emissione di certificati privati, vedere Emissione di un certificato di entità finale privata nella Guida per l'utente. Autorità di certificazione privata AWS

aws acm-pca issue-certificate \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --csr fileb://csr.pem \
  --signing-algorithm SHA256WITHRSA \
  --validity Value=365,Type=DAYS

Recupera e importa il certificato

Il issue-certificate comando restituisce un Autorità di certificazione privata AWS certificato ARN, non un ARN ACM. Per utilizzare questo certificato con API Gateway, recuperalo utilizzando aws acm-pca get-certificate e quindi importalo in ACM using. aws acm import-certificate L'importazione produce il certificato ACM ARN che utilizzerai nel passaggio successivo. Quando eseguiaws acm import-certificate, imposta --region la regione dell'API in modo che il certificato ACM venga creato lì.

Passaggio 2: configura una fase API per utilizzare il certificato ACM

Dopo aver ottenuto un certificato ACM ARN, configura la fase API per presentare il certificato al tuo backend.

Per configurare una fase (console)

1. Apri la console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Scegli la tua API REST.

3. Scegliere Stages (Fasi).

4. Nella sezione Dettagli fase scegli Modifica.

5. Per il certificato client, seleziona il tuo certificato ACM dall'elenco a discesa.

6. Scegli Save changes (Salva modifiche).

Per configurare una fase (AWS CLI)

Esegui il comando seguente:

aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations op='replace',path=/clientCertificateId,value=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012

Nota

API Gateway utilizza lo stesso clientCertificateId campo per i Gateway-generated certificati ACM e API. Quando fornisci un certificato ACM ARN, API Gateway rileva automaticamente il formato e utilizza il flusso di lavoro. ACM-managed

Fase 3: Verifica la configurazione

Per verificare che API Gateway invii il certificato al tuo backend, completa i seguenti passaggi:

Il backend deve richiedere un certificato client

Il backend deve essere configurato per richiedere un certificato client durante l'handshake TLS. Se il backend non ne richiede uno, API Gateway non presenta il certificato.

1. Richiama il tuo endpoint API.

2. Verifica che il tuo backend riceva il certificato client durante l'handshake TLS.

3. Verifica che il tuo backend accetti il certificato e restituisca una risposta positiva.

Se il backend rifiuta il certificato, verifica che la catena di certificati possa essere convalidata rispetto al trust store del backend.

Requisiti del certificato

Il certificato leaf che configuri deve soddisfare i seguenti requisiti.

Requisiti del certificato client ACM

Requisito	Description
Lunghezza massima della catena	5 certificati
Validity	Il certificato non deve essere scaduto o essere ancora valido al momento della configurazione
Region	Il certificato ACM deve trovarsi nella stessa regione dell'API
Account	Il certificato ACM deve trovarsi nello stesso account dell'API
Utilizzo esteso delle chiavi (EKU)	Se presente, deve includereclientAuth. Se assente, il certificato è accettato.
Utilizzo delle chiavi (KU)	Se presente, deve includere digitalSignature okeyAgreement. Se assente, il certificato è accettato.
Algoritmo chiave	Deve essere uno tra: RSA 2048, RSA 3072, RSA 4096, ECDSA (EC_Prime256v1), ECDSA (EC_SECP384R1) o ECDSA P-256 (EC_SECP521R1) P-384 P-521
Stato del certificato ACM	Deve essere ISSUED

Nota

API Gateway non convalida la catena di fiducia tra i certificati leaf e intermedi. Inoltre, API Gateway non convalida l'intento del certificato o i vincoli di base (ad esempio) sui certificati intermedi. CA:TRUE Il tuo backend esegue queste convalide durante l'handshake TLS.

Rinnovo e propagazione del certificato

Quando un certificato viene modificato in ACM, API Gateway rileva l'aggiornamento e propaga automaticamente il nuovo certificato. Non è necessario ridistribuire lo stage e l'API non subisce tempi di inattività durante la rotazione.

La propagazione dei certificati alla fine è coerente. Durante l'aggiornamento, il backend potrebbe ricevere il vecchio o il nuovo certificato fino al completamento della propagazione.

La modalità di rinnovo del certificato dipende da come è stato emesso:

• Certificati emessi tramite Autorità di certificazione privata AWS (ACM-managed) (Opzione B): ACM rinnova automaticamente questi certificati. API Gateway rileva il rinnovo e si aggiorna automaticamente.

• Certificati emessi Autorità di certificazione privata AWS e importati (opzione C): ACM non rinnova automaticamente i certificati importati. È necessario reimportare il certificato rinnovato. Dopo aver reimportato il certificato, API Gateway rileva la modifica e si aggiorna automaticamente.

• Certificati importati dalla tua PKI (opzione A): devi reimportare il certificato rinnovato in ACM. Dopo aver reimportato il certificato, API Gateway rileva la modifica e si aggiorna automaticamente.

ACM invia notifiche di scadenza del certificato tramite Amazon. EventBridge Puoi utilizzare queste notifiche per impostare allarmi prima della scadenza di un certificato.

Comportamento e limitazioni del certificato ACM

Visualizzazione del certificato configurato

I certificati ACM non vengono visualizzati nelle risposte GetClientCertificate o GetClientCertificates API. Per visualizzare il certificato ACM ARN configurato su una fase, usa. GetStage Per visualizzare i dettagli del certificato, utilizza le API ACM e. DescribeCertificate GetCertificate

Riutilizzo in più fasi

È possibile allegare lo stesso certificato ACM a più fasi. Ogni fase fa riferimento in modo indipendente al certificato tramite il relativo ARN.

Le API dei certificati client non si applicano ai certificati ACM

I certificati ACM non sono risorse API. Gateway-managed Le DeleteClientCertificate API GetClientCertificateUpdateClientCertificate, e restituiscono a NotFoundException quando vengono chiamate con un certificato ACM ARN. Utilizza le API ACM per gestire il ciclo di vita del certificato.

Pulizia automatica delle associazioni di certificati

Quando rimuovi un certificato ACM da una fase, aggiorni una fase per utilizzare un certificato diverso o elimini una fase o un'API REST, API Gateway pulisce automaticamente l'associazione dei certificati. Non è richiesta alcuna azione manuale.

Eliminazione del certificato ACM

ACM non consente di eliminare un certificato mentre API Gateway ha un'associazione attiva con esso. Per eliminare il certificato da ACM, rimuovilo innanzitutto da tutte le fasi che lo fanno riferimento.