Autentica para usar REST

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:

1. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. 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 el servidor de metadatos para mostrar 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).

1. 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 Content

   Se 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).

1. 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.

2. 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 Content

   Se 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

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.

1. Revisa los permisos necesarios.

   • Tu cuenta de usuario debe tener el permiso iam.serviceAccounts.getAccessToken en la cuenta de servicio que se usará (también llamada cuenta de servicio con privilegios). El permiso iam.serviceAccounts.getAccessToken se incluye en el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator). Necesitas este permiso incluso si tienes el rol Propietario (roles/owner) en el proyecto. Para obtener más información, consulta Configura los permisos obligatorios.

   • En el siguiente ejemplo, la cuenta de servicio que está suplantando debe tener 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).

2. 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.

3. 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"
   

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.

1. 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"
    }
   

2. 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 -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"

$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.