Limitazione dell'accesso alle API con le chiavi API

OpenAPI   |  gRPC

Puoi utilizzare le chiavi API per limitare l'accesso a metodi API specifici o a tutti i metodi di un'API. Questa pagina descrive come limitare l'accesso alle API ai client che hanno una chiave API e mostra anche come creare una chiave API.

Il Extensible Service Proxy (ESP) utilizza l'API Service Control per convalidare una chiave API e la sua associazione all' API abilitata di un progetto. Se imposti un requisito della chiave API nella tua API, le richieste al metodo, alla classe o all'API protetti vengono rifiutate a meno che non abbiano una chiave generata nel tuo progetto o in altri progetti appartenenti a sviluppatori a cui hai concesso l'accesso per abilitare la tua API. Il progetto in cui è stata creata la chiave API non viene registrato e non viene aggiunto all'intestazione della richiesta. Tuttavia, puoi visualizzare il Google Cloud progetto a cui è associato un client in Endpoint > Servizi, come descritto in Filtrare per un progetto consumer specifico.

Per informazioni sul Google Cloud progetto in cui deve essere creata una chiave API in, vedi Condividere le API protette dalla chiave API.

Limitare l'accesso a tutti i metodi API

Per richiedere una chiave API per accedere a tutti i metodi di un'API:

OpenAPI 2.0

1. Apri il file openapi.yaml del tuo progetto in un editor di testo.
2. In securityDefinitions:, aggiungi i valori api_key: apiKey, key, query come mostrato nel seguente snippet di codice campione:
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

   In questo modo viene stabilito uno "schema di sicurezza" denominato api_key, che puoi utilizzare per proteggere l'API. Per altre opzioni di definizione di api_key, consulta Limitazioni della definizione della chiave API.

3. Aggiungi api_key: [] alla direttiva security a livello principale del file (senza rientro o nidificazione). Potresti dover aggiungere la direttiva security o potrebbe essere già presente:

   security:
     - api_key: []

   Questa direttiva applica lo schema di sicurezza api_key a tutti i metodi del file. Non inserire nulla tra le parentesi. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

OpenAPI 3.x

1. Apri il file openapi.yaml del tuo progetto in un editor di testo.
2. In components.securitySchemes:, aggiungi quanto segue:

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   In questo modo viene stabilito uno "schema di sicurezza" denominato api_key, che puoi utilizzare per proteggere l'API.

3. Aggiungi api_key: [] alla direttiva security a livello principale del file (senza rientro o nidificazione):

   security:
     - api_key: []

   Questa direttiva applica lo schema di sicurezza api_key a tutti i metodi del file.

Limitare l'accesso a metodi API specifici

Per richiedere una chiave API per un metodo specifico:

OpenAPI 2.0

1. Apri il file openapi.yaml del tuo progetto in un editor di testo.
2. Aggiungi una direttiva di sicurezza vuota a livello principale del file (senza rientro o nidificazione) per applicarla all'intera API:

   security: []

3. In securityDefinitions:, aggiungi i valori api_key: apiKey, key, query come mostrato nel seguente snippet di codice campione:
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

   In questo modo viene stabilito uno "schema di sicurezza" denominato api_key, che puoi utilizzare per proteggere l'API. Per altre opzioni di definizione di api_key, consulta Limitazioni della definizione della chiave API.

4. Aggiungi api_key: [] alla direttiva security nella definizione del metodo:

   ...
   paths:
     "/echo":
       post:
         description: "Echo back a given message."
         operationId: "echo"
         security:
         - api_key: []
         produces:
         ...

   Questa direttiva applica lo schema di sicurezza api_key al metodo. Non inserire nulla tra le parentesi. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

OpenAPI 3.x

1. Apri il file openapi.yaml del tuo progetto in un editor di testo.
2. Aggiungi una direttiva di sicurezza vuota a livello principale del file (senza rientro o nidificazione) per applicarla all'intera API:

   security: []

3. In components.securitySchemes:, aggiungi quanto segue:

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   In questo modo viene stabilito uno "schema di sicurezza" denominato api_key, che puoi utilizzare per proteggere l'API.

4. Aggiungi api_key: [] alla direttiva security nella definizione del metodo:

   ...
   paths:
     /echo:
       post:
         description: "Echo back a given message."
         operationId: "echo"
         security:
         - api_key: []
         requestBody:
         ...

   Questa direttiva applica lo schema di sicurezza api_key al metodo.

Rimuovere la limitazione della chiave API per un metodo

Per disattivare la convalida della chiave API per un metodo specifico anche quando hai limitato l'accesso alle API per l'API:

OpenAPI 2.0

1. Apri il file openapi.yaml del tuo progetto in un editor di testo.
2. Aggiungi una direttiva security vuota nella definizione del metodo:

     ...
     paths:
       "/echo":
         post:
           description: "Echo back a given message."
           operationId: "echo"
           security: []
           produces:
           ...

OpenAPI 3.x

1. Apri il file openapi.yaml del tuo progetto in un editor di testo.
2. Aggiungi una direttiva security vuota nella definizione del metodo:

     ...
     paths:
       /echo:
         post:
           description: "Echo back a given message."
           operationId: "echo"
           security: []
           requestBody:
           ...

Chiamare un'API utilizzando una chiave API

Se un'API o un metodo API richiede una chiave API, fornisci la chiave utilizzando un parametro di query denominato key, come mostrato nel seguente esempio di curl:

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

dove ENDPOINTS_HOST e ENDPOINTS_KEY sono variabili di ambiente che contengono rispettivamente il nome host dell'API e la chiave API.

Condividere le API protette dalla chiave API

Le chiavi API sono associate al Google Cloud progetto in cui sono state create. Se hai deciso di richiedere una chiave API per la tua API, il Google Cloud progetto in cui viene creata la chiave API dipende da le risposte alle seguenti domande:

• Devi distinguere tra gli utenti che chiamano la tua API in modo da poter utilizzare le funzionalità di Endpoints come quote?
• Tutti gli utenti che chiamano la tua API hanno i propri Google Cloud progetti?
• Devi configurare limitazioni diverse per le chiavi API restrictions?

Puoi utilizzare il seguente albero decisionale come guida per decidere in quale Google Cloud progetto creare la chiave API.

Concedere l'autorizzazione per abilitare l'API

Quando devi distinguere tra gli utenti che chiamano la tua API e ogni utente ha il proprio Google Cloud progetto, puoi concedere alle entità l'autorizzazione per abilitare l'API nel proprio Google Cloud progetto. In questo modo, gli utenti della tua API possono creare la propria chiave API da utilizzare con la tua API.

Supponiamo, ad esempio, che il tuo team abbia creato un'API per l'uso interno da parte di vari programmi client della tua azienda e che ogni programma client abbia il proprio Google Cloud progetto. Per distinguere tra gli utenti che chiamano la tua API, la chiave API per ogni utente deve essere creata in un Google Cloud progetto diverso. Puoi concedere ai tuoi colleghi l'autorizzazione per abilitare l'API nel Google Cloud progetto a cui è associato il programma client.

Per consentire agli utenti di creare la propria chiave API:

1. Nel Google Cloud progetto in cui è configurata la tua API, concedi a ogni utente l' autorizzazione per abilitare la tua API.
2. Contatta gli utenti e informa che possono abilitare la tua API nel proprio Google Cloud progetto e creare una chiave API.

Creare unprogetto separato Google Cloud per ogni utente che chiama

Quando devi distinguere tra gli utenti che chiamano la tua API e non tutti gli utenti che chiamano hanno Google Cloud progetti, puoi creare un Google Cloud progetto e una chiave API separati per ogni utente che chiama. Prima di creare i progetti, valuta attentamente i nomi dei progetti in modo da poter identificare facilmente il chiamante associato al progetto.

Supponiamo, ad esempio, che tu abbia clienti esterni della tua API e che tu non abbia idea di come siano stati creati i programmi client che chiamano la tua API. Forse alcuni client utilizzano Google Cloud servizi e hanno un Google Cloud progetto, e forse alcuni non lo fanno. Per distinguere tra gli utenti che chiamano, devi creare un progetto e una chiave API separati Google Cloud per ogni utente che chiama.

Per creare un Google Cloud progetto e una chiave API separati per ogni utente che chiama:

1. Crea un progetto separato per ogni utente che chiama.
2. In ogni progetto, abilita la tua API e crea una chiave API.
3. Fornisci la chiave API a ogni utente che chiama.

Creare una chiave API per ogni utente che chiama

Quando non devi distinguere tra gli utenti che chiamano la tua API, ma vuoi aggiungere limitazioni alle chiavi API, puoi creare una chiave API separata per ogni utente che chiama nello stesso progetto.

Per creare una chiave API per ogni utente che chiama nello stesso progetto:

1. Nel progetto in cui è configurata la tua API o in un progetto in cui la tua API è abilitata, crea una chiave API per ogni cliente con le limitazioni della chiave API di cui hai bisogno.
2. Fornisci la chiave API a ogni utente che chiama.

Creare una chiave API per tutti gli utenti che chiamano

Quando non devi distinguere tra gli utenti che chiamano la tua API e non devi aggiungere limitazioni alle API ma vuoi comunque richiedere una chiave API (per impedire l'accesso anonimo, ad esempio), puoi creare una chiave API da utilizzare per tutti gli utenti che chiamano.

Per creare una chiave API per tutti gli utenti che chiamano:

1. Nel progetto in cui è configurata la tua API o in un progetto in cui la tua API è abilitata, crea una chiave API per tutti gli utenti che chiamano con le limitazioni della chiave API di cui hai bisogno.
2. Fornisci la stessa chiave API a ogni utente che chiama.

Restrizioni delle applicazioni

Le restrizioni delle applicazioni specificano i siti web, gli indirizzi IP o le app che possono utilizzare la tua chiave API. Per ulteriori informazioni, vedi Aggiungere restrizioni delle applicazioni.

Nota: se utilizzi Referrer HTTP (siti web) come restrizione delle applicazioni, devi includere uno schema (ad esempio https://) quando aggiungi la restrizione del sito web. Ad esempio, https://example.com/* è una restrizione valida, ma example.com/* non lo è.

Best practice

Se utilizzi le chiavi API per proteggere l'accesso alla tua API e ai dati utente, assicurati di impostare il flag --service_control_network_fail_policy su close quando configuri le opzioni di avvio di Extensible Service Proxy V2 (ESPv2). Il valore predefinito del flag è open.

ESPv2 chiama Service Control per verificare le chiavi API. Se si verificano errori di rete durante la connessione a Service Control e ESPv2 non riesce a verificare la chiave API, le eventuali richieste inviate alla tua API con chiavi fraudolente vengono rifiutate.

Passaggi successivi

• Quando e perché utilizzare le chiavi API
• Proteggere una chiave API