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.

Prerequisiti per la mutua TLS

Per configurare mutuo TLS è necessario:

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. Se desideri importare un certificato, continua a leggere la sezione seguente.

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/a configurarne uno.

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. ownershipVerificationCertificateNon 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:

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à:

Caricare il truststore in un bucket Amazon S3 in un singolo file

Di seguito è riportato un esempio di come potrebbe presentarsi un file .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.

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-name api.example.com \
    --regional-certificate-arn arn: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:

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 per aprire un ticket.

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 per aprire un ticket.