Condividi tramite


Usare i valori denominati nei criteri di Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

I criteri di Gestione API sono una potente funzionalità del sistema e consentono al server di pubblicazione di modificare il comportamento dell'API tramite la configurazione. I criteri sono una raccolta di istruzioni che vengono eseguite in modo sequenziale sulla richiesta o la risposta di un'API. Le istruzioni dei criteri possono essere costruite usando valori di testo letterali, espressioni di criteri e valori denominati.

I valori denominati sono una raccolta globale di coppie nome/valore in ogni istanza di Gestione API. Non esiste alcun limite imposto per il numero di elementi nella raccolta. I valori denominati possono essere usati per gestire valori stringa costanti e segreti all'interno dell'intera configurazione e di tutti i criteri delle API.

Valori denominati nel portale di Azure

Tipi valore

Tipo Descrizione
Normale Stringa letterale o espressione di criteri
Segreto Stringa letterale o espressione di criteri crittografata da Gestione API
Key vault Identificatore di un segreto archiviato in un insieme di credenziali delle chiavi di Azure.

I valori o i segreti normali possono contenere espressioni di criteri. Ad esempio, l'espressione @(DateTime.Now.ToString()) restituisce una stringa contenente la data e l'ora correnti.

Per informazioni dettagliate sugli attributi dei valori denominati, vedere Informazioni di riferimento sull'API REST di Gestione API.

Segreti di Key Vault

I valori dei segreti possono essere archiviati come stringhe crittografate in Gestione API (segreti personalizzati) o facendo riferimento ai segreti in Azure Key Vault.

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

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

Nota

I segreti archiviati in Azure Key Vault devono essere compresi tra 1 e 4096 caratteri, perché Gestione API non possono recuperare valori che superano questo limite.

Prerequisiti

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

Nota

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

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 o modificare un valore denominato

Aggiungere un segreto dell'insieme di credenziali delle chiavi a Gestione API

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

Importante

Quando si aggiunge un segreto 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 segreto dell'insieme di credenziali delle chiavi in Gestione API, prestare attenzione a non eliminare il segreto, l'insieme di credenziali delle chiavi o l'identità gestita usata per accedere all'insieme di credenziali delle chiavi.

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

  2. In API selezionare Valori denominati>+Aggiungi.

  3. Immettere un identificatore Nome e immettere un Nome visualizzato usato per fare riferimento alla proprietà nei criteri.

  4. In Tipo valore selezionare Insieme di credenziali delle chiavi.

  5. Immettere l'identificatore di un segreto dell'insieme di credenziali delle chiavi (senza versione) oppure scegliere Seleziona per selezionare un segreto da un insieme di credenziali delle chiavi.

    Importante

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

  6. In Identità client selezionare un'identità gestita assegnata dal sistema o 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 i segreti 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.

  7. Aggiungere uno o più tag facoltativi per organizzare i valori denominati, quindi selezionare Salva.

  8. Seleziona Crea.

    Aggiungere il valore del segreto dell'insieme di credenziali delle chiavi

Aggiungere un valore normale o segreto a Gestione API

  1. Nel portale di Azure accedere all'istanza di Gestione API.
  2. In API selezionare Valori denominati>+Aggiungi.
  3. Immettere un identificatore Nome e immettere un Nome visualizzato usato per fare riferimento alla proprietà nei criteri.
  4. In Tipo valore selezionare Normale o Secreto.
  5. In Valore immettere una stringa o un'espressione di criteri.
  6. Aggiungere uno o più tag facoltativi per organizzare i valori denominati, quindi selezionare Salva.
  7. Seleziona Crea.

Dopo aver creato il valore denominato, è possibile modificarlo selezionando il nome. Se si modifica il nome visualizzato, tutti i criteri che fanno riferimento a tale valore denominato vengono aggiornati automaticamente con il nuovo nome.

Usare un valore denominato

Gli esempi in questa sezione usano i valori denominati illustrati nella tabella seguente.

Nome valore Segreto
ContosoHeader TrackingId Falso
ContosoHeaderValue •••••••••••••••••••••• Vero
ExpressionProperty @(DateTime.Now.ToString()) Falso
ContosoHeaderValue2 This is a header value. Falso

Per usare un valore denominato in un criterio, inserirne il nome visualizzato all'interno di parentesi graffe doppie, ad esempio {{ContosoHeader}}, come illustrato nell'esempio seguente:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

In questo esempio, la proprietà ContosoHeader viene usata come nome di un'intestazione in un criterio set-header e la proprietà ContosoHeaderValue viene usata come valore di tale intestazione. Quando questo criterio viene valutato durante una richiesta o una risposta al gateway di Gestione API, {{ContosoHeader}} e {{ContosoHeaderValue}} vengono sostituiti dai rispettivi valori.

I valori denominati possono essere usati come valori completi di attributo o di elemento, come illustrato nell'esempio precedente, ma possono anche essere inseriti all'interno di un'espressione di testo o combinati con una parte di un'espressione di testo, come illustrato nell'esempio seguente:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

I valori denominati possono anche contenere espressioni di criteri. Nell'esempio seguente viene usata l'espressione ExpressionProperty.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Quando questo criterio viene valutato, {{ExpressionProperty}} viene sostituito dal valore corrispondente, @(DateTime.Now.ToString()). Poiché il valore è un'espressione di criteri, l'espressione viene valutata e il criterio passa alla fase di esecuzione.

È possibile eseguirne i test nel portale di Azure o nel portale per sviluppatori chiamando un'operazione il cui ambito contiene criteri con valori denominati. Nell'esempio seguente viene chiamata un'operazione che contiene i due criteri di esempio precedenti set-header con valori denominati. La risposta contiene due intestazioni personalizzate che vengono configurate tramite criteri con valori denominati.

Testare la risposta API

Se si osserva la traccia API in uscita relativa a una chiamata che include i due criteri con valori denominati degli esempi precedenti, è possibile vedere i due criteri set-header con i valori denominati inseriti, nonché la valutazione delle espressioni dei criteri per il valore denominato che contiene l'espressione.

Traccia di Controllo API

L'interpolazione di stringhe può essere usata anche con valori denominati.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Il valore per CustomHeader sarà The URL encoded value is This+is+a+header+value..

Attenzione

Se un criterio fa riferimento a un segreto in Azure Key Vault, il valore dell'insieme di credenziali delle chiavi sarà visibile agli utenti che hanno accesso alle sottoscrizioni abilitate per traccia delle richieste API.

Sebbene i valori denominati possano contenere espressioni di criteri, non possono contenere altri valori denominati. Se il testo contenente un riferimento a un valore denominato viene usato per un valore, ad esempio Text: {{MyProperty}}, tale riferimento non verrà risolto e sostituito.

Eliminare un valore denominato

Per eliminare un valore denominato, selezionare il nome e quindi selezionare Elimina dal menu di scelta rapida (...).

Importante

Se in un criterio di Gestione API si fa riferimento al valore denominato, sarà possibile eliminarlo solo dopo aver rimosso il valore denominato da tutti i criteri che lo usano.

Passaggi successivi