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

Quando si crea un'istanza del servizio azure Gestione API nel cloud di Azure, Azure lo assegna a un azure-api.net sottodominio , ad esempio apim-service-name.azure-api.net. È anche possibile esporre gli endpoint 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:

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

Prerequisiti

  • Una sottoscrizione di Azure attiva. Se non si ha una sottoscrizione di Azure, creare un account Azure gratuito prima di iniziare.

  • 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). Il nome alternativo soggetto o soggetto deve corrispondere al nome di dominio (in questo modo Gestione API'istanza di 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 i record DNS.

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

Endpoint per domini personalizzati

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

Endpoint 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 (legacy) Il valore predefinito è: <apim-service-name>.portal.azure-api.net
Portale per sviluppatori Il valore predefinito è: <apim-service-name>.developer.azure-api.net
Gestione Il valore predefinito è: <apim-service-name>.management.azure-api.net
Scm Il valore predefinito è: <apim-service-name>.scm.azure-api.net

Considerazioni

  • È possibile aggiornare uno qualsiasi 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 il portale per sviluppatori (URL del portale per sviluppatori).
  • Solo Gestione API proprietari di istanze possono usare internamente gli endpoint di Gestione e Gestione configurazione sito. 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.

Opzioni del certificato di dominio

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

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 usare una dipendenza rigida da un certificato 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 requisiti seguenti. Se si abilita il certificato gratuito gestito da Gestione API, soddisfa già questi requisiti.

  • Esportato come file PFX, crittografato con triple DES e facoltativamente protetto da password.
  • Deve contenere una chiave privata costituita da almeno 2048 bit
  • Contiene 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. Passare all'istanza di Gestione API nel portale di Azure.
  2. Nel riquadro di spostamento a sinistra selezionare Domini personalizzati.
  3. Selezionare +Aggiungi o 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 oggetto valido. File PFX e specificare la 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 Negotiate client certificate or Default SSL binding ( Negozia certificato client o Associazione SSL predefinita). Configurare il dominio del gateway con certificato personalizzato
  10. Selezionare Aggiungi o selezionare Aggiorna per un endpoint esistente.
  11. Selezionare 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 tempi di inattività, mentre i livelli basic e superiori non sono.

Come Gestione API server proxy risponde con i certificati SSL nella handshake TLS

Quando si configura un dominio personalizzato per l'endpoint gateway, è possibile impostare proprietà aggiuntive che determinano il modo in cui Gestione API risponde con un certificato server, a seconda della richiesta client.

Client che chiamano con l'intestazione SNI (Server Name Indication)

Se si dispone di uno o più domini personalizzati configurati per l'endpoint gateway, 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 il servizio ha configurato più domini personalizzati per gateway (supportato nel livello Developer and 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

Gestione API server proxy 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 si applica a livello di nome host gateway , tutte le richieste di connessione richiedono il certificato client. È possibile risolvere questa limitazione e configurare fino a 20 domini personalizzati per gateway (supportati solo nel livello Premium ).

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 cambi. Per altre informazioni, vedere Indirizzi IP di Azure Gestione API e le domande frequenti Gestione API.

Nota

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

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 gratuito e gestito 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 .

Passaggi successivi

Aggiornare e ridimensionare il servizio