En esta página, se describe cómo autenticar cuando realizas una solicitud REST a una API de Google.
Para obtener información sobre cómo autenticarte cuando usas bibliotecas cliente de Google, consulta Autentica mediante bibliotecas cliente.
Antes de comenzar
Para ejecutar las muestras en esta página, completa los siguientes pasos:
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:
gcloud services enable cloudresourcemanager.googleapis.com
iam.googleapis.com
Si no deseas usar gcloud CLI, puedes omitir estos pasos y usar la suplantación de identidad de cuenta de servicio o el servidor de metadatos para generar un token.
Tipos de credenciales
Puedes usar los siguientes tipos de credenciales para autenticar una llamada a REST:
Tus credenciales de gcloud CLI
Este enfoque es la forma más fácil y segura de proporcionar credenciales a un método de REST en un entorno de desarrollo local. Si tu cuenta de usuario tiene los permisos necesarios de Identity and Access Management (IAM) para el método al que deseas llamar, este es el enfoque preferido.
Tus credenciales de gcloud no son las mismas que proporcionas a ADC mediante la CLI de gcloud. Para obtener más información, consulta Configuración de autenticación de gcloud CLI y configuración de ADC.
Las credenciales proporcionadas a las credenciales predeterminadas de la aplicación (ADC).
Este método es la opción preferida para autenticar una llamada REST en un entorno de producción, ya que ADC encuentra credenciales del recurso en el que se ejecuta tu código (como una máquina virtual de Compute Engine). También puedes usar ADC para autenticarte en un entorno de desarrollo local. En este caso, la CLI de gcloud crea un archivo que contiene las credenciales en el sistema de archivos local.
Las credenciales proporcionadas mediante la suplantación de la identidad de una cuenta de servicio.
Este método requiere más configuración. Si quieres usar tus credenciales existentes para obtener credenciales de corta duración para otra cuenta de servicio, como realizar pruebas con una cuenta de servicio de forma local o solicitar privilegios elevados temporales, usa este enfoque.
Las credenciales que muestra el servidor de metadatos.
Este método solo funciona en entornos con acceso a un servidor de metadatos. Las credenciales que muestra el servidor de metadatos son las mismas que las que encontrarían las credenciales predeterminadas de la aplicación con la cuenta de servicio adjunta, pero solicitas de forma explícita el token de acceso del servidor de metadatos y, luego, lo proporcionas con la solicitud de REST. Para consultar las credenciales del servidor de metadatos, se requiere una solicitud HTTP GET. Este método no se basa en Google Cloud CLI.
Credenciales de la CLI de gcloud
Para ejecutar el siguiente ejemplo, necesitas el permiso resourcemanager.projects.get
en el proyecto. El permiso resourcemanager.projects.get
se incluye en una variedad de roles, por ejemplo, el rol Navegador (roles/browser
).
Usa el comando
gcloud auth print-access-token
para insertar un token de acceso generado a partir de las credenciales de usuario.En el siguiente ejemplo, se obtienen detalles del proyecto especificado. Puedes usar el mismo patrón para cualquier solicitud de REST.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT_ID
: el nombre o el ID de tu proyecto de Google Cloud.
Para enviar tu solicitud, elige una de estas opciones:
curl
Ejecuta el siguiente comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"PowerShell
ejecute el siguiente comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand ContentSe muestran los detalles de tu proyecto.
En el caso de las APIs que requieren un proyecto de cuota, debes configurar una de forma explícita para la solicitud. Para obtener más información, consulta Configura el proyecto de cuota con una solicitud de REST en esta página.
Credencial predeterminada de la aplicación
Para ejecutar el siguiente ejemplo, el principal asociado con las credenciales que proporcionas a las ADC necesita el permiso resourcemanager.projects.get
en el proyecto. El permiso resourcemanager.projects.get
se incluye en una variedad de roles, por ejemplo, el rol Navegador (roles/browser
).
Proporciona credenciales para ADC.
Si ejecutas en un recurso de procesamiento de Google Cloud, no debes proporcionar tus credenciales de usuario a ADC. En su lugar, usa la cuenta de servicio conectada para proporcionar credenciales. Para obtener más información, consulta Servicios que admiten la conexión de una cuenta de servicio.
Usa el comando
gcloud auth application-default print-access-token
para insertar el token de acceso que muestra ADC en tu solicitud de REST.En el siguiente ejemplo, se obtienen detalles del proyecto especificado. Puedes usar el mismo patrón para cualquier solicitud de REST.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
PROJECT_ID
: el nombre o el ID de tu proyecto de Google Cloud.
Para enviar tu solicitud, elige una de estas opciones:
curl
Ejecuta el siguiente comando:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"PowerShell
ejecute el siguiente comando:
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand ContentSe muestran los detalles de tu proyecto.
Si en la solicitud se muestra un mensaje de error sobre la compatibilidad de las credenciales del usuario final con la API, consulta Configura el proyecto de la cuota con una solicitud de REST en esta página.
Se usó la identidad de la cuenta de servicio
La forma más sencilla de robar la identidad de una cuenta de servicio para generar un token de acceso es con la gcloud CLI. Sin embargo, si necesitas generar el token de forma programática o no quieres usar gcloud CLI, puedes usar la suplantación de identidad para generar un token de corta duración.
Para obtener más información sobre cómo actuar en nombre de una cuenta de servicio, consulta Usa el robo de identidad de cuentas de servicio.
Revisa los permisos necesarios.
- El principal que deseas usar para realizar el robo de identidad debe tener el permiso
iam.serviceAccounts.getAccessToken
en la cuenta de servicio que se usará (también llamada cuenta de servicio con privilegios). El permisoiam.serviceAccounts.getAccessToken
se incluye en el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator
). Si usas tu cuenta de usuario, debes agregar este permiso incluso si tienes el rol Propietario (roles/owner
) en el proyecto. Para obtener más información, consulta Configura los permisos obligatorios.
- El principal que deseas usar para realizar el robo de identidad debe tener el permiso
Identifica o crea la cuenta de servicio con privilegios, la cuenta de servicio que representarás.
La cuenta de servicio con privilegios debe tener los permisos necesarios para realizar la llamada al método de la API.
gcloud
- Usa el comando
gcloud auth print-access-token
con la marca--impersonate-service-account
a fin de insertar un token de acceso para la cuenta de servicio con privilegios en tu solicitud de REST.
En el siguiente ejemplo, se obtienen detalles del proyecto especificado. Puedes usar el mismo patrón para cualquier solicitud de REST.
Para ejecutar este ejemplo, la cuenta de servicio que actúas necesita el permiso resourcemanager.projects.get
. El permiso resourcemanager.projects.get
se incluye en una variedad de roles, por ejemplo, el rol Navegador (roles/browser
).
Realiza los siguientes reemplazos:
PRIV_SA
: La dirección de correo electrónico de la cuenta de servicio con privilegios. Por ejemplo,my-sa@my-project.iam.gserviceaccount.com
PROJECT_ID
: el nombre o el ID de tu proyecto de Google Cloud.
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
"https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
Token de corta duración
Para generar un token de corta duración con la identidad de cuenta de servicio, sigue las instrucciones que se proporcionan en Cómo crear un token de acceso de corta duración.
Servidor de metadatos
Para obtener un token de acceso del servidor de metadatos, debes realizar la llamada REST con uno de los servicios que tienen acceso a un servidor de metadatos:
- Compute Engine
- Entorno estándar de App Engine
- Entorno flexible de App Engine
- Funciones de Cloud Run
- Cloud Run
- Google Kubernetes Engine
- Cloud Build
Usas una herramienta de línea de comandos, como curl
, para obtener un token de acceso y, luego, insértalo en tu solicitud de REST.
Consulta el servidor de metadatos para obtener un token de acceso:
curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \ -H "Metadata-Flavor: Google"
La solicitud muestra una respuesta similar a la del siguiente ejemplo:
{ "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA", "expires_in":3599, "token_type":"Bearer" }
Inserta el token de acceso en tu solicitud de REST y realiza los siguientes reemplazos:
ACCESS_TOKEN
: el token de acceso que se muestra en el paso anterior.PROJECT_ID
: el nombre o el ID de tu proyecto de Google Cloud.
curl -X GET \ -H "Authorization: Bearer ACCESS_TOKEN" \ "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
Configura el proyecto de cuota con una solicitud de REST
Para llamar a algunas APIs con credenciales de usuario, también debes configurar el proyecto que se factura para tu uso y que se usa a fin de realizar un seguimiento de la cuota. Si tu llamada a la API muestra un mensaje de error que indica que las credenciales de usuario no son compatibles o que el proyecto de cuota no está configurado, debes configurar explícitamente el proyecto de cuota para la solicitud.
Para configurar el proyecto de cuota, incluye el encabezado x-goog-user-project
en tu solicitud.
Para obtener más información sobre cuándo puedes encontrarte con este problema, consulta Las credenciales de usuario no funcionan.
Debes tener el permiso de IAM serviceusage.services.use
para que un proyecto pueda designarlo como tu proyecto de facturación. El permiso serviceusage.services.use
se incluye en el rol de IAM Service Usage Consumer. Si no tienes el permiso serviceusage.services.use
para ningún proyecto, comunícate con tu administrador de seguridad o un propietario del proyecto que pueda otorgarte el rol Service Usage Consumer en el proyecto.
En el siguiente ejemplo, se usa la API de Cloud Translation para traducir la palabra “hello” al español. La API de Cloud Translation es una API que necesita que se especifique un proyecto de cuota. Para ejecutar la muestra, crea un archivo llamado request.json
con el contenido del cuerpo de la solicitud.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_ID: El ID o el nombre del proyecto de Google Cloud que se usará como proyecto de facturación.
Cuerpo JSON de la solicitud:
{ "q": "hello", "source": "en", "target": "es" }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://translation.googleapis.com/language/translate/v2"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content
La solicitud de traducción se realiza correctamente. Puedes probar el comando sin el encabezado x-goog-user-project
para ver lo que sucede cuando no especificas el proyecto de facturación.
¿Qué sigue?
- Consulta una descripción general de la autenticación.
- Obtén información sobre cómo autenticar con bibliotecas cliente.
- Comprende la configuración de autenticación de gcloud CLI y la configuración de ADC.