Utilizzo di chiavi API

Questa pagina descrive come utilizzare le chiavi API in API Gateway.

Una chiave API è una stringa che identifica un Google Cloud progetto ai fini di quota, fatturazione e monitoraggio. Gli sviluppatori generano una chiave API in un progetto nella console Google Cloud . e la incorporano in ogni chiamata all'API come parametro di query o in un'intestazione della richiesta.

Se specifichi un requisito della chiave API nella configurazione dell'API, API Gateway utilizza la chiave API per cercare il progetto Google Cloud associato. API Gateway rifiuta le richieste, a meno che la chiave API non sia stata generata nel tuo progetto Google Cloud o in altri progettiGoogle Cloud in cui l'API è stata abilitata.

Per creare una chiave API o visualizzare le chiavi API già disponibili nel tuo progetto Google Cloud , vai alla pagina API e servizi > Credenziali.

Vai a credenziali

Utilizzare una chiave API

Per utilizzare le funzionalità di API Gateway, ad esempio le quote, puoi inserire una chiave API in modo che API Gateway possa identificare il Google Cloud progetto a cui è associata l'applicazione client.

Configurare l'autenticazione con chiave API per API Gateway

Per proteggere l'accesso al gateway utilizzando una chiave API:

  1. Attiva il supporto delle chiavi API per il tuo servizio. Inserisci il seguente comando, dove:
    • MANAGED_SERVICE_NAME specifica il nome del servizio gestito creato durante il deployment dell'API. Puoi visualizzarlo nella proprietà Servizio gestito elencata con il comando gcloud api-gateway apis describe.
    • PROJECT_ID specifica il nome del tuo progetto Google Cloud .
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
     Ad esempio: 
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. Modifica la specifica OpenAPI utilizzata per creare la configurazione API in modo da includere le istruzioni per applicare un criterio di sicurezza per la convalida della chiave API su tutto il traffico. Aggiungi il tipo security e securityDefinitions o securitySchemes come mostrato di seguito:

    OpenAPI 2.0

      # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

    securityDefinition configura l'API in modo che richieda una chiave API trasmessa come parametro di query denominato key quando viene richiesto l'accesso a tutti i percorsi definiti nella specifica.

    OpenAPI 3.x

    # openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

    securitySchemes configura l'API in modo che richieda una chiave API trasmessa come parametro di query denominato key quando viene richiesto l'accesso a tutti i percorsi definiti nella specifica.
  3. Crea una nuova configurazione API con la descrizione OpenAPI modificata utilizzando questo comando: 
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
     Ad esempio: 
    gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. Esegui questo comando per aggiornare il gateway esistente con la nuova configurazione API: 
    gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GATEWAY_LOCATION --project=PROJECT_ID
     Ad esempio: 
    gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

Limitazione delle chiavi API

Per impostazione predefinita, le chiavi API non sono soggette a restrizioni, il che le rende vulnerabili all'utilizzo non autorizzato. Aggiungi limitazioni API quando possibile. Le restrizioni delle API specificano quali API possono essere chiamate utilizzando la chiave API. Tutte le chiavi API utilizzate dalle applicazioni di produzione devono avere limitazioni API.

Per aggiungere limitazioni dell'API:

  1. Trova il titolo dell'API come indicato nella configurazione API. Nel seguente esempio, il titolo dell'API è My Example Config:

    OpenAPI 2.0

    # openapi.yaml
swagger: '2.0'
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

    OpenAPI 3.x

    # openapi.yaml
openapi: 3.0.4
info:
  title: My Example Config
  description: Sample API on API Gateway
  version: 1.0.0
...

  2. Nella console Google Cloud , vai alla pagina API e servizi > Credenziali.

    Vai a credenziali

  3. Seleziona il nome della chiave API che vuoi utilizzare per la tua API.

  4. Nella sezione Restrizioni delle API della pagina dei dettagli della chiave API, fai clic su Limita chiave.

  5. Seleziona l'API a cui la tua chiave API verrà utilizzata per accedere dall'elenco a discesa delle API disponibili. Ad esempio, seleziona My Example Config.

  6. Fai clic su Salva.

La limitazione dovrebbe essere applicata a breve.