Configurare un nome di dominio personalizzato per l'istanza di Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

Quando si crea un'istanza del servizio Gestione API di Azure nel cloud di Azure, Azure lo assegna a un sottodominio azure-api.net, ad esempio apim-service-name.azure-api.net. È anche possibile esporre gli endpoint di Gestione API usando il proprio nome di dominio personalizzato, ad esempio contoso.com. Questo articolo illustra come eseguire il mapping di un nome DNS personalizzato esistente agli endpoint esposti da un'istanza di Gestione API.

Importante

Gestione API accetta solo le richieste con valori di intestazione host corrispondenti a:

• Nome di dominio predefinito del gateway
• Uno qualsiasi dei nomi di dominio personalizzati configurati del gateway

Nota

Attualmente, i nomi di dominio personalizzati non sono supportati in un gateway dell'area di lavoro.

Importante

Il completamento delle modifiche apportate all'infrastruttura del servizio Gestione API, ad esempio la configurazione di domini personalizzati, l'aggiunta di certificati CA, la scalabilità, la configurazione della rete virtuale, le modifiche della zona di disponibilità e le aggiunte all'area, possono richiedere 15 minuti o più, a seconda del livello di servizio e delle dimensioni della distribuzione. Prevedere tempi più lunghi per un'istanza con un numero maggiore di unità di scala o configurazione in più aree. Modifiche progressive al servizio di gestione delle API vengono eseguite con attenzione per preservare la capacità e la disponibilità.

Durante l'aggiornamento del servizio, non è possibile apportare altre modifiche all'infrastruttura del servizio. Tuttavia, è possibile configurare API, prodotti, criteri e impostazioni utente. Il servizio non riscontra tempi di inattività del gateway e Gestione API continuerà a gestire le richieste API senza interruzioni (ad eccezione del livello Sviluppatore).

Prerequisiti

• Un'istanza di Gestione API. Per altre informazioni, vedere Create an Azure API Management instance (Creare un'istanza di Gestione API di Azure).

• Nome di dominio personalizzato di proprietà dell'utente o dell'organizzazione. Questo articolo non fornisce istruzioni su come ottenere un nome di dominio personalizzato.

• Facoltativamente, un certificato valido con una chiave pubblica e privata (.PFX). L'oggetto o il nome alternativo del soggetto (SAN) deve corrispondere al nome di dominio (in questo modo l'istanza di Gestione API può esporre in modo sicuro gli URL tramite TLS).

  Vedere Opzioni del certificato di dominio.

• Record DNS ospitati in un server DNS per eseguire il mapping del nome di dominio personalizzato al nome di dominio predefinito dell'istanza di Gestione API. Questo argomento non fornisce istruzioni su come ospitare il record DNS.

  Per altre informazioni sui record necessari, vedere configurazione DNS, più avanti in questo articolo.

Endpoint per domini personalizzati

Esistono diversi endpoint di Gestione API a cui è possibile assegnare un nome di dominio personalizzato. Attualmente sono disponibili gli endpoint seguenti:

Punto finale	Predefinito
Gateway	Il valore predefinito è: <apim-service-name>.azure-api.net. Il gateway è l'unico endpoint disponibile per la configurazione nel livello a consumo. La configurazione dell'endpoint gateway predefinita rimane disponibile dopo l'aggiunta di un dominio gateway personalizzato.
Portale per sviluppatori (tutti i livelli ad eccezione del consumo)	Il valore predefinito è: <apim-service-name>.developer.azure-api.net
Gestione (solo livelli classici)	Il valore predefinito è: <apim-service-name>.management.azure-api.net
API di configurazione del gateway auto-gestito (v2)	Il valore predefinito è: <apim-service-name>.configuration.azure-api.net
SCM (solo livelli classici)	Il valore predefinito è: <apim-service-name>.scm.azure-api.net

Considerazioni

• È possibile aggiornare uno degli endpoint supportati nel livello di servizio. In genere, i clienti aggiornano Gateway (questo URL viene usato per chiamare le API esposte tramite Gestione API) e Portale per sviluppatori (l'URL del portale per sviluppatori).
• L'endpoint gateway predefinito rimane disponibile dopo aver configurato un nome di dominio del gateway personalizzato e non può essere eliminato. Per altri endpoint di Gestione API (ad esempio Portale per sviluppatori) configurati con un nome di dominio personalizzato, l'endpoint predefinito non è più disponibile.
• Solo i proprietari di istanze di Gestione API possono usare internamente gli endpoint Gestione e SCM. Questi endpoint vengono assegnati meno frequentemente a un nome di dominio personalizzato.
• I livelli Premium e Developer supportano l'impostazione di più nomi host per l'endpoint Gateway.
• I nomi di dominio con caratteri jolly, ad esempio *.contoso.com, sono supportati in tutti i livelli, ad eccezione del livello Consumo. Un certificato di sottodominio specifico (ad esempio, api.contoso.com) ha la precedenza su un certificato con caratteri jolly (*.contoso.com) per le richieste di api.contoso.com.
• Quando si configura un dominio personalizzato per il portale per sviluppatori, è possibile abilitare CORS per il nuovo nome di dominio. Questa operazione è necessaria per consentire ai visitatori del portale per sviluppatori di usare la console interattiva nelle pagine di riferimento dell'API.

Opzioni dei certificati dei domini

Gestione API supporta certificati TLS personalizzati o certificati importati da Azure Key Vault. È anche possibile abilitare un certificato gestito gratuito.

Avviso

Se è necessaria l'aggiunta del certificato, usare un nome di dominio personalizzato e un certificato personalizzato o Key Vault, non il certificato predefinito o il certificato gestito gratuito. Non è consigliabile dipendere in modo sostanziale da un certificato che non è gestito.

Personalizzazione

Se si dispone già di un certificato privato da un provider di terze parti, è possibile caricarlo nell'istanza di Gestione API. Deve soddisfare i seguenti requisiti. (Se si abilita il certificato gratuito gestito da Gestione API, soddisfa già questi requisiti).

• Deve essere esportato come file PFX, crittografato con triple DES e facoltativamente protetto da password.
• Contenere una chiave privata di almeno 2048 bit
• Deve contenere tutti i certificati intermedi e il certificato radice nella catena di certificati.

Insieme di credenziali delle chiavi di

È consigliabile usare Azure Key Vault per gestire i certificati e impostarli su autorenew.

Se si usa Azure Key Vault per gestire un certificato TLS di dominio personalizzato, assicurarsi che il certificato venga inserito in Key Vault come certificato, non come segreto.

Attenzione

Quando si usa un certificato dell'insieme di credenziali delle chiavi in Gestione API, prestare attenzione a non eliminare il certificato, l'insieme di credenziali delle chiavi o l'identità gestita usata per accedere all'insieme di credenziali delle chiavi.

Per recuperare un certificato TLS/SSL, Gestione API deve disporre dell'elenco e ottenere le autorizzazioni dei segreti per Azure Key Vault contenente il certificato.

• Quando si usa il portale di Azure per importare il certificato, tutti i passaggi di configurazione necessari vengono completati automaticamente.

• Quando si usano strumenti da riga di comando o API di gestione, queste autorizzazioni devono essere concesse manualmente, in due passaggi:

  1. Nella pagina Identità gestite dell'istanza di Gestione API, abilitare un'identità gestita assegnata dal sistema o assegnata dall'utente. Prendere nota dell'ID principale in tale pagina.
  2. Assegnare le autorizzazioni all'identità gestita per accedere all'insieme di credenziali delle chiavi. Seguire la procedura descritta nella sezione seguente.

  Configurare l'accesso all'insieme di credenziali delle chiavi

  1. Nel portale, vai al tuo gestione delle chiavi.
  2. Nel menu a sinistra selezionare Configurazione di accesso. Si noti il modello di autorizzazione configurato.
  3. A seconda del modello di autorizzazione, configurare un criterio di accesso dell'insieme di credenziali delle chiavi o un accesso al controllo degli accessi in base al ruolo di Azure per un'identità gestita di Gestione API.

  Per aggiungere una policy di accesso del Key Vault:

  1. Selezionare Criteri di accesso nel menu a sinistra.
  2. Nella pagina Criteri di accesso selezionare + Crea.
  3. Nella scheda Autorizzazioni , in Autorizzazioni segrete selezionare Recupera ed Elenco e quindi selezionare Avanti.
  4. Nella scheda Entità selezionare Entità, cercare il nome della risorsa dell'identità gestita e quindi selezionare Avanti. Se si usa un'identità assegnata dal sistema, l'entità è il nome dell'istanza di Gestione API.
  5. Selezionare di nuovo Avanti. Nella scheda Rivedi e crea selezionare Crea.

  Per configurare l'accesso RBAC di Azure:

  1. Nel menu a sinistra selezionare Controllo di accesso (IAM).
  2. Nella pagina Controllo di accesso (IAM), selezionare Aggiungi assegnazione di ruolo.
  3. Nella scheda Ruolo, selezionare Utente dei certificati Key Vault.
  4. Nella scheda Membri, selezionare Identità gestita>+ Seleziona membri.
  5. Nella finestra Seleziona identità gestite selezionare l'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente associata all'istanza di Gestione API e quindi fare clic su Seleziona.
  6. Seleziona Rivedi + assegna.

Se il certificato è impostato su autorenew e il livello Gestione API ha un contratto di servizio (ovvero in tutti i livelli tranne il livello Sviluppatore), Gestione API rileverà automaticamente la versione più recente, senza tempi di inattività per il servizio.

Per altre informazioni, vedere Usare le identità gestite in Gestione API di Azure.

Gestito

Gestione API offre un certificato TLS gratuito e gestito per il dominio, se non si vuole acquistare e gestire il proprio certificato. Il certificato viene rinnovato automaticamente.

Nota

Il certificato TLS gratuito gestito è in anteprima. Attualmente non è disponibile nei livelli di servizio v2.

Limiti

• Attualmente può essere usato solo con l'endpoint gateway del servizio Gestione API
• Non supportato con il gateway self-hosted
• Non supportato nelle aree di Azure seguenti: Francia meridionale e Sudafrica occidentale
• Attualmente disponibile solo nel cloud di Azure
• Non supporta i nomi di dominio radice, ad esempio contoso.com. Richiede un nome completo, ad esempio api.contoso.com.
• Supporta solo i nomi di dominio pubblici
• Può essere configurato solo quando si aggiorna un'istanza di Gestione API esistente, non quando si crea un'istanza

Impostare un nome di dominio personalizzato - Portale

Scegliere i passaggi in base al certificato di dominio che si vuole usare.

Personalizzazione

1. Accedere all'istanza di Gestione API nel portale di Azure.
2. Nel riquadro di spostamento a sinistra selezionare Domini personalizzati.
3. Selezionare +Aggiungi, oppure selezionare un endpoint esistente da aggiornare.
4. Nella finestra a destra selezionare il tipo di endpoint per il dominio personalizzato.
5. Nel campo Nome host specificare il nome da usare. Ad esempio, api.contoso.com.
6. In Certificato, selezionare Personalizzato
7. Selezionare File certificato per selezionare e caricare un certificato.
8. Caricare un file .PFX valido e specificare la relativa Password, se il certificato è protetto con una password.
9. Quando si configura un endpoint gateway, selezionare o deselezionare altre opzioni in base alle esigenze, tra cui Negoziazione certificato client oassociazione SSL predefinita.
10. Selezionare Aggiungi o Aggiorna per un endpoint esistente.
11. Seleziona Salva.

Insieme di credenziali delle chiavi di

1. Accedere all'istanza di Gestione API nel portale di Azure.
2. Nel riquadro di spostamento a sinistra selezionare Domini personalizzati.
3. Selezionare +Aggiungi, oppure selezionare un endpoint esistente da aggiornare.
4. Nella finestra a destra selezionare il tipo di endpoint per il dominio personalizzato.
5. Nel campo Nome host specificare il nome da usare. Ad esempio, api.contoso.com.
6. In Certificato, selezionare Key Vault e quindi Seleziona.
   1. Selezionare la sottoscrizione dall'elenco a discesa.
   2. Selezionare l'insieme di credenziali delle chiavi dall'elenco a discesa.
   3. Dopo aver caricato i certificati, selezionare il certificato dall'elenco a discesa. Fare clic su Seleziona.
   4. In Identità client selezionare un'identità assegnata dal sistema o un'identità gestita assegnata dall'utente abilitata nell'istanza per accedere all'insieme di credenziali delle chiavi.
7. Quando si configura un endpoint gateway, selezionare o deselezionare altre opzioni in base alle esigenze, tra cui Negoziazione certificato client oassociazione SSL predefinita.
8. Selezionare Aggiungi o Aggiorna per un endpoint esistente.
9. Seleziona Salva.

Gestito

1. Accedere all'istanza di Gestione API nel portale di Azure.
2. Nel riquadro di spostamento a sinistra selezionare Domini personalizzati.
3. Selezionare +Aggiungi, oppure selezionare un endpoint esistente da aggiornare.
4. Nella finestra a destra selezionare il tipo di endpoint per il dominio personalizzato.
5. Nel campo Nome host specificare il nome da usare. Ad esempio, api.contoso.com.
6. In Certificato, selezionare Gestito per abilitare un certificato gratuito gestito da Gestione API. Il certificato gestito è disponibile in anteprima solo per l'endpoint del gateway.
7. Copiare i valori seguenti e usarli per configurare IL DNS:
   • Record TXT
   • record CNAME
8. Quando si configura un endpoint gateway, selezionare o deselezionare altre opzioni in base alle esigenze, tra cui Negoziazione certificato client oassociazione SSL predefinita.
9. Selezionare Aggiungi o Aggiorna per un endpoint esistente.
10. Seleziona Salva.

Configurazione del DNS

• Configurare un record CNAME per il dominio personalizzato.
• Quando si usa il certificato gratuito e gestito di Gestione API, configurare anche un record TXT per stabilire la proprietà del dominio.

Nota

Il certificato gratuito viene rilasciato da DigiCert. Per alcuni domini, è necessario consentire in modo esplicito DigiCert come autorità di certificazione creando un record di dominio CAA con il valore: 0 issue digicert.com.

Record CNAME

Configurare un record CNAME che punta dal nome di dominio personalizzato (ad esempio, api.contoso.com) al nome host del servizio Gestione API (ad esempio, <apim-service-name>.azure-api.net). Un record CNAME è più stabile di un record A nel caso in cui l'indirizzo IP venga modificato. Per altre informazioni, vedere Indirizzi IP di Gestione API di Azure e Domande frequenti su Gestione API.

Nota

Alcuni registrar di dominio consentono di eseguire il mapping dei sottodomini solo quando si usa un record CNAME, ad esempio www.contoso.com, e non i nomi radice, ad esempio contoso.com. Per altre informazioni sui record CNAME, vedere la documentazione fornita dal registrar o dai nomi di dominio IETF - Implementazione e specifica.

Attenzione

Quando si usa il certificato gratuito e gestito e si configura un record CNAME con il provider DNS, assicurarsi che venga risolto nel nome host del servizio Gestione API predefinito (<apim-service-name>.azure-api.net). Attualmente Gestione API non rinnova automaticamente il certificato se il record CNAME non viene risolto nel nome host predefinito di Gestione API. Ad esempio, se si usa il certificato gratuito e gestito e si usa Cloudflare come provider DNS, assicurarsi che il proxy DNS non sia abilitato nel record CNAME.

Record TXT

Quando si abilita il certificato gratuito e gestito per Gestione API, configurare anche un record TXT nella zona DNS per stabilire la proprietà del nome di dominio.

• Il nome del record è il nome di dominio personalizzato preceduto da apimuid. Esempio: apimuid.api.contoso.com.
• Il valore è un identificatore di proprietà del dominio fornito dall'istanza di Gestione API.

Quando si usa il portale per configurare il certificato gestito gratuito per il dominio personalizzato, il nome e il valore del record TXT necessario vengono visualizzati automaticamente.

È anche possibile ottenere un identificatore di proprietà del dominio chiamando l'API REST Get Domain Ownership Identifier (Ottieni l'identificatore di proprietà del dominio).

Modalità di risposta del server proxy di Gestione API con certificati SSL nell'handshake TLS

Quando si configura un dominio personalizzato per l'endpoint del gateway, è possibile impostare proprietà aggiuntive che determinano la risposta di API Management con un certificato server, a seconda della richiesta client.

Client che chiamano con intestazione SNI (Server Name Indication)

Se per l'endpoint del gateway sono configurati uno o più domini personalizzati, API Management può rispondere alle richieste HTTPS da:

• Dominio personalizzato (ad esempio, contoso.com)
• Dominio predefinito (ad esempio, apim-service-name.azure-api.net).

In base alle informazioni nell'intestazione SNI, API Management risponde con il certificato server appropriato.

Client che chiamano senza intestazione SNI

Se si usa un client che non invia l'intestazione SNI, API Management crea risposte in base alla logica seguente:

• Se il servizio dispone di un solo dominio personalizzato configurato per gateway, il certificato predefinito è il certificato rilasciato al dominio personalizzato del gateway.

• Se nel servizio sono configurati più domini personalizzati per Gateway (scenario supportato solo nei livelli Sviluppatore e Premium), è possibile designare il certificato predefinito impostando la proprietà defaultSslBinding su true ("defaultSslBinding":"true"). Nel portale selezionare la casella di controllo Associazione SSL predefinita.

  Se non si imposta la proprietà, il certificato predefinito è il certificato rilasciato al dominio gateway predefinito ospitato in *.azure-api.net.

Supporto per una richiesta PUT/POST con payload di grandi dimensioni

Il server proxy di API Management supporta le richieste con payload di grandi dimensioni (>40 KB) quando si usano certificati lato client in HTTPS. Per impedire il blocco della richiesta del server, è possibile impostare la proprietà negotiateClientCertificate su true ("negotiateClientCertificate": "true") nel nome host del gateway. Nel portale selezionare la casella di controllo Negozia certificato client.

Se la proprietà è impostata su true, il certificato client viene richiesto al momento della connessione SSL/TLS, prima di qualsiasi scambio di richieste HTTP. Poiché l'impostazione viene applicata al livello del nome host del Gateway, tutte le richieste di connessione richiedono il certificato client. È possibile aggirare questa limitazione e configurare fino a 20 domini personalizzati per il gateway (supportato solo nel livello Premium).

Limitazione per il nome di dominio personalizzato nel livello Standard v2

Attualmente, nel livello Standard v2 Gestione API richiede un nome DNS risolvibile pubblicamente per consentire il traffico verso l'endpoint del gateway. Se si configura un nome di dominio personalizzato per l'endpoint del gateway, tale nome deve essere risolvibile pubblicamente, non limitato a una zona DNS privata.

Come soluzione alternativa negli scenari in cui si limita l'accesso pubblico al gateway e si configura un nome di dominio privato, è possibile configurare il gateway applicazione per ricevere traffico al nome di dominio privato e instradarlo all'endpoint gateway dell'istanza di Gestione API. Per un'architettura di esempio, vedere questo repository GitHub.

Risoluzione dei problemi: La rotazione del certificato del nome host da Azure Key Vault non è riuscita

A causa di un problema di configurazione o connettività, l'istanza di Gestione API potrebbe non essere in grado di recuperare un certificato nome host da Azure Key Vault dopo l'aggiornamento o la rotazione di un certificato. In questo caso, l'istanza di Gestione API continua a usare un certificato memorizzato nella cache fino a quando non riceve un certificato aggiornato. Se il certificato memorizzato nella cache scade, il traffico di runtime verso il gateway verrà bloccato. Qualsiasi servizio upstream, come Application Gateway che usa la configurazione del certificato del nome host, può bloccare anche il traffico in tempo reale verso il gateway quando viene usato un certificato scaduto memorizzato nella cache.

Per attenuare questo problema, verificare che il modulo di gestione delle chiavi esista e che il certificato sia archiviato al suo interno. Se l'istanza di Gestione API viene distribuita in una rete virtuale, verificare la connettività in uscita al tag del servizio AzureKeyVault. Controllare se l'identità gestita usata per accedere al key vault esiste. Verificare le autorizzazioni dell'identità gestita per accedere al Key Vault. Per informazioni dettagliate sulla configurazione, vedere Configurare un nome di dominio personalizzato - Key Vault, più indietro in questo articolo. Dopo il ripristino della configurazione, il certificato nome host verrà aggiornato in Gestione API entro 4 ore.

Contenuti correlati

Aggiornare e ridimensionare il servizio