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

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:

Endpoint	Default
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	Il valore predefinito è: <apim-service-name>.developer.azure-api.net
Gestione	Il valore predefinito è: <apim-service-name>.management.azure-api.net
API di configurazione (v2)	Il valore predefinito è: <apim-service-name>.configuration.azure-api.net
SCM	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.

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 passare all'insieme di credenziali delle chiavi.

  2. Nel menu a sinistra, selezionare Configurazione di accesso e prendere nota del 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 un criterio di accesso dell'insieme di credenziali delle chiavi:
     

     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 Ottieni e Elenco, quindi selezionare Avanti.
     4. Nella scheda Entità, Seleziona entità , cercare il nome della risorsa dell'identità gestita e quindi selezionareAvanti. 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 al controllo degli accessi in base al ruolo 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 segreti dell'insieme di credenziali delle chiavi.
     4. Nella scheda Membri selezionare Identità gestita>+ Seleziona membri.
     5. Nella pagina Seleziona identità gestita, selezionare l'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente associata all'istanza di Gestione API e quindi selezionare 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.

Nota

Il processo di assegnazione del certificato potrebbe richiedere circa 15 minuti o più, a seconda delle dimensioni della distribuzione. Il livello sviluppatore ha dei tempi di inattività, mentre i livelli Basic e superiore non li hanno.

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 Gestione API 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, Gestione API 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, Gestione API risponde con il certificato server appropriato.

Client che chiamano senza intestazione SNI

Se si usa un client che non invia l'intestazione SNI, Gestione API 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 Gestione API 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).

Passaggi successivi

Aggiornare e ridimensionare il servizio