Obtén información para invocar funciones de Cloud Run autenticadas

1. Introducción

Descripción general

Funciones de Cloud Run es una solución de procesamiento ligera que permite a los desarrolladores crear funciones individuales y de un solo propósito que se pueden activar con HTTPS o responder a CloudEvents sin necesidad de administrar un servidor o un entorno de ejecución. Obtén más información sobre las funciones de Cloud Run en nuestra entrada de blog.

Existen dos enfoques principales para controlar las invocaciones a las funciones de Cloud Run: proteger el acceso según la identidad y proteger el acceso con controles de acceso basados en la red. Este codelab se centra en el primer enfoque y te guía a través de 3 situaciones para proteger el acceso según la identidad para invocar una función:

1. Usa tu token de identidad de gcloud para invocar una función con fines de desarrollo y pruebas locales.
2. Usa la identidad de una cuenta de servicio cuando desarrolles y pruebes de forma local para usar las mismas credenciales que en producción.
3. Usa las bibliotecas cliente de Google para controlar la autenticación en las APIs de Google Cloud, por ejemplo, cuando un servicio necesita invocar una función.

Qué aprenderás

• Cómo configurar la autenticación en una función de Cloud Run y verificar que se haya configurado correctamente
• Invoca una función autenticada desde un entorno de desarrollo local proporcionando el token para tu identidad de gcloud.
• Cómo crear una cuenta de servicio y otorgarle el rol adecuado para invocar una función
• Cómo usar la identidad de un servicio desde un entorno de desarrollo local que tiene los roles adecuados para invocar una función

2. Configuración y requisitos

Requisitos previos

• Accediste a Cloud Console.
• Ya implementaste una función de Cloud Run activada por HTTP. Consulta el ejemplo de inicio rápido.
• (Opcional) Para la tercera situación, este codelab usa Node.js y npm como ejemplo, pero puedes usar cualquier entorno de ejecución compatible con las bibliotecas cliente de Google Auth.

Activar Cloud Shell

1. En la consola de Cloud, haz clic en Activar Cloud Shell .

Si es la primera vez que inicias Cloud Shell, aparecerá una pantalla intermedia en la que se describirá qué es. Si apareció una pantalla intermedia, haz clic en Continuar.

El aprovisionamiento y la conexión a Cloud Shell solo tomará unos minutos.

Esta máquina virtual está cargada con todas las herramientas de desarrollo necesarias. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Gran parte de tu trabajo en este codelab, si no todo, se puede hacer con un navegador.

Una vez que te conectes a Cloud Shell, deberías ver que ya te autenticaste y que el proyecto ya se configuró con el ID de tu proyecto.

2. En Cloud Shell, ejecuta el siguiente comando para confirmar que tienes la autenticación:

gcloud auth list

Resultado del comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Nota: gcloud es la herramienta de línea de comandos potente y unificada de Google Cloud. Ya está preinstalada en Cloud Shell. Notarás su compatibilidad con la finalización con tabulación. Para obtener más información, consulta la descripción general de la herramienta de línea de comandos de gcloud.

3. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

Resultado del comando

[core]
project = <PROJECT_ID>

De lo contrario, puede configurarlo con este comando:

gcloud config set project <PROJECT_ID>

Resultado del comando

Updated property [core/project].

Nota: Si completas este instructivo fuera de Cloud Shell, sigue los pasos para configurar las credenciales predeterminadas de la aplicación.

3. Crea y prueba una función autenticada de Cloud Run

Requerir autenticación significa que la principal que invoca la función debe tener el rol de invocador de Cloud Run; de lo contrario, la función mostrará un error 403 Forbidden. En este codelab, se mostrará cómo otorgar los roles de invocador adecuados a una principal.

Configura variables de entorno locales para simplificar los comandos de gcloud

Primero, crearás algunas variables de entorno para mejorar la legibilidad de los comandos de gcloud que se usan en este codelab.

REGION=us-central1
PROJECT_ID=$(gcloud config get-value project)

Crea el código fuente de la función

Aunque este codelab usa Node.js, puedes usar cualquier entorno de ejecución compatible con las bibliotecas cliente de Google Auth.

Primero, crea un directorio y ábrelo con el comando cd.

mkdir auth-function-codelab && cd $_

Luego, crea el archivo package.json.

touch package.json

echo '{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}
' > package.json

A continuación, crea el archivo fuente index.js.

touch index.js

echo 'const functions = require("@google-cloud/functions-framework");

functions.http("helloWorld", (req, res) => {
 res.send(`Hello ${req.query.name || req.body.name || "World"}!`);
});' > index.js

Crea la función autenticada

Estos son los pasos para crear una función autenticada para el entorno de ejecución nodejs20. Sin embargo, puedes usar cualquier entorno de ejecución compatible con las bibliotecas cliente de Google Auth.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

Para implementar una función de Cloud Run directamente en Cloud Run, ejecuta el siguiente comando:

gcloud beta run deploy $FUNCTION_NAME \
      --source . \
      --function helloWorld \
      --region $REGION \
      --no-allow-unauthenticated

Luego, puedes guardar la URL de la función como una variable de entorno para usarla más tarde.

FUNCTION_URL="$(gcloud run services describe $FUNCTION_NAME --region $REGION --format 'value(status.url)')"

Si prefieres implementar como Cloud Functions (2ª gen.), usa el siguiente comando:

gcloud functions deploy nodejs-http-function \
  --gen2 \
  --runtime=nodejs20 \
  --region=$REGION \
  --source=. \
  --entry-point=helloWorld \
  --trigger-http \
  --no-allow-unauthenticated

Luego, puedes guardar la URL de la función como una variable de entorno para usarla más tarde.

FUNCTION_URL="$(gcloud functions describe $FUNCTION_NAME --gen2 --region us-central1 --format='get(serviceConfig.uri)')"

Verifica que la función requiera autenticación intentando invocarla como una persona que llama anónima

Invocarás la función sin autenticación para verificar que recibas un error 403 esperado.

Desde una línea de comandos, ejecuta el siguiente comando curl:

curl -i $FUNCTION_URL

Verás el siguiente resultado:

<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>403 Forbidden</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Forbidden</h1>
<h2>Your client does not have permission to get URL <code>/</code> from this server.</h2>
<h2></h2>
</body></html>

Ahora, puedes consultar 3 situaciones en las que puedes invocar tu función proporcionando autenticación.

4. Situación 1: Usa tu token de identidad de gcloud

Como desarrollador, querrás una forma de probar tu función mientras la desarrollas de forma local. En esta sección, realizarás una prueba rápida para verificar que la función se autentique correctamente con tu propia identidad.

Para verificar que estás autenticado con gcloud, ejecuta el siguiente comando:

gcloud auth list

Deberías ver un asterisco junto a tu identidad activa, por ejemplo:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Puedes encontrar más información para configurar gcloud init y gcloud auth login en la documentación.

A continuación, invoca la función y pásale tu token de identidad.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token)"

Ahora verás el resultado:

Hello World!

Solución de problemas

Si recibes un error 403 Forbidden, asegúrate de que tu identidad tenga el rol de invocador de Cloud Run. Puedes usar la consola de IAM para verificar los roles otorgados a una principal.

Aunque usar tu propio token de identidad es una forma rápida de probar tu función durante el desarrollo, la persona que llama a tu función autenticada necesitará los roles adecuados; de lo contrario, recibirá un error 403 Forbidden.

Te recomendamos que sigas el principio de privilegio mínimo limitando la cantidad de identidades y cuentas de servicio que tienen roles para invocar la función. En la siguiente situación, aprenderás a crear una cuenta de servicio nueva y otorgarle los roles adecuados para invocar la función.

5. Situación 2: Usa la identidad de una cuenta de servicio

En esta situación, usarás la identidad de una cuenta de servicio (es decir, asumirás sus permisos) para invocar una función cuando desarrolles y pruebes de forma local. Si usas la identidad de una cuenta de servicio, puedes probar tu función con las mismas credenciales que en producción.

De esta manera, no solo verificarás los roles, sino que también seguirás el principio de privilegio mínimo, ya que no tendrás que otorgar el rol de invocador de Cloud Functions a otras identidades solo para fines de pruebas locales.

Para los fines de este codelab, crearás una cuenta de servicio nueva que solo tenga roles para invocar la función que creaste en este codelab.

Crear una nueva cuenta de servicio

Primero, crearás un par de variables de entorno adicionales para representar las cuentas de servicio que se usan en los comandos de gcloud.

SERVICE_ACCOUNT_NAME="invoke-functions-codelab"
SERVICE_ACCOUNT_ADDRESS=$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

A continuación, crearás la cuenta de servicio.

gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="Cloud Run function Authentication codelab"

Y otorgarás a la cuenta de servicio el rol de invocador de Cloud Run:

gcloud run services add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1  \
  --member serviceAccount:$SERVICE_ACCOUNT_ADDRESS \
  --role='roles/run.invoker'

Invoca la función usando la identidad de la cuenta de servicio

Para ello, usarás la identidad de la cuenta de servicio recién creada obteniendo su token de ID.

Agrega los roles necesarios para usar la identidad de otra cuenta

Para usar la identidad de una cuenta de servicio, tu cuenta de usuario debe tener el rol de creador de tokens de cuentas de servicio (roles/iam.serviceAccountTokenCreator) para generar un token de ID para la cuenta de servicio.

Puedes ejecutar los siguientes comandos para otorgar este rol a tu cuenta de usuario activa:

ACCOUNT_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")

gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT_ADDRESS  \
  --member user:$ACCOUNT_EMAIL \
  --role='roles/iam.serviceAccountTokenCreator'

Usa el token de ID de la cuenta de servicio

Espera unos minutos para que se propaguen los permisos. Ahora puedes invocar la función pasando el token de ID de la cuenta de servicio.

curl $FUNCTION_URL -H "Authorization: bearer $(gcloud auth print-identity-token --impersonate-service-account $SERVICE_ACCOUNT_ADDRESS)" 

Verás lo siguiente:

WARNING: This command is using service account impersonation. All API calls will be executed as [invoke-functions-codelab@<project-id>.iam.gserviceaccount.com].

Hello World!

6. Situación 3: Usa las bibliotecas cliente de Google

Para esta última parte del codelab, ejecutarás un servicio pequeño de forma local para generar un token de ID para una cuenta de servicio y, luego, llamarás a la función de forma programática con las bibliotecas cliente de Google Auth y las credenciales predeterminadas de la aplicación (ADC). Puedes obtener más información sobre las bibliotecas cliente de Google en la sección Explicación de bibliotecas cliente de la documentación.

El uso de ADC es especialmente importante cuando deseas escribir y probar tu función de forma local (p. ej., en tu laptop, en Cloud Shell, etcétera) mientras interactúas con otros recursos de Google Cloud (p. ej., Cloud Storage, Vision API, etcétera). En este ejemplo, verás cómo hacer que un servicio invoque otra función que requiere autenticación. Para obtener más información sobre ADC y el desarrollo local, consulta la entrada de blog Cómo desarrollar y probar tus Cloud Functions de forma local | Blog de Google Cloud.

Ejecuta el comando de gcloud para usar la identidad de una cuenta de servicio

ADC encuentra automáticamente las credenciales según el entorno de la aplicación y las usa para autenticarse en las APIs de Google Cloud. La marca –impersonate-service-account te permite usar la identidad de una cuenta de servicio para autenticarte en las APIs de Google Cloud.

Para usar la identidad de una cuenta de servicio, puedes ejecutar el siguiente comando:

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

Ahora ejecutarás comandos de gcloud como esa cuenta de servicio, en lugar de tu identidad.

Crea y ejecuta un servicio para invocar una función autenticada

Cada entorno de ejecución tiene su propia biblioteca cliente de Google Auth que puedes instalar. En este codelab, se te guiará para crear y ejecutar una app de Node.js de forma local.

Estos son los pasos para Node.js:

1. Crea un directorio nuevo

mkdir local-dev && cd $_

2. Crea una app nueva de Node.js

npm init -y

3. Instala la biblioteca cliente de Google Auth

npm install google-auth-library

4. Crea un archivo index.js
5. Recupera la URL de tu función de Cloud Run, que agregarás a tu código en el siguiente paso.

echo $FUNCTION_URL

6. Agrega el siguiente código a index.js. Asegúrate de cambiar la variable targetAudience a la URL de tu función de Cloud Run.

index.js

// Cloud Functions uses your function's url as the `targetAudience` value

const targetAudience = '<YOUR-CLOUD-RUN-FUNCTION-URL>';

// For Cloud Functions, endpoint(`url`) and `targetAudience` should be equal

const url = targetAudience;

const { GoogleAuth } = require('google-auth-library');
const auth = new GoogleAuth();

async function request() {
    console.info(`request ${url} with target audience ${targetAudience}`);

    // this call retrieves the ID token for the impersonated service account
    const client = await auth.getIdTokenClient(targetAudience);

    const res = await client.request({ url });
    console.info(res.data);
}

request().catch(err => {
    console.error(err.message);
    process.exitCode = 1;
});

7. Ejecuta la app

node index.js

Deberías ver el resultado "Hello World!".

Solución de problemas

Si ves un error Permission ‘iam.serviceAccounts.getOpenIdToken' denied on resource (or it may not exist)., espera unos minutos para que se propague el rol de creador de tokens de cuenta de servicio.

Si recibiste el error Cannot fetch ID token in this environment, use GCE or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account credentials JSON file, es posible que hayas olvidado ejecutar el comando.

gcloud auth application-default login --impersonate-service-account=$SERVICE_ACCOUNT_ADDRESS

7. ¡Felicitaciones!

Felicitaciones por completar el codelab.

Te recomendamos que revises la documentación sobre cómo proteger las funciones de Cloud Run.

También te recomendamos esta entrada de blog sobre el desarrollo local con funciones de Cloud Run para aprender a desarrollar y probar tu función de Cloud Run en tu entorno de desarrollador local.

Temas abordados

• Cómo configurar la autenticación en una función de Cloud Run y verificar que se haya configurado correctamente
• Invoca una función autenticada desde un entorno de desarrollo local proporcionando el token para tu identidad de gcloud.
• Cómo crear una cuenta de servicio y otorgarle el rol adecuado para invocar una función
• Cómo usar la identidad de un servicio desde un entorno de desarrollo local que tiene los roles adecuados para invocar una función

8. Limpia

Para evitar cargos involuntarios (por ejemplo, si esta Cloud Function se invoca de forma involuntaria más veces que tu asignación mensual de invocación de funciones de Cloud Run en el nivel gratuito), puedes borrar la Cloud Function o el proyecto que creaste en el Paso 2.

Para dejar de usar la identidad de la cuenta de servicio, puedes volver a acceder con tu identidad:

gcloud auth application-default login

Para borrar la función de Cloud Run, ve a la consola de Cloud de la función de Cloud Run en https://console.cloud.google.com/functions/. Asegúrate de que el proyecto que creaste en el paso 2 sea el proyecto seleccionado actualmente.

Selecciona la my-authenticated-function que implementaste antes. Luego, presiona Borrar.

Si decides borrar todo el proyecto, puedes ir a https://console.cloud.google.com/cloud-resource-manager, seleccionar el proyecto que creaste en el Paso 2 y elegir Borrar. Si borras el proyecto, deberás cambiar los proyectos en tu SDK de Cloud. Para ver la lista de todos los proyectos disponibles, ejecuta gcloud projects list.