Saiba como invocar funções autenticadas do Cloud Run

1. Introdução

Visão geral

As funções do Cloud Run são uma solução de computação leve para desenvolvedores. Elas criam funções autônomas e de finalidade única que podem ser acionadas usando HTTPS ou responder a CloudEvents sem a necessidade de gerenciar um servidor ou ambiente de execução. Saiba mais sobre as funções do Cloud Run na nossa postagem do blog.

Há duas abordagens principais para controlar as invocações de funções do Cloud Run: proteger o acesso com base na identidade e proteger o acesso usando controles de acesso baseados na rede. Este codelab se concentra na primeira abordagem e mostra três cenários para proteger o acesso com base na identidade para invocar uma função:

1. Use seu token de identidade do gcloud para invocar uma função para fins de desenvolvimento e teste locais
2. Impersonar uma conta de serviço ao desenvolver e testar localmente para usar as mesmas credenciais da produção
3. Use as bibliotecas de cliente do Google para processar a autenticação nas APIs do Google Cloud, por exemplo, quando um serviço precisa invocar uma função.

O que você vai aprender

• Como configurar a autenticação em uma função do Cloud Run e verificar se a autenticação foi configurada corretamente
• Invocar uma função autenticada em um ambiente de desenvolvimento local fornecendo o token para sua identidade do gcloud
• Como criar uma conta de serviço e conceder a ela o papel apropriado para invocar uma função
• Como falsificar um serviço em um ambiente de desenvolvimento local que tenha as funções adequadas para invocar uma função

2. Configuração e requisitos

Pré-requisitos

• Você fez login no console do Cloud
• Você já implantou uma função do Cloud Run acionada por HTTP. Confira o exemplo do guia de início rápido.
• (opcional) Para o terceiro cenário, este codelab usa Node.js e npm como exemplo, mas você pode usar qualquer ambiente de execução compatível com as bibliotecas de cliente do Google Auth.

Ativar o Cloud Shell

1. No Console do Cloud, clique em Ativar o Cloud Shell.

Se esta for a primeira vez que você iniciar o Cloud Shell, uma tela intermediária vai aparecer com uma descrição dele. Se esse for o caso, clique em Continuar.

Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB e é executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Grande parte do trabalho neste codelab, se não todo, pode ser feito em um navegador.

Depois de se conectar ao Cloud Shell, você vai notar que sua conta já está autenticada e que o projeto está configurado com seu ID do projeto.

2. Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:

gcloud auth list

Resposta ao comando

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

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

Observação: a ferramenta de linha de comando gcloud é a poderosa e unificada do Google Cloud. Ela vem pré-instalado no Cloud Shell. Essa ferramenta aceita preenchimento com tabulação. Para mais informações, consulte a visão geral da ferramenta de linha de comando gcloud.

3. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto:

gcloud config list project

Resposta ao comando

[core]
project = <PROJECT_ID>

Se o projeto não estiver configurado, configure-o usando este comando:

gcloud config set project <PROJECT_ID>

Resposta ao comando

Updated property [core/project].

Observação:se você estiver concluindo este tutorial fora do Cloud Shell, siga as instruções em Configurar o Application Default Credentials.

3. Criar e testar uma função autenticada do Cloud Run

A autenticação obrigatória significa que o principal que invoca a função precisa ter o papel de invocador do Cloud Run. Caso contrário, a função vai retornar um erro 403 proibido. Este codelab vai mostrar como conceder as funções de invocador adequadas a um participante.

Configurar variáveis de ambiente locais para comandos gcloud simplificados

Primeiro, você vai criar algumas variáveis de ambiente para melhorar a legibilidade dos comandos gcloud usados neste codelab.

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

Criar o código-fonte da função

Embora este codelab use o Node.js, você pode usar qualquer ambiente de execução compatível com as bibliotecas de cliente do Google Auth.

Primeiro, crie um diretório e acesse-o.

mkdir auth-function-codelab && cd $_

Em seguida, crie o arquivo package.json.

touch package.json

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

Em seguida, crie o arquivo de origem 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

Criar a função autenticada

Estas são as etapas para criar uma função autenticada para o ambiente de execução do nodejs20. No entanto, você pode usar qualquer ambiente de execução compatível com as bibliotecas de cliente do Google Auth.

FUNCTION_NAME=authenticated-function-codelab
ENTRY_POINT=helloWorld

Para implantar uma função do Cloud Run diretamente no Cloud Run, execute o seguinte comando:

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

e salve o URL da função como uma variável de ambiente para usar mais tarde.

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

Se você preferir implantar como um Cloud Functions de 2ª geração, use o seguinte comando:

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

e salve o URL da função como uma variável de ambiente para usar mais tarde.

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

Verifique se a função requer autenticação tentando invocar como um autor de chamada anônimo

Você vai invocar a função sem autenticação para verificar se recebeu um erro 403 esperado.

Em uma linha de comando, execute o seguinte comando curl:

curl -i $FUNCTION_URL

O resultado será o seguinte:

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

Agora você está pronto para conferir três cenários em que pode invocar sua função fornecendo autenticação.

4. Cenário 1: usar o token de identidade do gcloud

Como desenvolvedor, você vai querer uma maneira de testar sua função enquanto a desenvolve localmente. Nesta seção, você vai realizar um teste rápido para verificar se a função está autenticada corretamente usando sua própria identidade.

Execute o seguinte comando para verificar se você está autenticado usando gcloud:

gcloud auth list

Você vai encontrar um asterisco ao lado da identidade ativa, por exemplo:

Credentialed Accounts
ACTIVE  ACCOUNT

*       <my_account>@<my_domain.com>

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

Confira mais informações sobre como configurar o gcloud init e o gcloud auth login na documentação.

Em seguida, invoque a função e transmita seu token de identidade.

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

Agora você verá o resultado:

Hello World!

Solução de problemas

Se você receber um erro 403 Forbidden, verifique se sua identidade tem o papel Invocador do Cloud Run. Use o Console do IAM para verificar os papéis atribuídos a um principal.

Embora usar seu próprio token de identidade seja uma maneira rápida de testar a função durante o desenvolvimento, o autor da chamada da função autenticada vai precisar das funções adequadas. Caso contrário, o autor da chamada vai receber um erro 403 "Proibido".

Siga o princípio do menor privilégio limitando o número de identidades e contas de serviço que têm funções para invocar a função. No próximo cenário, você vai aprender a criar uma nova conta de serviço e conceder a ela os papéis apropriados para invocar a função.

5. Cenário 2: personificar uma conta de serviço

Nesse cenário, você impersonifica (ou seja, assume as permissões de) uma conta de serviço para invocar uma função ao desenvolver e testar localmente. Ao falsificar uma conta de serviço, você pode testar sua função com as mesmas credenciais da produção.

Ao fazer isso, você não apenas verifica os papéis, mas também segue o princípio do menor privilégio, não precisando conceder o papel de invocador do Cloud Function a outras identidades apenas para fins de teste local.

Para este codelab, você vai criar uma nova conta de serviço que só tem funções para invocar a função criada neste codelab.

Criar uma nova conta de serviço

Primeiro, você vai criar algumas variáveis de ambiente adicionais para representar as contas de serviço usadas nos comandos do gcloud.

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

Em seguida, você vai criar a conta de serviço.

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

E conceda o papel de chamador do Cloud Run à conta de serviço:

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

Invocar a função representando a conta de serviço

Para isso, você vai representar a conta de serviço recém-criada ao receber o token de ID dela.

Adicionar papéis obrigatórios para a usurpação de identidade

Para personificar uma conta de serviço, sua conta de usuário precisa ter o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) para gerar um token de identificação para a conta de serviço.

É possível executar os comandos a seguir para conceder esse papel à sua conta de usuário ativa:

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'

Usar o token de ID da conta de serviço

Aguarde alguns minutos para que as permissões sejam propagadas. Agora você pode invocar a função transmitindo o token de ID da conta de serviço.

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

Você vai ver o seguinte:

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. Cenário 3: usar as bibliotecas de cliente do Google

Nesta última parte do codelab, você vai executar um pequeno serviço localmente para gerar um token de ID para uma conta de serviço e, em seguida, chamar a função usando as bibliotecas de cliente do Google Auth e as credenciais padrão do aplicativo (ADC). Leia mais sobre as bibliotecas de cliente do Google na seção "Explicações sobre as bibliotecas de cliente" da documentação.

O uso do ADC é especialmente importante quando você quer escrever e testar sua função localmente (por exemplo, no laptop, no Cloud Shell etc.) enquanto interage com outros recursos do Google Cloud (por exemplo, Cloud Storage, API Vision etc.). Neste exemplo, você vai aprender a fazer um serviço invocar outra função que exige autenticação. Para mais informações sobre o ADC e o desenvolvimento local, consulte a postagem do blog Como desenvolver e testar suas funções do Cloud localmente | Blog do Google Cloud.

Executar o comando gcloud para falsificar uma conta de serviço

O ADC encontra credenciais automaticamente com base no ambiente do aplicativo e as usa para se autenticar nas APIs do Google Cloud. A flag –impersonate-service-account permite representar uma conta de serviço usando a identidade dela para autenticação nas APIs do Google Cloud.

Para falsificar uma conta de serviço, execute o seguinte comando:

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

Agora você está executando comandos gcloud como essa conta de serviço, em vez da sua identidade.

Criar e executar um serviço para invocar uma função autenticada

Cada ambiente de execução tem a própria biblioteca de cliente do Google Auth que você pode instalar. Neste codelab, você vai aprender a criar e executar um app Node.js localmente.

Siga estas etapas para Node.js:

1. Crie um novo diretório

mkdir local-dev && cd $_

2. Criar um novo app Node.js

npm init -y

3. Instalar a biblioteca de cliente do Google Auth

npm install google-auth-library

4. Crie um arquivo index.js.
5. Extraia o URL da função do Cloud Run, que você vai adicionar ao código na próxima etapa.

echo $FUNCTION_URL

6. Adicione o seguinte código ao index.js. Mude a variável targetAudience para o URL da função do 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. Executar o app

node index.js

A mensagem "Hello World!" vai aparecer.

Solução de problemas

Se você receber um erro "A permissão 'iam.serviceAccounts.getOpenIdToken' foi negada no recurso (ou pode não existir)", aguarde alguns minutos para que o papel de criador do token da conta de serviço seja propagado.

Se você recebeu o erro "Não é possível buscar o token de ID neste ambiente. Use o GCE ou defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como um arquivo JSON de credenciais da conta de serviço", talvez você tenha esquecido de executar o comando

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

7. Parabéns!

Parabéns por concluir o codelab.

Recomendamos a análise da documentação sobre como proteger as funções do Cloud Run.

Também recomendamos esta postagem do blog sobre desenvolvimento local com as Funções do Cloud Run para saber como desenvolver e testar sua função do Cloud Run no ambiente de desenvolvimento local.

O que vimos

• Como configurar a autenticação em uma função do Cloud Run e verificar se a autenticação foi configurada corretamente
• Invocar uma função autenticada em um ambiente de desenvolvimento local fornecendo o token para sua identidade do gcloud
• Como criar uma conta de serviço e conceder a ela o papel apropriado para invocar uma função
• Como representar um serviço de um ambiente de desenvolvimento local que tenha os papéis apropriados para invocar uma função

8. Limpar

Para evitar cobranças acidentais (por exemplo, se essa função do Cloud for invocada acidentalmente mais vezes do que sua alocação mensal de invocação de função do Cloud Run no nível sem custo financeiro), exclua a função do Cloud ou o projeto criado na etapa 2.

Para parar de representar a conta de serviço, faça login novamente usando sua identidade:

gcloud auth application-default login

Para excluir a função do Cloud Run, acesse o Console do Cloud Run em https://console.cloud.google.com/functions/. Verifique se o projeto criado na etapa 2 é o selecionado.

Selecione a my-authenticated-function que você implantou anteriormente. Em seguida, clique em Excluir.

Se você quiser excluir o projeto inteiro, acesse https://console.cloud.google.com/cloud-resource-manager, selecione o projeto criado na etapa 2 e escolha "Excluir". Se você excluir o projeto, vai precisar mudar os projetos no Cloud SDK. Para conferir a lista de todos os projetos disponíveis, execute gcloud projects list.