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. Questa pagina descrive come limitare l'accesso alle API ai client che dispongono di una chiave API e mostra come creare una chiave API.

Extensible Service Proxy (ESP) utilizza ServiceControlAPI 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 è registrato e non è aggiunto all'intestazione della richiesta. Tuttavia, puoi visualizzare il progetto Google Cloud a cui è associato un client in Endpoint > Servizio, come descritto in Filtrare per un progetto consumer specifico.

Per informazioni sul progetto Google Cloud in cui deve essere creata una chiave API, consulta la pagina relativa alla condivisione delle API protette da chiave API.

Per impostazione predefinita, nei servizi gRPC, tutti i metodi API richiedono una chiave API per accedervi. Puoi disabilitare il requisito della chiave API per l'intera API o per metodi specifici. A tale scopo, aggiungi una sezione uso alla configurazione del servizio e configura regole e selettori, come descritto nelle procedure seguenti.

Limitazione o concessione dell'accesso a tutti i metodi API

Per specificare non una chiave API per accedere all'API:

  1. Apri il file di configurazione del servizio gRPC del progetto in un editor di testo e trova o aggiungi una sezione usage.

  2. Nella sezione usage, specifica una regola allow_unregistered_calls come segue. Il carattere jolly "*" in selector indica che la regola si applica a tutti i metodi nell'API.

    usage:
      rules:
      # All methods can be called without an API Key.
      - selector: "*"
        allow_unregistered_calls: true
    

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 di configurazione del servizio gRPC del progetto in un editor di testo e trova o aggiungi una sezione usage:

  2. Nella sezione usage, specifica una regola allow_unregistered_calls come segue. selector significa che la regola si applica solo al metodo specificato, in questo caso ListShelves.

    usage:
      rules:
      # ListShelves method can be called without an API Key.
      - selector: endpoints.examples.bookstore.Bookstore.ListShelves
        allow_unregistered_calls: true
    

Chiamata a un'API utilizzando una chiave API

Le chiamate a API variano in base al tipo di client gRPC o HTTP.

Client gRPC

Se un metodo richiede una chiave API, i client gRPC devono trasferire il valore della chiave come x-api-key metadati con la relativa chiamata al metodo.

Python

def run(host, port, api_key, auth_token, timeout, use_tls, servername_override, ca_path):
    """Makes a basic ListShelves call against a gRPC Bookstore server."""

    if use_tls:
        with open(ca_path, 'rb') as f:
            creds = grpc.ssl_channel_credentials(f.read())
        channel_opts = ()
        if servername_override:
            channel_opts += ((
                        'grpc.ssl_target_name_override', servername_override,),)
        channel = grpc.secure_channel('{}:{}'.format(host, port), creds, channel_opts)
    else:
        channel = grpc.insecure_channel('{}:{}'.format(host, port))

    stub = bookstore_pb2_grpc.BookstoreStub(channel)
    metadata = []
    if api_key:
        metadata.append(('x-api-key', api_key))
    if auth_token:
        metadata.append(('authorization', 'Bearer ' + auth_token))
    shelves = stub.ListShelves(empty_pb2.Empty(), timeout, metadata=metadata)
    print('ListShelves: {}'.format(shelves))

Java

private static final class Interceptor implements ClientInterceptor {
  private final String apiKey;
  private final String authToken;

  private static Logger LOGGER = Logger.getLogger("InfoLogging");

  private static Metadata.Key<String> API_KEY_HEADER =
      Metadata.Key.of("x-api-key", Metadata.ASCII_STRING_MARSHALLER);
  private static Metadata.Key<String> AUTHORIZATION_HEADER =
      Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER);

  public Interceptor(String apiKey, String authToken) {
    this.apiKey = apiKey;
    this.authToken = authToken;
  }

  @Override
  public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
      MethodDescriptor<ReqT,RespT> method, CallOptions callOptions, Channel next) {
    LOGGER.info("Intercepted " + method.getFullMethodName());
    ClientCall<ReqT, RespT> call = next.newCall(method, callOptions);

    call = new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(call) {
      @Override
      public void start(Listener<RespT> responseListener, Metadata headers) {
        if (apiKey != null && !apiKey.isEmpty()) {
          LOGGER.info("Attaching API Key: " + apiKey);
          headers.put(API_KEY_HEADER, apiKey);
        }
        if (authToken != null && !authToken.isEmpty()) {
          System.out.println("Attaching auth token");
          headers.put(AUTHORIZATION_HEADER, "Bearer " + authToken);
        }
        super.start(responseListener, headers);
      }
    };
    return call;
  }
}

Go

func main() {
	flag.Parse()

	// Set up a connection to the server.
	conn, err := grpc.Dial(*addr, grpc.WithInsecure())
	if err != nil {
		log.Fatalf("did not connect: %v", err)
	}
	defer conn.Close()
	c := pb.NewGreeterClient(conn)

	if *keyfile != "" {
		log.Printf("Authenticating using Google service account key in %s", *keyfile)
		keyBytes, err := ioutil.ReadFile(*keyfile)
		if err != nil {
			log.Fatalf("Unable to read service account key file %s: %v", *keyfile, err)
		}

		tokenSource, err := google.JWTAccessTokenSourceFromJSON(keyBytes, *audience)
		if err != nil {
			log.Fatalf("Error building JWT access token source: %v", err)
		}
		jwt, err := tokenSource.Token()
		if err != nil {
			log.Fatalf("Unable to generate JWT token: %v", err)
		}
		*token = jwt.AccessToken
		// NOTE: the generated JWT token has a 1h TTL.
		// Make sure to refresh the token before it expires by calling TokenSource.Token() for each outgoing requests.
		// Calls to this particular implementation of TokenSource.Token() are cheap.
	}

	ctx := context.Background()
	if *key != "" {
		log.Printf("Using API key: %s", *key)
		ctx = metadata.AppendToOutgoingContext(ctx, "x-api-key", *key)
	}
	if *token != "" {
		log.Printf("Using authentication token: %s", *token)
		ctx = metadata.AppendToOutgoingContext(ctx, "Authorization", fmt.Sprintf("Bearer %s", *token))
	}

	// Contact the server and print out its response.
	name := defaultName
	if len(flag.Args()) > 0 {
		name = flag.Arg(0)
	}
	r, err := c.SayHello(ctx, &pb.HelloRequest{Name: name})
	if err != nil {
		log.Fatalf("could not greet: %v", err)
	}
	log.Printf("Greeting: %s", r.Message)
}

Node.js

const makeGrpcRequest = (JWT_AUTH_TOKEN, API_KEY, HOST, GREETEE) => {
  // Uncomment these lines to set their values
  // const JWT_AUTH_TOKEN = 'YOUR_JWT_AUTH_TOKEN';
  // const API_KEY = 'YOUR_API_KEY';
  // const HOST = 'localhost:50051'; // The IP address of your endpoints host
  // const GREETEE = 'world';

  // Import required libraries
  const grpc = require('grpc');
  const path = require('path');

  // Load protobuf spec for an example API
  const PROTO_PATH = path.join(__dirname, '/protos/helloworld.proto');
  const protoObj = grpc.load(PROTO_PATH).helloworld;

  // Create a client for the protobuf spec
  const client = new protoObj.Greeter(HOST, grpc.credentials.createInsecure());

  // Build gRPC request
  const metadata = new grpc.Metadata();
  if (API_KEY) {
    metadata.add('x-api-key', API_KEY);
  } else if (JWT_AUTH_TOKEN) {
    metadata.add('authorization', `Bearer ${JWT_AUTH_TOKEN}`);
  }

  // Execute gRPC request
  client.sayHello({name: GREETEE}, metadata, (err, response) => {
    if (err) {
      console.error(err);
    }

    if (response) {
      console.log(response.message);
    }
  });
};

Client HTTP

Se utilizzi Cloud Endpoints per gRPC' la funzionalità di transcodifica HTTP, i client HTTP possono inviare la chiave come parametro di ricerca proprio come fanno per i servizi OpenAPI.

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.

Passaggi successivi