Limitazione dell'accesso API con chiavi API

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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.

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

Per informazioni sul progetto Google Cloud in cui deve essere creata una chiave API, consulta la sezione Condividere le API protette dalla 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. Per farlo, aggiungi una sezione usage alla tua configurazione del servizio e configura regole e selettori, come descritti nelle seguenti procedure.

Limitazione o concessione dell'accesso a tutti i metodi API

Per specificare che una chiave API non è obbligatoria per accedere all'API:

  1. Apri il file della configurazione del servizio gRPC del tuo 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 "*" nell'elemento selector indica che la regola si applica a tutti i metodi dell'API.

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

Rimozione della limitazione delle chiavi API per un metodo

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

  1. Apri il file della configurazione del servizio gRPC del tuo 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 indica 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

Chiamare un'API utilizzando una chiave API

Le chiamate a un'API variano a seconda che tu chiami da un client gRPC o un client HTTP.

Client gRPC

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

Python

endpoints/bookstore-grpc/bookstore_client.py 
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

endpoints/bookstore-grpc/client/src/main/java/com/google/endpoints/examples/bookstore/BookstoreClient.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

endpoints/getting-started-grpc/client/main.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

endpoints/getting-started-grpc/client.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' funzionalità di transcodifica HTTP, i client HTTP possono inviare la chiave come parametro di ricerca allo stesso modo dei servizi OpenAPI.

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 la tua API, il progetto Google Cloud in cui viene creata la chiave dipende dalle risposte alle seguenti domande:

  • Devi distinguere tra i chiamanti della tua API in modo da poter utilizzare le funzionalità di endpoint, come le quote?
  • Tutti i chiamanti della tua API hanno i propri progetti Google Cloud?
  • Hai bisogno di 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

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

Ad esempio, supponiamo che il tuo team abbia creato un'API per uso interno da vari programmi client nella tua azienda e che ogni programma client abbia il proprio progetto Google Cloud. Per distinguere i chiamanti dell'API, la chiave API deve essere creata in un diverso 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 una propria chiave API:

  1. Nel progetto Google Cloud in cui è configurata la tua API, concedi a ogni utente l'autorizzazione per abilitare la tua API.
  2. Contatta gli utenti per informarli che possono attivare 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 utilizzano progetti Google Cloud, puoi creare un progetto Google Cloud separato e una chiave API per ciascun chiamante. Prima di creare i progetti, pensa ai nomi dei progetti in modo da poter identificare facilmente il chiamante associato.

Ad esempio, supponiamo 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 client utilizzano i servizi Google Cloud e hanno un progetto Google Cloud, e forse alcuni non lo fanno. Per distinguere 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 l'API e crea una chiave API.
  3. Assegna la chiave API a ciascun chiamante.

Creare una chiave API per ogni chiamante

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

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

  1. Puoi creare una chiave API per ogni cliente con le limitazioni delle chiavi API di cui hai bisogno in un progetto in cui è configurata l'API o in cui è attivata l'API.
  2. Assegna la chiave API a ciascun chiamante.

Crea una chiave API per tutti i chiamanti

Quando non hai bisogno di 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 per tutti i chiamanti.

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

Passaggi successivi