Se usó la API de Cloud Translation para traducir esta página.

Restringe el acceso a la API con claves de API

OpenAPI | gRPC

Puedes usar claves de API para restringir el acceso a métodos de API específicos o a todos los métodos en una API. En esta página, se describe cómo restringir el acceso a la API a los clientes que tienen una clave de API y, también, cómo crear una clave de API.

El proxy de servicio extensible (ESP) usa la API de Control de servicios para validar una clave de API y su asociación con la API habilitada de un proyecto. Si configuras un requisito de clave en tu API, se rechazan las solicitudes a la clase, la API o el método protegidos si no tienen una clave generada en tu proyecto o en otros proyectos que pertenezcan a desarrolladores a los que les hayas otorgado acceso para habilitar tu API. El proyecto en el que se creó la clave de API no se registra y no se agrega al encabezado de la solicitud. Sin embargo, puedes ver el proyecto de Google Cloud con el que está asociado un cliente en Endpoints > Servicios, como se describe en Filtro para un proyecto de consumidor específico.

Para obtener información sobre en qué proyecto de Google Cloud se debe crear una clave de API, consulta Compartir API protegidas por claves de API.

Restringe el acceso a todos los métodos de la API

A fin de solicitar una clave de API para acceder a todos los métodos de la API, haz lo siguiente:

Abre el archivo openapi.yaml de tu proyecto en un editor de texto.
En securityDefinitions:, agrega los valores api_key: apiKey, key y query, como se indica en el fragmento del código de muestra:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Esto establece un “esquema de seguridad” llamado api_key, que puedes usar para proteger la API. Para obtener más opciones de definición de api_key, consulta las limitaciones de definiciones de claves de API.
En el nivel superior del archivo (sin sangría ni anidado), agrega api_key: [] a la directiva security. Es posible que debas agregar la directiva security o que esta ya se encuentre presente:
```
  security:
    - api_key: []
```
Esta directiva aplica el esquema de seguridad api_key para todos los métodos en el archivo. No coloques nada dentro de los corchetes. La especificación de OpenAPI requiere una lista vacía para los esquemas de seguridad que no usan OAuth.

Restringir el acceso a métodos de la API específicos

A fin de solicitar una clave de API para un método específico, haz lo siguiente:

Abre el archivo openapi.yaml de tu proyecto en un editor de texto.
En el nivel superior del archivo (sin sangría ni anidado), agrega una directiva de seguridad vacía para aplicarla a toda la API:
```
security: []
```
En securityDefinitions:, agrega los valores api_key: apiKey, key y query, como se indica en el fragmento del código de muestra:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Esto establece un “esquema de seguridad” llamado api_key, que puedes usar para proteger la API. Para obtener más opciones de definición de api_key, consulta las limitaciones de definiciones de claves de API.
Agrega api_key: [] a la directiva security en la definición del método:
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
Esta directiva aplica el esquema de seguridad api_key al método. No coloques nada dentro de los corchetes. La especificación de OpenAPI requiere una lista vacía para los esquemas de seguridad que no usan OAuth.

Quitar la restricción de clave de API de un método

A fin de desactivar la validación de la clave de API para un método en particular, incluso cuando restringiste el acceso a la API, sigue estos pasos:

Abre el archivo openapi.yaml de tu proyecto en un editor de texto.

Agrega una directiva security vacía en la definición del método:

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

Llama a una API mediante una clave de API

Si una API o un método de una API requiere una clave de API, proporciona la clave mediante un parámetro de consulta llamado key, como se muestra en el siguiente ejemplo con cURL:

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

En el ejemplo anterior, ENDPOINTS_HOST y ENDPOINTS_KEY son variables de entorno que contienen el nombre de host de tu API y la clave de API, respectivamente.

Comparte API protegidas por claves de API

Las claves de API están asociadas al proyecto de Google Cloud en el que se crearon. Si decidiste solicitar una clave de API para tu API, el proyecto de Google Cloud en el que se crea la clave de API depende de las respuestas a las siguientes preguntas:

¿Necesitas distinguir entre los emisores de tu API de modo que puedas usar características de Endpoints, como las cuotas?
¿Todos los emisores de tu API tienen sus propios proyectos de Google Cloud?
¿Necesitas configurar restricciones de clave de API diferentes?

Puedes usar el siguiente árbol de decisión como guía para decidir en qué proyecto de Google Cloud se creará la clave de API.

Otorga permisos para habilitar la API

Cuando necesites distinguir entre los emisores de tu API y cada emisor tiene su propio proyecto de Google Cloud, puedes otorgar a las principales permiso para habilitar la API en su propio proyecto de Google Cloud. De esta forma, los usuarios pueden crear su propia clave de API para usarla en tu API.

Por ejemplo, supongamos que tu equipo creó una API de uso interno para varios programas cliente de tu empresa y cada programa cliente tiene su propio proyecto de Google Cloud. Si necesitas distinguir entre los emisores de la API, se debe crear una clave de API para cada emisor en un proyecto de Google Cloud diferente. Puedes otorgar a tus compañeros de trabajo permiso para habilitar la API en el proyecto de Google Cloud con el que está asociado el programa cliente.

Para permitir que los usuarios creen sus propias claves de API, haz lo siguiente:

En el proyecto de Google Cloud en el que está configurada tu API, otórgale a cada usuario permiso para habilitar tu API.
Informa a los usuarios que pueden habilitar la API en su propio proyecto de Google Cloud y crear una clave de API.

Crea un proyecto de Google Cloud por separado para cada emisor

Cuando necesites distinguir entre los emisores de tu API y no todos los emisores tengan proyectos de Google Cloud, puedes crear un proyecto de Google Cloud y una clave de API diferentes para cada emisor. Antes de crear los proyectos, piensa bien qué nombres de proyecto usarás, a fin de poder identificar con facilidad al emisor asociado con el proyecto.

Por ejemplo, supongamos que la API tiene clientes externos y no tienes idea de cómo se crearon los programas cliente que llaman a la API. Es posible que algunos de los clientes utilicen los servicios de Google Cloud y tengan un proyecto de Google Cloud, y quizás otros no. Para distinguir entre los emisores, debes crear un proyecto de Google Cloud separado y una clave de API para cada emisor.

Si deseas crear un proyecto de Google Cloud y una clave de API distintos para cada emisor, sigue estos pasos:

Crea un proyecto por separado para cada emisor.
En cada proyecto, habilita tu API y crea una clave de API.
Proporciona la clave de API a cada emisor.

Crear una clave de API para cada emisor

Cuando no necesitas distinguir entre los emisores de tu API, pero quieres agregar restricciones de clave de API, puedes crear una clave de API separada para cada emisor en el mismo proyecto.

Para crear una clave de API para cada emisor en el mismo proyecto, haz lo siguiente:

En el proyecto en el que está configurada la API o en un proyecto en el que la API esté habilitada, crea una clave de API para cada cliente que tenga las restricciones de clave de API que necesites.
Proporciona la clave de API a cada emisor.

Crear una clave de API para todos los emisores

Cuando no necesitas distinguir entre los emisores de la API ni necesitas agregar restricciones de API, pero deseas requerir una clave de API de todos modos (por ejemplo, para impedir el acceso anónimo), puedes crear una sola clave de API que usarán todos los emisores.

Para crear una clave de API para todos los emisores, haz lo siguiente:

En el proyecto en el que está configurada tu API o en un proyecto en el que la API esté habilitada, crea una clave de API para todos los emisores.
Proporciona la misma clave de API a todos los emisores.

Prácticas recomendadas

Si confías en las claves de API para proteger el acceso a tu API y los datos del usuario, asegúrate de establecer la marca --service_control_network_fail_open en close cuando configures las opciones de inicio del proxy de servicio extensible V2 (ESPv2). El valor predeterminado para la marca es open..

El ESPv2 llama al Control de servicios para verificar las claves de API. Si hay fallas de red cuando te conectas al Control de servicios y el ESPv2 no puede verificar la clave de API, esto garantiza que se rechacen todas las solicitudes potenciales que se realicen a tu API con claves fraudulentas.