Como restringir o acesso à API com as chaves de API

OpenAPI | gRPC

Use as chaves de API para restringir o acesso a métodos específicos ou a todos os métodos em uma API. Nesta página, você aprende a restringir o acesso à API para os clientes com uma chave, bem como a criar uma chave de API.

O Extensible Service Proxy (ESP) usa a API Service Control para validar uma chave de API e a associação com a API ativada de um projeto. Se você definir um requisito de chave para uma API, as solicitações para métodos, classes ou APIs protegidos serão rejeitadas a menos que elas tenham uma chave gerada no seu projeto ou em outros projetos de desenvolvedores com acesso para ativar sua API. O projeto em que a chave de API foi criada não é registrado nem adicionado ao cabeçalho da solicitação. No entanto, é possível visualizar o Google Cloud projeto a que um cliente está associado em Endpoints > Serviços, conforme descrito em Filtrar por um projeto de consumidor específico.

Para saber em qual Google Cloud projeto uma chave de API precisa ser criada em, consulte Compartilhar APIs protegidas por chave de API.

Como restringir acesso a todos os métodos da API

Para exigir uma chave de API para acessar todos os métodos da API:

OpenAPI 2.0

1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
2. Em securityDefinitions:, adicione valores api_key: apiKey, key, query, conforme mostrado no snippet de código de exemplo:
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

   Isso estabelece um "esquema de segurança" chamado api_key, que pode ser usado para proteger a API. Para outras opções de definição de api_key, consulte Limitações da definição de chave de API.

3. No nível superior do arquivo (sem recuo ou aninhamento), adicione api_key: [] à diretiva security. Talvez seja necessário adicionar a diretiva security ou ela já esteja presente:

   security:
     - api_key: []

   Esta diretiva aplica o esquema de segurança api_key a todos os métodos no arquivo. Não coloque nada dentro dos colchetes. A especificação da OpenAPI precisa de uma lista de esquemas de segurança vazia que não usa o OAuth.

OpenAPI 3.x

1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
2. Em components.securitySchemes:, adicione o seguinte:

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   Isso estabelece um "esquema de segurança" chamado api_key, que pode ser usado para proteger a API.

3. No nível superior do arquivo (sem recuo ou aninhamento), adicione api_key: [] à diretiva security:

   security:
     - api_key: []

   Esta diretiva aplica o esquema de segurança api_key a todos os métodos no arquivo.

Como restringir o acesso a métodos específicos da API

Para exigir uma chave de API para acessar um método específico:

OpenAPI 2.0

1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
2. No nível superior do arquivo (sem recuo ou aninhamento), adicione uma diretiva de segurança vazia para aplicá-la à API inteira:

   security: []

3. Em securityDefinitions:, adicione valores api_key: apiKey, key, query, conforme mostrado no snippet de código de exemplo:
   securityDefinitions:
     # This section configures basic authentication with an API key.
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"

   Isso estabelece um "esquema de segurança" chamado api_key, que pode ser usado para proteger a API. Para outras opções de definição de api_key, consulte Limitações da definição de chave de API.

4. Adicione api_key: [] à diretiva security na definição do método:

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

   Esta diretiva aplica o esquema de segurança api_key ao método. Não coloque nada dentro dos colchetes. A especificação da OpenAPI precisa de uma lista de esquemas de segurança vazia que não usa o OAuth.

OpenAPI 3.x

1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
2. No nível superior do arquivo (sem recuo ou aninhamento), adicione uma diretiva de segurança vazia para aplicá-la à API inteira:

   security: []

3. Em components.securitySchemes:, adicione o seguinte:

   components:
     securitySchemes:
       api_key:
         type: "apiKey"
         name: "key"
         in: "query"

   Isso estabelece um "esquema de segurança" chamado api_key, que pode ser usado para proteger a API.

4. Adicione api_key: [] à diretiva security na definição do método:

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

   Esta diretiva aplica o esquema de segurança api_key ao método.

Como remover a restrição de chave de API de um método

Para desativar a validação da chave de API para um método específico mesmo que você tenha restringido o acesso da API:

OpenAPI 2.0

1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
2. Adicione uma diretiva security vazia na definição do método:

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

OpenAPI 3.x

1. Abra o arquivo openapi.yaml do projeto em um editor de texto.
2. Adicione uma diretiva security vazia na definição do método:

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

Como chamar uma API usando uma chave de API

Se uma API ou método de API exigir uma chave de API, forneça a chave usando um parâmetro de consulta chamado key, conforme mostrado no seguinte exemplo de curl:

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

em que ENDPOINTS_HOST e ENDPOINTS_KEY são variáveis de ambiente que contêm o nome do host da API e a chave de API, respectivamente.

Compartilhar APIs protegidas por chave de API

As chaves de API são associadas ao Google Cloud projeto em que foram criadas. Se você decidiu exigir uma chave de API para sua API, o Google Cloud projeto em que a chave de API é criada depende de as respostas às seguintes perguntas:

• Você precisa diferenciar os chamadores de sua API para poder usar recursos do Endpoints, como cotas?
• Todos os autores de chamadas da sua API têm os próprios Google Cloud projetos?
• Você precisa configurar diferentes restrições de chave de API?

Use a árvore de decisões abaixo como guia para decidir em qual Google Cloud projeto criar a chave de API.

Conceder permissão para ativar a API

Quando você precisa distinguir os autores das chamadas da sua API, e cada um tem o próprio Google Cloud projeto, é possível conceder permissão aos principais para ativar a API no próprio Google Cloud projeto. Dessa forma, os usuários da sua API podem criar a própria chave de API para uso com ela.

Por exemplo, digamos que sua equipe tenha criado uma API para uso interno por diversos programas cliente na empresa e cada um deles tenha o próprio Google Cloud projeto. Para distinguir entre os autores das chamadas da sua API, a chave de API de cada autor da chamada precisa ser criada em um projeto diferente Google Cloud . Você pode conceder permissão aos seus colegas para ativar a API no Google Cloud projeto associado ao programa cliente.

Veja como permitir que os usuários criem a própria chave de API:

1. No Google Cloud projeto em que a API está configurada, conceda a cada usuário a permissão para ativar sua API.
2. Entre em contato com os usuários e informe que eles podem ativar sua API no próprio Google Cloud projeto e criar uma chave de API.

Crie um projeto separado Google Cloud para cada autor da chamada

Quando você precisa diferenciar os autores das chamadas da API, mas nem todos os autores das chamadas têm Google Cloud projetos, crie um projeto separado Google Cloud e uma chave de API para cada um. Antes de criar os projetos, pense nos nomes deles para facilitar a identificação do cliente associado a cada um.

Por exemplo, digamos que você tenha clientes externos da API e você não tenha ideia de como foram criados os programas clientes que chamam essa API. Talvez alguns dos clientes usem Google Cloud serviços e tenham um Google Cloud projeto, e talvez isso não aconteça com outros clientes. Para distinguir entre os autores das chamadas, é necessário criar um projeto separado Google Cloud e uma chave de API para cada autor da chamada.

Para criar um projeto separado Google Cloud e uma chave de API para cada autor da chamada:

1. Crie um projeto separado para cada autor da chamada.
2. Em cada projeto, ative a API e crie uma chave de API.
3. Forneça a chave de API para cada autor da chamada.

Criar uma chave de API para cada autor da chamada

Quando você não precisa distinguir entre os autores das chamadas de API, mas quer adicionar restrições de chave de API, é possível criar uma chave de API separada para cada autor da chamada no mesmo projeto.

Veja como criar uma chave de API para cada autor da chamada no mesmo projeto:

1. No projeto em que a API estiver ativada ou configurada, crie uma chave de API para cada cliente com as restrições necessárias.
2. Forneça a chave de API para cada autor da chamada.

Criar uma chave de API para todos os autores das chamadas

Quando você não precisa distinguir entre os autores das chamadas de API e não precisa adicionar restrições, mas ainda quer exigir uma chave de API (para impedir o acesso anônimo, por exemplo), é possível criar uma chave para todos os autores de chamadas usarem.

Para criar uma chave de API para todos os autores das chamadas:

1. No projeto em que a API estiver ativada ou configurada, crie uma chave de API para todos os autores de chamadas com as restrições necessárias.
2. Forneça a mesma chave de API para cada autor da chamada.

Restrições de aplicativo

As restrições de aplicativo especificam quais sites, endereços IP ou apps podem usar sua chave de API. Para mais informações, consulte Adicionar restrições de aplicativos.

Observação: se você usar Referenciadores HTTP (sites) como uma restrição de aplicativo, inclua um esquema (por exemplo, https://) ao adicionar a restrição do site. Por exemplo, https://example.com/* é uma restrição válida, mas example.com/* não é.

Práticas recomendadas

Se você depende de chaves de API para proteger o acesso aos dados do usuário e à API, defina a sinalização --service_control_network_fail_policy como close ao configurar a inicialização do Extensible Service Proxy V2 (ESPv2) opções. O valor padrão da sinalização é open.

O ESPv2 chama o Service Control para verificar as chaves de API. Se houver falhas de rede ao se conectar ao Service Control e o ESPv2 não puder verificar a chave de API, todas as possíveis solicitações feitas à API com chaves fraudulentas serão rejeitadas.

A seguir

• Quando e por que usar as chaves de API
• Como proteger uma chave de API