Nomi di dominio personalizzati per API private in Gateway API
Puoi creare un nome di dominio personalizzato per la tua API privata. Un nome di dominio personalizzato privato consente di fornire un URL più semplice e intuitivo ai chiamanti dell'API. Con un nome di dominio personalizzato privato è possibile ridurre la complessità, configurare le misure di sicurezza durante l'handshake TLS e controllare il ciclo di vita del certificato del nome di dominio tramite AWS Certificate Manager (ACM). Per ulteriori informazioni, consulta Protezione della chiave privata del certificato per il nome di dominio personalizzato.
I nomi di dominio personalizzati per le API private non devono essere necessariamente univoci tra più account. È possibile creare example.private.com nell'account 111122223333 e nell'account 555555555555, purché il certificato ACM copra il nome di dominio. Per identificare un nome di dominio personalizzato privato, usa l'ARN del nome di dominio personalizzato privato. Questo identificatore è univoco per i nomi di dominio personalizzati privati.
Quando crei un nome di dominio personalizzato privato in Gateway API, sei un provider di API. Puoi fornire il tuo nome di dominio personalizzato privato ad altri Account AWS utilizzando Gateway API o AWS Resource Access Manager (AWS RAM).
Quando invochi un nome di dominio personalizzato privato, sei un consumatore di API. Puoi utilizzare un nome di dominio personalizzato privato dal tuo Account AWS o da un altro Account AWS.
Quando utilizzi un nome di dominio personalizzato privato, crei un'associazione di accesso al nome di dominio tra un endpoint VPC e un nome di dominio personalizzato privato. Con un'associazione di accesso al nome di dominio, i consumatori di API possono invocare il tuo nome di dominio personalizzato privato mentre sono isolati dalla rete Internet pubblica. Per ulteriori informazioni, consulta Attività dei provider di API e dei consumatori di API per i nomi di dominio personalizzati per le API private.
Protezione della chiave privata del certificato per il nome di dominio personalizzato
Quando richiedi un certificato SSL/TLS utilizzando ACM per creare il tuo nome di dominio personalizzato per le API private, ACM genera una coppia di chiavi pubblica/privata. La coppia di chiavi viene generata al momento dell'importazione di un certificato. La chiave di accesso pubblica diventa parte del certificato. Per archiviare in modo sicuro la chiave privata, ACM crea un'altra chiave tramite AWS KMS, chiamata chiave KMS, con l'alias aws/acm. AWS KMS utilizza questa chiave per crittografare la chiave privata del certificato. Per ulteriori informazioni, consulta Data protection in AWS Certificate Manager nella Guida per l'utente di AWS Certificate Manager.
Gateway API utilizza AWS TLS Connection Manager, un servizio accessibile ai Servizi AWS, per proteggere e utilizzare le chiavi private del certificato. Quando si usa il certificato ACM per creare un nome di dominio personalizzato di Gateway API, Gateway API associa il certificato ad AWS TLS Connection Manager. A questo scopo viene creata una concessione in AWS KMS per la chiave gestita da AWS. Questa concessione consente a TLS Connection Manager di utilizzare AWS KMS per decrittografare la chiave privata del certificato. TLS Connection Manager utilizza il certificato e la chiave privata decrittografata (testo normale) per stabilire una connessione sicura (sessione SSL/TLS) con i client dei servizi Gateway API. Quando l'associazione del certificato a un servizio Gateway API viene annullata, la concessione viene ritirata. Per ulteriori informazioni, consulta Grants nella Guida per gli sviluppatori di AWS Key Management Service.
Per ulteriori informazioni, consulta Crittografia dei dati inattivi in Amazon API Gateway.
Considerazioni sui nomi di dominio personalizzati
Le seguenti considerazioni potrebbero influire sull’utilizzo dei nomi di dominio personalizzati:
-
Gateway API impiega circa 15 minuti per allocare il nome di dominio personalizzato privato.
-
Se si aggiorna il certificato ACM, Gateway API impiega circa 15 minuti per completare l’operazione. Durante questo periodo, il nome di dominio è nello stato
UPDATINGed è ancora possibile accedervi. -
Per invocare un nome di dominio personalizzato privato, è necessario creare un'associazione di accesso al nome di dominio personalizzato. Affinché un'associazione di accesso al nome di dominio sia pronta sono necessari circa 15 minuti.
-
L’ARN del nome di dominio personalizzato privato contiene
account-id. Quando si crea un nome di dominio, Gateway API utilizza il formato ARNarn:. Quando si accede a un nome di dominio personalizzato privato, si utilizza il formato ARNpartition:apigateway:region::/domainnamesarn:.partition:apigateway:region:account-id:/domainnames/domain-namePotrebbe essere necessario modificare le autorizzazioni IAM per consentire l’accesso a un nome di dominio privato dopo averlo creato.
-
Non è possibile invocare nomi di dominio personalizzati privati con lo stesso nome dallo stesso endpoint VPC. Ad esempio, per invocare
arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234earn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+xyz000, è necessario associare ciascun nome di dominio personalizzato privato a un endpoint VPC diverso. -
Sono supportati i certificati con caratteri jolly, ad esempio un certificato per
*.private.example.com. -
I nomi di dominio personalizzati con caratteri jolly non sono supportati.
-
Sono supportati solo i certificati RSA con una lunghezza di chiave di 2048 bit e i certificati ECDSA con lunghezze di chiave di 256 bit e 384 bit.
-
Non è possibile impostare il tipo di indirizzo IP per le API private per consentire solo agli indirizzi IPv4 di invocare l’API privata. È supportato solo il tipo dualstack. Per ulteriori informazioni, consulta Tipi di indirizzo IP per REST API in Gateway API.
-
Per inviare il traffico utilizzando l’API privata, è possibile usare tutti i tipi di indirizzo IP supportati da Amazon VPC. È possibile inviare traffico dualstack e IPv6 configurando le impostazioni sull'endpoint VPC. Questa configurazione non può essere modificata tramite Gateway API. Per ulteriori informazioni, consulta Aggiungere il supporto IPv6 per il VPC.
-
La mappatura percorso di base a più livelli, ad esempio la mappatura API privata a
/developers/feature, non è supportata, ma è possibile utilizzare una regola di routing per creare una condizione di percorso a più livelli. Per ulteriori informazioni, consulta Invio del traffico alle API tramite il nome di dominio personalizzato in Gateway API. -
Non è possibile impostare una versione TLS minima per un nome di dominio personalizzato privato. A tutti i nomi di dominio personalizzati privati è associata la policy di sicurezza
TLS-1-2. -
È possibile utilizzare la policy degli endpoint VPC per controllare l'accesso a un nome di dominio personalizzato privato. Per ulteriori informazioni, consulta gli esempi 4 e 5 in Utilizzo di policy di endpoint VPC per API private in API Gateway.
-
È necessario creare una policy delle risorse separata per l'API privata e per il nome di dominio personalizzato privato. Per invocare un nome di dominio personalizzato privato, un consumatore di API deve disporre dell'accesso dalla policy delle risorse dei nomi di dominio personalizzati privati, dalla policy delle risorse delle API private e da qualsiasi autorizzazione o policy di endpoint VPC sull'API privata.
Considerazioni sull'utilizzo di nomi di dominio personalizzati privati con altre risorse Gateway API
Le seguenti considerazioni potrebbero influire sull’utilizzo dei nomi di dominio personalizzati privati con altre risorse Gateway API:
-
Non è possibile inviare il traffico da un nome di dominio personalizzato privato a un’API pubblica.
-
Quando un'API privata viene mappata a un nome di dominio personalizzato privato, non è possibile modificare il tipo di endpoint dell'API.
-
Non è possibile eseguire la migrazione di un nome di dominio personalizzato pubblico a un nome di dominio personalizzato privato.
-
Se disponi di un endpoint VPC che utilizzi per accedere a un nome di dominio personalizzato pubblico, non utilizzarlo per creare un'associazione di accesso al nome di dominio con un nome di dominio personalizzato privato.
Differenze tra nomi di dominio personalizzati privati e nomi di dominio personalizzati pubblici
Di seguito sono descritte le differenze tra i nomi di dominio personalizzati privati e pubblici:
-
I nomi di dominio personalizzati privati non devono essere necessariamente univoci tra più account.
-
Un nome di dominio privato ha un ID del nome di dominio. Questo ID identifica in modo univoco un nome di dominio personalizzato privato e non viene generato per i nomi di dominio personalizzati pubblici.
-
Quando utilizzi l'interfaccia AWS CLI per aggiornare o eliminare un nome di dominio personalizzato privato, devi fornire l'ID del nome di dominio. Se il nome di dominio personalizzato privato è
example.come il nome di dominio personalizzato pubblico èexample.come non si fornisce l'ID del nome di dominio, Gateway API modificherà o eliminerà il nome di dominio personalizzato pubblico.
Passaggi successivi per nomi di dominio personalizzati per la API private
Per informazioni sulle attività di un provider e di un consumatore di API, consulta Attività dei provider di API e dei consumatori di API per i nomi di dominio personalizzati per le API private.
Per istruzioni sulla creazione di un nome di dominio personalizzato privato che puoi invocare nel tuo Account AWS, consulta Tutorial: creazione e invocazione di un nome di dominio personalizzato per API private.
Per istruzioni su come fornire a un altro Account AWS l'accesso al tuo nome di dominio personalizzato privato, consulta Provider di API: condivisione del nome di dominio personalizzato privato tramite AWS RAM. Per istruzioni su come associare l'endpoint VPC a un nome di dominio personalizzato privato in un altro Account AWS, consulta Consumatore di API: associazione dell'endpoint VPC a un nome di dominio personalizzato privato condiviso.
