Sottoscrizioni in Gestione API di Azure

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

In Gestione API di Azure, le sottoscrizioni sono il modo più comune per consentire ai consumer di API di accedere alle API pubblicate tramite un'istanza di Gestione API. Questo articolo offre una panoramica sul concetto.

Nota

Una sottoscrizione di Gestione API viene usata specificamente per chiamare le API tramite Gestione API usando una chiave di sottoscrizione. Non è uguale a una sottoscrizione di Azure.

Cosa sono le sottoscrizioni?

Pubblicando API tramite Gestione API, è possibile proteggere facilmente l'accesso alle API usando le chiavi di abbonamento. Gli sviluppatori che devono utilizzare le API pubblicate devono includere una chiave di abbonamento valida nelle richieste HTTP quando effettuano chiamate a tali API. Senza una chiave di abbonamento valida, le chiamate vengono:

  • Immediatamente rifiutate dal gateway di Gestione API.
  • Non inoltrate ai servizi di back-end.

Per accedere alle API, gli sviluppatori necessitano di un abbonamento e di una chiave di abbonamento. Una sottoscrizione è un contenitore denominato per una coppia di chiavi di sottoscrizione.

Inoltre,

  • Gli sviluppatori possono ottenere sottoscrizioni senza richiedere l'approvazione da parte degli editori di API.
  • Gli editori delle API possono creare sottoscrizioni direttamente, per i consumer delle API.

Suggerimento

Gestione API supporta anche altri meccanismi per proteggere l'accesso alle API, inclusi gli esempi seguenti:

Gestire le chiavi di sottoscrizione

La rigenerazione regolare delle chiavi è una precauzione di sicurezza comune. Analogamente alla maggior parte dei servizi di Azure che richiedono una chiave di sottoscrizione, Gestione API genera chiavi in coppie. Ogni applicazione che usa il servizio può passare dalla chiave A alla chiave B e rigenerare la chiave A con interruzioni minime e viceversa.

L'impostazione di chiavi specifiche invece di rigenerare quelle può essere eseguita richiamando la sottoscrizione di Gestione API di Azure - Creare o aggiornare l'API REST di Azure. In particolare, properties.primaryKey e/o properties.secondaryKey devono essere impostati nel corpo della richiesta HTTP.

Nota

  • Gestione API non offre funzionalità predefinite per gestire il ciclo di vita delle chiavi di sottoscrizione, ad esempio l'impostazione delle date di scadenza o la rotazione automatica delle chiavi. È possibile sviluppare flussi di lavoro per automatizzare questi processi usando strumenti come Azure PowerShell o Gli SDK di Azure.
  • Per applicare l'accesso limitato nel tempo alle API, gli autori di API possono usare criteri con chiavi di sottoscrizione o usare un meccanismo che fornisce una scadenza predefinita, ad esempio l'autenticazione basata su token.

Ambito delle sottoscrizioni

Le sottoscrizioni possono essere associate a vari ambiti: prodotto, tutte le API o un'API singola.

Sottoscrizioni per un prodotto

In genere, le sottoscrizioni in Gestione API sono state associate a un singolo ambito prodotto. Sviluppatori:

  • È stato trovato l'elenco dei prodotti nel portale per sviluppatori.
  • Richieste di sottoscrizione inviate per i prodotti che volevano usare.
  • Usare le chiavi in tali sottoscrizioni (approvate automaticamente o dagli editori dell'API) per accedere a tutte le API nel prodotto.

Attualmente, il portale per sviluppatori mostra solo le sottoscrizioni dell'ambito del prodotto nella sezione Profilo utente.

Sottoscrizioni prodotto

Sottoscrizioni per tutte le API o un'API singola

È anche possibile creare chiavi che concedono l'accesso a:

  • Una singola API o
  • Tutte le API all'interno di un'istanza di Gestione API.

In questi casi non è necessario creare un prodotto e aggiungervi prima le API.

Sottoscrizione a tutti gli accessi

Ogni istanza di Gestione API include una sottoscrizione integrata di tutti gli accessi che concede l'accesso a tutte le API. Questa sottoscrizione con ambito servizio semplifica il test e il debug delle API all'interno della console di test.

Avviso

La sottoscrizione all-access consente l'accesso a ogni API nell'istanza di Gestione API e deve essere usata solo dagli utenti autorizzati. Non usare mai questa sottoscrizione per l'accesso all'API di routine o incorporare la chiave di sottoscrizione all-access nelle app client.

Nota

Se si usa una sottoscrizione con ambito API, una sottoscrizione all-API o la sottoscrizione predefinita all-access, i criteri configurati nell'ambito del prodotto non vengono applicati alle richieste da tale sottoscrizione.

Sottoscrizioni autonome

Gestione API consente anche sottoscrizioni autonome, che non sono associate a un account per sviluppatore. Questa funzionalità risulta utile in scenari simili a diversi sviluppatori o team che condividono una sottoscrizione.

La creazione di una sottoscrizione senza assegnare un proprietario lo rende una sottoscrizione autonoma. Per concedere agli sviluppatori e al resto del team l'accesso alla chiave di sottoscrizione autonoma:

  • Condividere manualmente la chiave di sottoscrizione.
  • Usare un sistema personalizzato per rendere disponibile la chiave di sottoscrizione al team.

Creare e gestire sottoscrizioni nel portale di Azure

Gli autori di API possono creare sottoscrizioni direttamente nel portale di Azure.

Quando viene creata nel portale, una sottoscrizione si trova nello stato Attivo, ovvero un sottoscrittore può chiamare un'API associata usando una chiave di sottoscrizione valida. È possibile modificare lo stato della sottoscrizione in base alle esigenze. Ad esempio, è possibile sospendere, annullare o eliminare qualsiasi sottoscrizione (inclusa la sottoscrizione integrata all-access) per impedire l'accesso all'API.

Usare una chiave di sottoscrizione

Un sottoscrittore può usare una chiave di sottoscrizione di Gestione API in uno dei due modi seguenti:

  • Aggiungere l'intestazione HTTP Ocp-Apim-Subscription-Key alla richiesta, passando il valore di una chiave di sottoscrizione valida.

  • Includere il parametro di query subscription-key e un valore valido nell'URL. Il parametro di query viene controllato solo se l'intestazione non è presente.

Suggerimento

Ocp-Apim-Subscription-Key è il nome predefinito dell'intestazione della chiave di sottoscrizione e subscription-key è il nome predefinito del parametro di query. Se necessario, è possibile modificare questi nomi nelle impostazioni per ogni API. Ad esempio, nel portale aggiornare questi nomi nella scheda Impostazioni di un'API.

Nota

Se incluso in un'intestazione di richiesta o in un parametro di query, la chiave di sottoscrizione per impostazione predefinita viene passata al back-end e può essere esposta nei log di monitoraggio back-end o in altri sistemi. Se si tratta di dati sensibili, è possibile configurare un criterio alla fine della sezione inbound per rimuovere l'intestazione della chiave di sottoscrizione (set-header) o il parametro di query (set-query-parameter).

Abilitare o disabilitare i requisiti di sottoscrizione per l'accesso all'API o al prodotto

Per impostazione predefinita, quando si crea un'API, è necessaria una chiave di sottoscrizione per l'accesso all'API. Analogamente, quando si crea un prodotto, per impostazione predefinita è necessaria una chiave di sottoscrizione per accedere a qualsiasi API aggiunta al prodotto. In determinati scenari, un editore di API potrebbe voler pubblicare un prodotto o un'API specifica nel pubblico senza il requisito delle sottoscrizioni. Sebbene un server di pubblicazione possa scegliere di abilitare l'accesso non sicuro (anonimo) a determinate API, è consigliabile configurare un altro meccanismo per proteggere l'accesso client.

Attenzione

Prestare attenzione quando si configura un prodotto o un'API che non richiede una sottoscrizione. Questa configurazione può essere eccessivamente permissiva e può rendere un'API più vulnerabile a determinate minacce alla sicurezza delle API.

Nota

Per i prodotti aperti è disabilitata l'impostazione Richiede sottoscrizione , il che significa che gli utenti non devono sottoscriverlo. Per questo motivo, i prodotti aperti non vengono visualizzati nella pagina Prodotti del portale per sviluppatori.

È possibile disabilitare il requisito di sottoscrizione al momento della creazione di un'API o di un prodotto o in una data successiva.

Per disabilitare il requisito di sottoscrizione tramite il portale:

  • Disabilitare il requisito per il prodotto: nella pagina Impostazioni del prodotto disabilitare Richiede sottoscrizione
  • Disabilitare il requisito per l'API: nella pagina Impostazioni dell'API disabilitare la sottoscrizione richiesta.

Dopo aver disabilitato il requisito della sottoscrizione, è possibile accedere all'API o alle API selezionate senza una chiave di sottoscrizione.

Gestione API gestisce le richieste con o senza chiavi di sottoscrizione

Richiesta API con una chiave di abbonamento

Quando Gestione API riceve una richiesta API da un client con una chiave di abbonamento, gestisce la richiesta in base alle regole seguenti:

  1. Verificare se è una chiave valida associata a un abbonamento attiva, sia:

    • Un abbonamento con ambito all'API
    • Un abbonamento con ambito a un prodotto assegnato all'API
    • Un abbonamento con ambito per tutte le API
    • Un abbonamento con ambito servizio (abbonamento predefinito di tutti gli accessi)

    Se viene fornita una chiave valida per un abbonamento attivo in un ambito appropriato, l'accesso è consentito. I criteri vengono applicati a seconda della configurazione della definizione dei criteri nell'ambito.

  2. In caso contrario, l'accesso viene negato (errore di accesso negato 401).

Richiesta API senza una chiave di abbonamento

Quando Gestione API riceve una richiesta API da un client senza una chiave di abbonamento, gestisce la richiesta in base alle regole seguenti:

  1. Verificare prima di tutto l'esistenza di un prodotto che include l'API, ma non richiede un abbonamento (un prodotto aperto). Se il prodotto aperto esiste, gestire la richiesta nel contesto delle API, dei criteri e delle regole di accesso configurate per il prodotto. Un'API può essere associata alla maggior parte di un prodotto aperto.
  2. Se non viene trovato un prodotto aperto incluso l'API, verificare se l'API richiede un abbonamento. Se una abbonamento non è necessario, gestire la richiesta nel contesto di tale API e operazione.
  3. Se non viene trovato alcun prodotto o API configurato, l'accesso viene negato (errore di accesso negato 401).

Tabella di riepilogo

La tabella seguente riepiloga il modo in cui il gateway gestisce le richieste API con o senza chiavi di sottoscrizione in scenari diversi. Vengono annotate le configurazioni che potrebbero abilitare l'accesso non intenzionale all'API anonima.

Tutti i prodotti assegnati all'API richiedono una sottoscrizione L'API richiede una sottoscrizione Chiamata API con chiave di sottoscrizione Chiamata API senza chiave di sottoscrizione Scenari tipici
✔️ ✔️ Accesso consentito:

• Chiave con ambito prodotto
• Chiave con ambito API
• Tutte le API con ambito chiave
• Chiave con ambito servizio

Accesso negato:

• Altra chiave non con ambito per il prodotto o l'API applicabile		 Accesso negato Accesso alle API protette tramite una sottoscrizione con ambito prodotto o con ambito API
✔️ ❌ Accesso consentito:

• Chiave con ambito prodotto
• Chiave con ambito API
• Tutte le API con ambito chiave
• Chiave con ambito servizio

Accesso negato:

• Altra chiave non con ambito per il prodotto o l'API applicabile		 Accesso consentito (contesto API) • Accesso alle API protette con sottoscrizione con ambito prodotto

• Accesso anonimo all'API. Se l'accesso anonimo non è previsto, configurare i criteri a livello di API per applicare l'autenticazione e l'autorizzazione.
❌1 ✔️ Accesso consentito:

• Chiave con ambito prodotto
• Chiave con ambito API
• Tutte le API con ambito chiave
• Chiave con ambito servizio

Accesso negato:

• Altra chiave non con ambito per il prodotto o l'API applicabile		 Accesso consentito (contesto di prodotto aperto) • Accesso API protetto con sottoscrizione con ambito API

• Accesso anonimo all'API. Se l'accesso anonimo non è previsto, configurare con i criteri di prodotto per applicare l'autenticazione e l'autorizzazione
❌1 ❌ Accesso consentito:

• Chiave con ambito prodotto
• Chiave con ambito API
• Tutte le API con ambito chiave
• Chiave con ambito servizio

Accesso negato:

• Altra chiave non con ambito per il prodotto o l'API applicabile		 Accesso consentito (contesto di prodotto aperto) Accesso anonimo all'API. Se l'accesso anonimo non è previsto, configurare con i criteri di prodotto per applicare l'autenticazione e l'autorizzazione

1 Esiste un prodotto aperto associato all'API.

Considerazioni

  • L'accesso API in un contesto di prodotto è lo stesso, indipendentemente dal fatto che il prodotto venga pubblicato o meno. Annullare la pubblicazione del prodotto lo nasconde dal portale per sviluppatori, ma non invalida le chiavi di sottoscrizione nuove o esistenti.
  • Anche se un prodotto o un'API non richiede una sottoscrizione, è comunque possibile usare una chiave valida da una sottoscrizione attiva che consente l'accesso al prodotto o all'API.
  • L'accesso aòò'API "context" indica i criteri e i controlli di accesso applicati a un determinato ambito (ad esempio, API o prodotto).

Passaggi successivi

Per altre informazioni su Gestione API: