Come proteggere le API usando l'autenticazione con certificati client in Gestione API

SI APPLICA A: Tutti i livelli di Gestione API

Gestione API offre la possibilità di proteggere l'accesso alle API (ovvero dal client a Gestione API) mediante i certificati client e l'autenticazione TLS reciproca. È possibile convalidare i certificati presentati dal client di connessione e controllare le proprietà del certificato in base ai valori desiderati usando le espressioni dei criteri.

Per informazioni sulla protezione dell'accesso al servizio back-end di un'API tramite certificati client (ovvero da Gestione API al back-end), vedere Come proteggere i servizi back-end usando l'autenticazione con certificati client.

Per una panoramica concettuale dell'autorizzazione API, vedere Autenticazione e autorizzazione per le API in Gestione API.

Opzioni di certificati

Per la convalida dei certificati, Gestione API può eseguire un controllo rispetto ai certificati gestiti nell'istanza di Gestione API. Se si sceglie di usare Gestione API per gestire i certificati client, sono disponibili le opzioni seguenti:

• Fare riferimento a un certificato gestito in Azure Key Vault
• Aggiungere un file del certificato direttamente in Gestione API

È consigliabile usare i certificati dell'insieme di credenziali delle chiavi perché consentono di migliorare la sicurezza di Gestione API:

• I certificati archiviati negli insiemi di credenziali delle chiavi possono essere riutilizzati nei servizi
• È possibile applicare criteri di accesso granulari ai certificati archiviati negli insiemi di credenziali delle chiavi
• I certificati aggiornati nell'insieme di credenziali delle chiavi vengono ruotati automaticamente in Gestione API. Dopo l'aggiornamento nell'insieme di credenziali delle chiavi, un certificato in Gestione API viene aggiornato entro 4 ore. È anche possibile aggiornare manualmente il certificato usando il portale di Azure o tramite l'API REST di gestione.

Prerequisiti

• Se non è ancora stata creata un'istanza del servizio Gestione API, vedere Creare un'istanza del servizio Gestione API.

• È necessario accedere al certificato e alla password per la gestione in un insieme di credenziali delle chiavi di Azure o caricare il certificato nel servizio Gestione API. Il certificato deve essere in formato CER o PFX. Sono consentiti i certificati autofirmati.

  Se si usa un certificato autofirmato, installare anche certificati CA radice attendibili e intermedi nell'istanza di Gestione API.

  Nota

  I certificati CA per la convalida dei certificati non sono supportati nel livello A consumo.

Prerequisiti per l'integrazione dell'insieme di credenziali delle chiavi

Nota

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

1. Se non si ha già un insieme di credenziali delle chiavi, crearne uno. Per la procedura per la creazione di un insieme di credenziali delle chiavi, vedere Avvio rapido: creare un insieme di credenziali delle chiavi usando il portale di Azure.

   Per creare o importare un certificato nell'insieme di credenziali delle chiavi, vedere Avvio rapido: impostare e recuperare un certificato da Azure Key Vault usando il portale di Azure.

2. Abilitare un'identità gestita assegnata dal sistema o assegnata dall'utente nell'istanza di Gestione API.

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 ed Elenco, quindi selezionare Avanti.
   4. Nella scheda Entità di sicurezza, Seleziona entità di sicurezza , 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 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 certificati Key Vault.
   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.

Requisiti per il firewall di Key Vault

Se il firewall di Key Vault è abilitato nell'insieme di credenziali delle chiavi, sono necessari requisiti aggiuntivi:

• Per accedere all'insieme di credenziali delle chiavi, è necessario usare l'identità gestita assegnata dal sistema dell'istanza di Gestione API.

• Nel firewall di Key Vault, abilitare l'opzione Consenti ai servizi Microsoft attendibili di ignorare questo firewall.

• Assicurarsi che l'indirizzo IP del client locale sia autorizzato ad accedere temporaneamente all'insieme di credenziali delle chiavi mentre si seleziona un certificato o un segreto da aggiungere a Gestione API di Azure. Per altre informazioni, vedere Configurare le impostazioni di rete di Azure Key Vault.

  Dopo aver completato la configurazione, è possibile bloccare l'indirizzo client nel firewall di insieme di credenziali delle chiavi.

Requisiti della rete virtuale

Se l'istanza di Gestione API viene distribuita in una rete virtuale, configurare anche le impostazioni di rete seguenti:

• Abilitare un endpoint di servizio in Azure Key Vault nella subnet di Gestione API.
• Configurare una regola del gruppo di sicurezza di rete (NSG) per consentire il traffico in uscita ai tag del servizio AzureKeyVault e AzureActiveDirectory.

Per informazioni dettagliate, vedere Configurazione di rete durante la configurazione di Gestione API di Azure in una rete virtuale.

Aggiungere un certificato dell'insieme di credenziali delle chiavi

Vedere Prerequisiti per l'integrazione dell'insieme di credenziali delle chiavi.

Importante

Quando si aggiunge un certificato dell'insieme di credenziali delle chiavi all'istanza di Gestione API, è necessario disporre delle autorizzazioni per elencare i segreti dell'insieme di credenziali delle chiavi.

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 aggiungere un certificato dell'insieme di credenziali delle chiavi a Gestione API:

1. Nel portale di Azure accedere all'istanza di Gestione API.

2. In Sicurezza, selezionare Certificati.

3. Selezionare Certificati>+ Aggiungi.

4. In ID, immettere il nome desiderato.

5. In Certificato, selezionare insieme di credenziali delle chiavi.

6. Immettere l'identificatore di un certificato dell'insieme di credenziali delle chiavi oppure scegliere Seleziona per selezionare un certificato da un insieme di credenziali delle chiavi.

   Importante

   Se si immette manualmente un identificatore del certificato dell'insieme di credenziali delle chiavi, assicurarsi che non disponga di informazioni sulla versione. In caso contrario, il certificato non verrà ruotato automaticamente in Gestione API dopo un aggiornamento nell'insieme di credenziali delle chiavi.

7. In Identità client, selezionare un'identità gestita assegnata dal sistema o assegnata da un utente esistente. Di seguito viene descritto come aggiungere o modificare le identità gestite nel servizio Gestione API.

   Nota

   L'identità deve disporre delle autorizzazioni per ottenere ed elencare il certificato dell'insieme di credenziali delle chiavi. Se non è già stato configurato l'accesso all'insieme di credenziali delle chiavi, Gestione API richiede di configurare automaticamente l'identità con le autorizzazioni necessarie.

8. Selezionare Aggiungi.

   

9. Seleziona Salva.

Caricamento di un certificato

Per caricare un certificato client in Gestione API:

1. Nel portale di Azure accedere all'istanza di Gestione API.

2. In Sicurezza, selezionare Certificati.

3. Selezionare Certificati>+ Aggiungi.

4. In ID, immettere il nome desiderato.

5. In Certificato, selezionare Personalizzato.

6. Sfogliare per selezionare file con estensione .pfx del certificato e immettere la password.

7. Selezionare Aggiungi.

   

8. Seleziona Salva.

Nota

Se si vuole usare il certificato solo per autenticare il client con Gestione API, è possibile caricare un file CER.

Abilitare l'istanza di Gestione API per ricevere e verificare i certificati client

Livello Developer, Basic, Standard o Premium

Per ricevere e verificare i certificati client tramite HTTP/2 nei livelli Developer, Basic, Standard o Premium, è necessario abilitare l'impostazione Negozia certificato client nel riquadro Dominio personalizzato come riportato in basso.

Consumo, Livello Basic v2, Standard v2

Per ricevere e verificare i certificati client nel livello Consumo, Basic v2 o Standard v2, è necessario abilitare l'impostazione Richiedi certificato client nel pannello Domini personalizzati, come illustrato di seguito.

Criteri per convalidare i certificati client

Usare il criterio validate-client-certificate per convalidare uno o più attributi di un certificato client usato per accedere alle API ospitate nell'istanza di Gestione API.

Configurare i criteri per convalidare uno o più attributi, tra cui autorità di certificazione, oggetto, identificazione personale, se il certificato viene convalidato rispetto all'elenco di revoche online e altri elementi.

Convalida del certificato con variabili di contesto

È anche possibile creare espressioni di criteri con la variabile context per controllare i certificati client. Gli esempi nelle sezioni seguenti illustrano le espressioni che usano la proprietà context.Request.Certificate e altre proprietà context.

Nota

L'autenticazione reciproca dei certificati potrebbe non funzionare correttamente quando l'endpoint del gateway di Gestione API viene esposto tramite il gateway applicazione. Questo perché il gateway applicazione funziona come servizio di bilanciamento del carico di livello 7, stabilendo una connessione SSL distinta con il servizio back-end Gestione API. Di conseguenza, il certificato collegato dal client nella richiesta HTTP iniziale non verrà inoltrato a Gestione API. Tuttavia, come soluzione alternativa, è possibile trasmettere il certificato usando l'opzione delle variabili del server. Per istruzioni dettagliate, vedere Variabili del server di autenticazione reciproca.

Importante

• A partire da maggio 2021, la proprietà context.Request.Certificate richiede solo il certificato quando hostnameConfiguration dell'istanza di Gestione API imposta la proprietà negotiateClientCertificate su True. Per impostazione predefinita, negotiateClientCertificate è impostato su False.
• Se la rinegoziazione TLS è disabilitata nel client, è possibile che vengano visualizzati errori TLS quando si richiede il certificato usando la proprietà context.Request.Certificate. In questo caso, abilitare le impostazioni di rinegoziazione TLS nel client.
• La rinegoziazione della certificazione non è supportata nei livelli di Gestione API v2.

Controllo dell'autorità di certificazione e del soggetto

È possibile configurare i criteri riportati di seguito per controllare l'autorità di certificazione e il soggetto di un certificato client:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Nota

Per disabilitare il controllo dell'elenco di revoche di certificati, usare context.Request.Certificate.VerifyNoRevocation() anziché context.Request.Certificate.Verify(). Se il certificato client è autofirmato, i certificati CA radice (o intermedi) devono essere caricati in Gestione API per il funzionamento di context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation().

Controllo dell'identificazione personale

I criteri riportati di seguito possono essere configurati per controllare l'identificazione personale del certificato client:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Nota

Per disabilitare il controllo dell'elenco di revoche di certificati, usare context.Request.Certificate.VerifyNoRevocation() anziché context.Request.Certificate.Verify(). Se il certificato client è autofirmato, i certificati CA radice (o intermedi) devono essere caricati in Gestione API per il funzionamento di context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation().

Controllo di un'identificazione personale rispetto ai certificati caricati in Gestione API

L'esempio seguente illustra come controllare l'identificazione personale di un certificato client rispetto a certificati caricati in Gestione API:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Nota

Per disabilitare il controllo dell'elenco di revoche di certificati, usare context.Request.Certificate.VerifyNoRevocation() anziché context.Request.Certificate.Verify(). Se il certificato client è autofirmato, i certificati CA radice (o intermedi) devono essere caricati in Gestione API per il funzionamento di context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation().

Suggerimento

Il problema del deadlock del certificato client descritto in questo articolo può manifestarsi in diversi modi, ad esempio il blocco delle richieste, le richieste generano un codice di stato 403 Forbidden dopo il timeout, context.Request.Certificate è null. Questo problema in genere interessa le richieste POST e PUT con una lunghezza di contenuto di circa 60 kB o superiore. Per evitare che si verifichi questo problema, attivare l'impostazione "Negozia certificato client" per i nomi host desiderati nel pannello "Domini personalizzati", come illustrato nella prima immagine di questo documento. Questa funzionalità non è disponibile nel livello A consumo.

Passaggi successivi

• Come proteggere i servizi back-end usando l'autenticazione con certificati client
• Come aggiungere un certificato CA personalizzato in Gestione API di Azure
• Informazioni sui criteri in Gestione API