Limitazione dell'accesso API con le chiavi API

Puoi utilizzare le chiavi API per limitare l'accesso a metodi API specifici o a tutti i metodi in un'API. In questa pagina viene spiegato come limitare l'accesso alle API ai client che dispongono di una chiave API e come creare una chiave API.

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

Per informazioni sul progetto Google Cloud in cui deve essere creata una chiave API, consulta l'articolo Condividere le API protette da chiave API.

Limitazione dell'accesso a tutti i metodi API

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

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

  2. In securityDefinitions:, aggiungi i valori api_key: apiKey, key, query come mostrato nello snippet di codice di esempio:

    securityDefinitions:
      # This section configures basic authentication with an API key.
      api_key:
        type: "apiKey"
        name: "key"
        in: "query"

    Stabilisce uno "schema di sicurezza" chiamato api_key, che puoi usare per proteggere l'API. Per le altre opzioni di definizione di api_key, consulta le limitazioni per la definizione delle chiavi API.

  3. Al livello più alto del file (non rientrato o nidificato), aggiungi api_key: [] all'istruzione security . Potresti dover aggiungere l'istruzione security oppure l'istruzione potrebbe essere già presente:

      security:
        - api_key: []
    

    Questa istruzione applica lo schema di sicurezza api_key a tutti i metodi nel file. Non inserire alcun elemento tra parentesi quadre. 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:

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

  2. Al livello più alto del file (non rientrato o nidificato), aggiungi una direttiva di sicurezza vuota per applicarla all'intera API:

    security: []
    
  3. In securityDefinitions:, aggiungi i valori api_key: apiKey, key, query come mostrato nello snippet di codice di esempio:

    securityDefinitions:
      # This section configures basic authentication with an API key.
      api_key:
        type: "apiKey"
        name: "key"
        in: "query"

    Stabilisce uno "schema di sicurezza" chiamato api_key, che puoi usare per proteggere l'API. Per le altre opzioni di definizione di api_key, consulta le limitazioni per la definizione delle chiavi API.

  4. 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 posizionare alcuno elemento tra parentesi quadre. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

Rimozione della limitazione per le chiavi API per un metodo

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

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

  2. Aggiungi un'istruzione security vuota nella definizione del metodo:

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

Chiamata a un'API utilizzando una chiave API

Se un'API o un metodo API richiedono una chiave API, fornisci la chiave utilizzando un parametro di ricerca 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 da 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 dipende dalla risposta alle seguenti domande:

  • Devi distinguere tra i chiamanti della tua API in modo da poter utilizzare le funzionalità endpoint come le quote?
  • Tutti i chiamanti della tua API hanno i propri progetti Google Cloud?
  • Devi impostare diverse limitazioni delle chiavi API?

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

Struttura decisionale chiave API

Concedi l'autorizzazione per abilitare l'API

Quando devi distinguere tra i chiamanti della tua API e ogni chiamante ha il proprio progetto Google Cloud, puoi concedere alle entità l'autorizzazione per abilitare l'API nel proprio progetto Google Cloud. In questo modo, gli utenti della tua 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 nella tua azienda e che ogni programma client abbia il proprio progetto Google Cloud. Per distinguere tra i chiamanti della tua API, la chiave API per ogni chiamante deve essere creata in un altro progetto Google Cloud. Puoi concedere ai tuoi colleghi l'autorizzazione per abilitare l'API nel progetto Google Cloud a cui è associato il programma client.

Per consentire agli utenti di creare la propria chiave API:

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

Creare un progetto Google Cloud separato per ogni chiamante

Quando devi distinguere tra i chiamanti dell'API e non tutti i chiamanti hanno progetti Google Cloud, puoi creare un progetto Google Cloud separato e una chiave API per ogni chiamante. Prima di creare i progetti, rifletti sui nomi dei progetti in modo da poter identificare facilmente il chiamante associato.

Ad esempio, supponiamo che abbiate clienti esterni della vostra API e che non abbiate idea di come sono stati creati i programmi client che chiamano la vostra API. Forse alcuni dei clienti utilizzano i servizi Google Cloud e hanno un progetto Google Cloud, e forse alcuni non lo fanno. Per distinguere tra i chiamanti, devi creare un progetto Google Cloud separato e una chiave API per ogni chiamante.

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

  1. Creare un progetto separato per ogni chiamante.
  2. In ogni progetto, abilita la tua API e crea una chiave API.
  3. Fornisci la chiave API a ogni chiamante.

Creare una chiave API per ogni chiamante

Quando non è necessario distinguere tra chiamanti dell'API, ma si vogliono aggiungere limitazioni alla chiave API, è possibile creare una chiave API separata per ciascun chiamante nello stesso progetto.

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

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

Crea una chiave API per tutti i chiamanti

Quando non devi distinguere tra i chiamanti dell'API e non devi aggiungere restrizioni per l'API, ma vuoi comunque richiedere una chiave API (ad esempio per impedire l'accesso anonimo), puoi creare una chiave API per tutti i chiamanti.

Per creare una chiave API per tutti i chiamanti:
  1. Nel progetto in cui è configurata l'API o in quello per cui l'API è abilitata, crea una chiave API per tutti i chiamanti.
  2. Fornisci la stessa chiave API a ogni chiamante.

Best practice

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

ESPv2 chiama Service Control per verificare le chiavi API. In caso di errori di rete durante la connessione a Service Control e ESPv2, non è possibile verificare la chiave API, per evitare che le potenziali richieste inviate all'API con chiavi fraudolente vengano rifiutate.

Passaggi successivi