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

  • Articolo

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.

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.

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.

Impostare un nome di dominio personalizzato - Portale

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

  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. Configurare il dominio del gateway con un certificato personalizzato
  10. Selezionare Aggiungi o Aggiorna per un endpoint esistente.
  11. 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).

Passaggi successivi

Aggiornare e ridimensionare il servizio