Limitazione dell'accesso all'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 in un'API. Questa pagina descrive come limitare l'accesso API ai client che hanno una chiave API e mostra anche come creare una chiave API.

Extensible Service Proxy (ESP) utilizza l'API Service Control per convalidare una chiave API e la sua associazione all'API abilitata per un progetto. Se imposti un requisito di chiave API nell'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 all'interno di altri progetti appartenenti a sviluppatori i 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 progetto Google Cloud a cui è associato un client in Endpoint > Servizi, come descritto in Filtro per progetto consumer specifico.

Per informazioni sul progetto Google Cloud in cui deve essere creata una chiave API, consulta API di condivisione protette da chiave API.

Limitazione dell'accesso a tutti i metodi dell'API

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

Apri il file openapi.yaml del progetto in un editor di testo.
In securityDefinitions:, aggiungi i valori api_key: apiKey, key e query, come mostrato nello 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" chiamato api_key, che puoi usare per proteggere l'API. Per altre opzioni di definizione di api_key, consulta Limitazioni della definizione delle chiavi API.
Nel livello principale del file (non rientrato o nidificato), aggiungi api_key: [] all'istruzione security . Potresti dover aggiungere l'istruzione security o potrebbe essere già presente:
```
  security:
    - api_key: []
```
Questa istruzione applica lo schema di sicurezza api_key a tutti i metodi nel file. Non inserire nulla all'interno delle parentesi. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

Limitazione dell'accesso a metodi API specifici

Per richiedere una chiave API per un metodo specifico:

Apri il file openapi.yaml del progetto in un editor di testo.
Nel livello superiore del file (non rientrato o nidificato), aggiungi un'istruzione di sicurezza vuota per applicarla all'intera API:
```
security: []
```
In securityDefinitions:, aggiungi i valori api_key: apiKey, key e query, come mostrato nello 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" chiamato api_key, che puoi usare per proteggere l'API. Per altre opzioni di definizione di api_key, consulta Limitazioni della definizione delle chiavi API.
Aggiungi api_key: [] all'istruzione security nella definizione del metodo:
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
Questa istruzione applica lo schema di sicurezza api_key al metodo. Non inserire nulla all'interno delle parentesi. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

Rimozione della limitazione della chiave API per un metodo

Per disattivare la convalida delle chiavi API per un determinato metodo anche se hai limitato l'accesso all'API per l'API:

Apri il file openapi.yaml del progetto in un editor di testo.

Aggiungi un'istruzione security vuota nella definizione del metodo:

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

Chiamare un'API mediante una chiave API

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

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

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

Condivisione di API protette dalla chiave API

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

Devi distinguere tra i chiamanti dell'API in modo da poter utilizzare le funzionalità di Endpoints come le quotas?
Tutti i chiamanti della tua API hanno progetti Google Cloud personali?
Devi impostare limitazioni relative alle chiavi API diverse?

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

Concedi l'autorizzazione per abilitare l'API

Se devi distinguere tra i chiamanti della tua API e ogni chiamante ha un proprio progetto Google Cloud, puoi concedere alle entità l'autorizzazione per abilitare l'API nel proprio progetto Google Cloud. In questo modo, gli utenti dell'API possono creare la propria chiave API da utilizzare con l'API.

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

Per consentire agli utenti di creare la propria chiave API:

Nel progetto Google Cloud in cui è configurata l'API, concedi a ogni utente l'autorizzazione per attivare l'API.
Contatta gli utenti e chiedi loro che possono abilitare l'API nel loro progetto Google Cloud e creare una chiave API.

Creare un progetto Google Cloud separato per ogni chiamante

Se devi distinguere tra i chiamanti della tua API e non tutti i chiamanti hanno progetti Google Cloud, puoi creare un progetto Google Cloud e una chiave API separati per ogni chiamante. Prima di creare i progetti, valutane i nomi in modo da poter identificare facilmente il chiamante associato al progetto.

Ad esempio, supponi di avere clienti esterni della tua API e di non avere idea di come sono stati creati i programmi client che chiamano l'API. Forse alcuni clienti utilizzano i servizi Google Cloud e hanno un progetto Google Cloud; altri forse non lo usano. Per distinguere i chiamanti, devi creare un progetto Google Cloud e una chiave API separati per ogni chiamante.

Per creare un progetto Google Cloud e una chiave API separati per ogni chiamante:

Creare un progetto separato per ogni chiamante.
In ogni progetto, abilita l'API e crea una chiave API.
Assegna la chiave API a ogni chiamante.

Creare una chiave API per ogni chiamante

Se non hai bisogno di distinguere tra i chiamanti dell'API, ma vuoi aggiungere limitazioni relative alle chiavi API, puoi creare una chiave API separata per ogni chiamante nello stesso progetto.

Per creare una chiave API per ogni chiamante nello stesso progetto:

Nel progetto in cui è configurata l'API o in un progetto in cui è abilitata l'API, crea una chiave API per ogni cliente con le restrizioni relative alle chiavi API di cui hai bisogno.
Assegna la chiave API a ogni chiamante.

Creare una chiave API per tutti i chiamanti

Quando non devi distinguere tra i chiamanti della tua API e non devi aggiungere limitazioni delle API, ma vuoi comunque richiedere una chiave API (ad esempio per impedire l'accesso anonimo), puoi creare una chiave API utilizzabile da tutti i chiamanti.

Per creare una chiave API per tutti i chiamanti:

Nel progetto in cui è configurata l'API o in un progetto in cui è abilitata l'API, crea una chiave API per tutti i chiamanti.
Assegna la stessa chiave API a ogni chiamante.

best practice

Se utilizzi le chiavi API per proteggere l'accesso all'API e ai dati utente, assicurati di impostare il flag --service_control_network_fail_open su close durante la configurazione delle 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 ed ESPv2 non è in grado di verificare la chiave API, questo garantisce che tutte le potenziali richieste effettuate all'API con chiavi fraudolente vengano rifiutate.