Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Come attivare l'TLSautenticazione reciproca per il tuo REST APIs in API Gateway
TLSL'autenticazione reciproca richiede l'autenticazione bidirezionale tra il client e il server. Con MutualTLS, i client devono presentare certificati X.509 per verificare la propria identità e accedere al API Mutual TLS è un requisito comune per l'Internet of Things (IoT) e business-to-business le applicazioni.
È possibile utilizzare Mutual TLS insieme ad altre operazioni di autorizzazione e autenticazione supportate da API Gateway. APIGateway inoltra i certificati forniti dai client agli autorizzatori Lambda e alle integrazioni di backend.
Importante
Per impostazione predefinita, i client possono richiamarti API utilizzando l'execute-api
endpoint che Gateway genera per te. API API Per garantire che i clienti possano accedere al tuo API solo utilizzando un nome di dominio personalizzato con mutuoTLS, disabilita l'endpoint predefinitoexecute-api
. Per ulteriori informazioni, consulta Disabilita l'endpoint predefinito per le API REST.
Argomenti
Prerequisiti per la mutua TLS
Per configurare mutuo TLS è necessario:
Un nome di dominio personalizzato regionale
Almeno un certificato configurato AWS Certificate Manager per il tuo nome di dominio personalizzato
Un truststore configurato e caricato in Amazon S3
Nomi di dominio personalizzati
Per abilitare TLS il mutuo per a RESTAPI, devi configurare un nome di dominio personalizzato per il tuoAPI. È possibile abilitare Mutual TLS per un nome di dominio personalizzato e quindi fornire il nome di dominio personalizzato ai client. Per accedere e utilizzare un nome API di dominio personalizzato con TLS attivazione reciproca, i client devono presentare certificati attendibili nelle API richieste. Puoi trovare ulteriori informazioni all'indirizzo Nome di dominio personalizzato per REST APIs in API Gateway.
Utilizzo dei certificati AWS Certificate Manager emessi
È possibile richiedere un certificato pubblicamente attendibile direttamente da ACM o importare certificati pubblici o autofirmati. Per configurare un certificato inACM, vai a ACM
Utilizzo di un AWS Private Certificate Authority certificato o importato
Per utilizzare un certificato importato in ACM o da AWS Private Certificate Authority mutuoTLS, API Gateway necessita di un certificato ownershipVerificationCertificate
emesso daACM. Questo certificato di proprietà viene utilizzato solo per verificare che disponi delle autorizzazioni per l'utilizzo del nome di dominio. Non viene utilizzato per la TLS stretta di mano. Se non ne hai già unoownershipVerificationCertificate
, vai https://console.aws.amazon.com/acm/
Dovrai mantenere la validità di questo certificato per tutta la durata del nome di dominio. Se un certificato scade e il rinnovo automatico non riesce, tutti gli aggiornamenti al nome di dominio verranno bloccati. Dovrai aggiornare il ownershipVerificationCertificateArn
con un ownershipVerificationCertificate
valido prima di poter apportare altre modifiche. ownershipVerificationCertificate
Non può essere utilizzato come certificato server per un altro TLS dominio comune in API Gateway. Se un certificato viene reimportato direttamente inACM, l'emittente deve rimanere lo stesso.
Configurazione del truststore
I truststore sono file di testo con un'estensione .pem
. Sono elenchi attendibili di certificati provenienti da autorità di certificazione. Per utilizzare mutuoTLS, crea un truststore di certificati X.509 di cui ti fidi per accedere ai tuoi. API
Devi includere nel truststore l'intera catena di attendibilità, a partire dal certificato della CA emittente, fino al certificato emesso da una CA radice. APIGateway accetta certificati client emessi da qualsiasi CA presente nella catena di fiducia. I certificati possono provenire da autorità di certificazione pubbliche o private. I certificati possono avere una lunghezza massima della catena di quattro. È inoltre possibile fornire certificati autofirmati. I seguenti algoritmi sono supportati nel truststore:
SHA-256 o superiore
RSA-2048 o superiore
ECDSA-256 o -384 ECDSA
APIGateway convalida una serie di proprietà del certificato. È possibile utilizzare gli autorizzatori Lambda per eseguire controlli aggiuntivi quando un client richiama un certificatoAPI, incluso verificare se un certificato è stato revocato. APIGateway convalida le seguenti proprietà:
Validation | Descrizione |
---|---|
Sintassi X.509 |
Il certificato deve soddisfare i requisiti di sintassi X.509. |
Integrità |
Il contenuto del certificato non deve essere stato modificato rispetto a quello firmato dall'autorità di certificazione del truststore. |
Validity |
Il periodo di validità del certificato deve essere attuale. |
Concatenamento di nomi/concatenamento di chiavi |
I nomi e gli oggetti dei certificati devono formare una catena ininterrotta. I certificati possono avere una lunghezza massima della catena di quattro. |
Caricare il truststore in un bucket Amazon S3 in un singolo file
Di seguito è riportato un esempio di come potrebbe presentarsi un file .pem.
Esempio certificates.pem
-----BEGIN CERTIFICATE----- <Certificate contents> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <Certificate contents> -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- <Certificate contents> -----END CERTIFICATE----- ...
Il AWS CLI comando seguente viene caricato nel tuo certificates.pem
bucket Amazon S3.
aws s3 cp
certificates.pem
s3://bucket-name
Il tuo bucket Amazon S3 deve avere l'autorizzazione di lettura per API Gateway per consentire API a Gateway di accedere al tuo truststore.
Configurazione di Mutual TLS per un nome di dominio personalizzato
Per configurare mutuo TLS per un RESTAPI, è necessario utilizzare un nome di dominio personalizzato regionale per il proprioAPI, con una politica TLS_1_2
di sicurezza. Per ulteriori informazioni sulla scelta di una politica di sicurezza, consultaScegli una politica di sicurezza per il tuo dominio REST API personalizzato in API Gateway.
Nota
Mutual TLS non è supportato per uso privatoAPIs.
Dopo aver caricato il tuo truststore su Amazon S3, puoi configurare il tuo nome di dominio personalizzato per utilizzare mutuo. TLS Incolla quanto segue (barre incluse) in un terminale:
aws apigateway create-domain-name --region
us-east-2
\ --domain-nameapi.example.com
\ --regional-certificate-arnarn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678
\ --endpoint-configuration types=REGIONAL \ --security-policy TLS_1_2 \ --mutual-tls-authentication truststoreUri=s3://bucket-name
/key-name
Dopo aver creato il nome di dominio, devi configurare i DNS record e le mappature dei percorsi di base per le operazioni. API Per ulteriori informazioni, consulta Configura un nome di dominio personalizzato regionale in API Gateway.
Invoca un utente API utilizzando un nome di dominio personalizzato che richiede mutuo TLS
Per richiamare un account API con mutuo TLS abilitato, i client devono presentare un certificato attendibile nella API richiesta. Quando un client tenta di richiamare il tuoAPI, API Gateway cerca l'emittente del certificato client nel tuo truststore. APIAffinché Gateway possa procedere con la richiesta, l'emittente del certificato e l'intera catena di fiducia fino al certificato CA principale devono trovarsi nel tuo truststore.
Il seguente comando curl
di esempio seguente invia una richiesta api.example.com,
che include my-cert.pem
nella richiesta. my-key.key
è la chiave privata del certificato.
curl -v --key
./my-key.key
--cert./my-cert.pem
api.example.com
Il tuo API viene invocato solo se il truststore considera attendibile il certificato. Le seguenti condizioni faranno sì che API Gateway fallisca l'TLShandshake e neghi la richiesta con un codice di stato. 403
Se il tuo certificato:
non è attendibile
è scaduto
non utilizza un algoritmo supportato
Nota
APIGateway non verifica se un certificato è stato revocato.
Aggiornamento del truststore
Per aggiornare i certificati nel truststore, carica un nuovo bundle di certificati in Amazon S3. Potrai quindi aggiornare il nome di dominio personalizzato per utilizzare il certificato aggiornato.
Usa il Controllo delle versioni di Amazon S3 per mantenere più versioni del truststore. Quando aggiorni il tuo nome di dominio personalizzato per utilizzare una nuova versione del truststore, API Gateway restituisce avvisi se i certificati non sono validi.
APIGateway emette avvisi sui certificati solo quando aggiorni il nome di dominio. APIGateway non ti avvisa se un certificato precedentemente caricato scade.
Il AWS CLI comando seguente aggiorna un nome di dominio personalizzato per utilizzare una nuova versione di truststore.
aws apigateway update-domain-name \ --domain-name
api.example.com
\ --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123
'
Disabilita mutuo TLS
Per disabilitare TLS il mutuo per un nome di dominio personalizzato, rimuovi il truststore dal tuo nome di dominio personalizzato, come mostrato nel comando seguente.
aws apigateway update-domain-name \ --domain-name api.example.com \ --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''
Risolvi i problemi relativi a Mutual per TLS REST API
Di seguito vengono forniti consigli per la risoluzione di errori e problemi che potrebbero verificarsi quando si attiva Mutual. TLS
Risoluzione dei problemi relativi agli avvisi dei certificati
Quando si crea un nome di dominio personalizzato con mutuoTLS, API Gateway restituisce avvisi se i certificati nel truststore non sono validi. Questo può verificarsi anche quando aggiorni un nome di dominio personalizzato all'utilizzo di un nuovo truststore. Gli avvisi indicano il problema con il certificato e l'oggetto del certificato che ha generato l'avviso. Mutual TLS è ancora abilitato per teAPI, ma alcuni client potrebbero non essere in grado di accedervi. API
Per identificare il certificato che ha generato l'avviso, devi decodificare i certificati nel truststore. Puoi utilizzare strumenti come openssl
per decodificare i certificati e identificarne gli oggetti.
Il comando seguente visualizza il contenuto di un certificato, incluso l'oggetto:
openssl x509 -in
certificate.crt
-text -noout
Aggiorna o rimuovi i certificati che hanno prodotto gli avvisi, quindi carica un nuovo truststore su Amazon S3. Dopo aver caricato il nuovo truststore, aggiorna il nome di dominio personalizzato per utilizzarlo.
Risoluzione dei problemi relativi ai conflitti dei nomi di dominio
L'errore "The certificate subject <certSubject> conflicts with an existing
certificate from a different issuer."
indica che più autorità di certificazione hanno emesso un certificato per questo dominio. Per ogni soggetto del certificato, può esserci un solo emittente in API Gateway per i TLS domini reciproci. Dovrai ottenere tutti i certificati per tale oggetto tramite un unico emittente. Se il problema riguarda un certificato di cui non hai il controllo ma puoi provare la proprietà del nome di dominio, contatta AWS Support
Risoluzione dei problemi relativi ai messaggi di stato dei nomi di dominio
PENDING_CERTIFICATE_REIMPORT
: Ciò significa che hai reimportato un certificato ACM e la convalida non è riuscita perché il nuovo certificato ha un SAN (nome alternativo del soggetto) che non è coperto dal ownershipVerificationCertificate
o l'oggetto o SANs nel certificato non copre il nome di dominio. Potrebbe esserci una configurazione errata o è stato importato un certificato non valido. È necessario reimportare un certificato valido in. ACM Per ulteriori informazioni sulla convalida, consulta Convalida della proprietà del dominio.
PENDING_OWNERSHIP_VERIFICATION
: Ciò significa che il certificato precedentemente verificato è scaduto e non ACM è stato possibile rinnovarlo automaticamente. Dovrai rinnovare il certificato o richiederne uno nuovo. Ulteriori informazioni sul rinnovo dei certificati sono disponibili nella guida alla risoluzione dei problemi relativi al ACM rinnovo gestito dei certificati.
Risolvi i problemi relativi al certificato restituito errato
Quando si esegue la migrazione di un certificato dedicato da un nome di dominio completo (FQDN) a un nome di dominio cliente wildcard, API Gateway potrebbe restituire il certificato per il nome di dominio FQDN anziché il nome di dominio wildcard.
Il comando seguente mostra quale certificato viene restituito da Gateway: API
openssl s_client -connect hostname:port
Se il certificato risultante è per ilFQDN, contatta AWS Support