1. Visão geral
Ao criar microsserviços ou aplicativos multiagente no Cloud Run, os serviços de back-end internos não podem ficar abertos para a Internet pública. Em vez disso, configure cada serviço de back-end para exigir autenticação (--no-allow-unauthenticated) e conceda o papel do IAM de invocador do Cloud Run (roles/run.invoker) apenas aos autores de chamada autorizados.
Tradicionalmente, para chamar um serviço autenticado do Cloud Run, o aplicativo de chamada precisa realizar a injeção manual de token no código. Antes de enviar uma solicitação HTTP, seu código consulta o servidor de metadados do Compute para receber um token de ID do OpenID Connect (OIDC) assinado pelo Google. Esse token tem como escopo o URL de público-alvo do serviço de destino, e seu código o anexa ao cabeçalho Authorization: Bearer. Escrever e manter a estrutura de autenticação no código do aplicativo gera um atrito desnecessário:
- Ela acopla sua lógica de negócios às bibliotecas de autenticação do Google Cloud, reduzindo a legibilidade e a portabilidade entre ambientes.
- A lógica de aquisição de tokens varia de acordo com os tipos de destino e os modos de segurança. Por exemplo, o Cloud Run espera tokens de ID do OIDC, as APIs do Google esperam tokens de acesso do OAuth 2.0 e o mTLS exige tokens vinculados.
O Express Link do Cloud Run (pré-lançamento) remove a injeção manual de tokens do código do aplicativo. Ative a rede ambiente no serviço de chamada (origem) do Cloud Run e crie um recurso declarativo ExpressLink que vincule o serviço de origem ao de destino. Um proxy sidecar gerenciado pelo Google intercepta solicitações HTTP de texto simples de saída para o destino, injeta automaticamente o token de identidade do serviço de chamada e criptografa a conexão com o destino.
Neste codelab, você vai comparar as duas abordagens com o mesmo serviço de back-end particular:
- Implantar um serviço de destino particular e um serviço de autor da chamada (caller-oidc) que busca um token de ID do OIDC no Compute Metadata Server em Python. Essa etapa confirma a conectividade de ponta a ponta com o back-end e mostra o código de autenticação necessário sem o Express Link.
- Implante um segundo serviço de chamada (caller-express-link) sem o código de busca de tokens de metadados e conecte-o ao serviço de destino usando a rede ambiente e um link expresso.
PART 1: WITHOUT EXPRESS LINK (caller-oidc) +----------------------------------------------+ +-----------------+ | Caller Service (caller-oidc) | HTTPS | Destination | | | + token | (destination) | | App Container | -------> | | | 1. Parse audience URL with urllib.parse | | Verifies caller | | 2. Fetch OIDC ID token via google-auth | | has IAM role | | 3. Set Authorization: Bearer header | | run.invoker | +----------------------------------------------+ +-----------------+ PART 2: WITH EXPRESS LINK (caller-express-link) +----------------------------------------------+ +-----------------+ | Caller Service (caller-express-link) | HTTPS | Destination | | +----------------+ +----------------+ | + token | (destination) | | | App Container | HTTP | Ambient | | -------> | | | | requests.get() | ---> | Sidecar Proxy | | | Same service | | | (no auth code) | | (Express Link) | | | as Part 1 | | +----------------+ +----------------+ | | (unchanged) | +----------------------------------------------+ +-----------------+
Pré-requisitos
- Noções básicas sobre Python e serviços da Web HTTP
- Conhecimento básico das contas de serviço do Google Cloud IAM e das implantações do Cloud Run
O que você vai aprender
- Como implantar um serviço de destino de nuvem privada do Cloud Run que aplica a autenticação do IAM
- Como autenticar manualmente solicitações entre serviços em Python usando tokens de ID do OIDC
google-authdo servidor de metadados para verificar a conectividade de referência - Como remover o código de busca manual de tokens e implantar um serviço de chamada do Cloud Run com a rede de ambiente ativada
- Como criar um Express Link do Cloud Run para que o serviço de chamada possa invocar um serviço de destino autenticado sem código de autenticação
O que você vai criar
- destination: um serviço particular do Python Flask no Cloud Run que expõe um endpoint
/ping. - caller-oidc: um serviço Python Flask que chama destination buscando e injetando manualmente tokens de ID do OIDC no código do aplicativo.
- caller-express-link: um serviço Python Flask lado a lado com código de injeção de token zero que chama o mesmo serviço de destino por um Express Link.
O que é necessário
- Um navegador da Web, como o Chrome
- Um projeto na nuvem do Google Cloud com faturamento ativado e permissões para criar contas de serviço do IAM, serviços do Cloud Run e recursos do Network Services
2. Configurar o ambiente
Configure um projeto do Google Cloud
- Se você ainda não tiver uma Conta do Google, crie uma.
- Use uma conta pessoal em vez de uma conta escolar ou de trabalho. As contas escolares e de trabalho podem ter restrições que impedem a ativação das APIs necessárias para este laboratório.
- Faça login no Console do Google Cloud.
- Ative o faturamento no console do Cloud.
- A conclusão deste laboratório custa menos de US $1 em recursos do Cloud.
- Siga as etapas no final deste laboratório para excluir recursos e evitar cobranças adicionais.
- Novos usuários estão qualificados para o teste sem custo financeiro de US$ 300.
- Crie um novo projeto ou reutilize um atual.
- Se você receber um erro sobre a cota do projeto, reutilize um projeto atual ou exclua um projeto atual para criar um novo.
Iniciar o Cloud Shell
Neste codelab, você vai usar o Cloud Shell, um ambiente de linha de comando baseado em navegador pré-instalado com a CLI do Google Cloud (gcloud), Python e curl.
- No console do Google Cloud, clique em Ativar o Cloud Shell na barra de navegação de cima. Se for solicitado, clique em Autorizar.
- Exporte o ID do projeto e a região de implantação e configure
gcloudpara usar$PROJECT_ID. SubstituaYOUR_PROJECT_IDpelo ID do projeto e, se quiser, substituaus-west1por outra região do Cloud Run:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="us-west1"
gcloud config set project "$PROJECT_ID"
- Exporte o número do projeto e a conta ativa do Google Cloud e confirme se as quatro variáveis estão preenchidas:
export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
export ACTIVE_ACCOUNT=$(gcloud config get-value account 2>/dev/null)
echo "PROJECT_ID: $PROJECT_ID | PROJECT_NUMBER: $PROJECT_NUMBER | ACCOUNT: $ACTIVE_ACCOUNT | REGION: $REGION"
Atualizar a gcloud e ativar as APIs
- Atualize os componentes
gcloudpara ter os comandosbetamais recentes para rede ambiental e Express Link:
gcloud components update --quiet
- Ative as APIs do Google Cloud necessárias para implantações de origem do Cloud Run, contas de serviço do IAM, rede de ambiente e link expresso do Network Services:
gcloud services enable \
iam.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
networkservices.googleapis.com \
networksecurity.googleapis.com \
trafficdirector.googleapis.com \
cloudtrace.googleapis.com
criar um diretório de espaço de trabalho
Crie um diretório de trabalho para armazenar as três pastas de serviço que você vai criar neste codelab:
mkdir -p ~/express-link-codelab
cd ~/express-link-codelab
3. Implantar o serviço de destino particular
Primeiro, você vai implantar um serviço privado do Cloud Run chamado destination. Você vai reutilizar esse serviço de destino único para as duas partes do codelab:
- Um serviço de destino nunca realiza a injeção de token de saída.
- Um serviço de destino não precisa ter a Rede Ambiente ativada para receber tráfego por um express link.
- Crie uma conta de serviço dedicada do IAM para o serviço de destino:
gcloud iam service-accounts create destination-identity \
--display-name="Cloud Run destination service account"
- Crie uma pasta
destinatione acesse-a:
mkdir -p ~/express-link-codelab/destination
cd ~/express-link-codelab/destination
- Execute o comando a seguir para criar um arquivo
requirements.txtcom o Flask e o Gunicorn:
cat << 'EOF' > requirements.txt
Flask==3.0.0
gunicorn==21.2.0
EOF
- Execute o comando a seguir para criar um arquivo
main.pyque expõe um endpoint/pingque retorna o nome do serviço do Cloud Run da variável de ambienteK_SERVICE:
cat << 'EOF' > main.py
import os
from flask import Flask
app = Flask(__name__)
@app.route("/ping")
def ping():
service_name = os.environ.get("K_SERVICE", "unknown")
return f"Hello from {service_name}"
if __name__ == "__main__":
app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
EOF
- Implante
destinationda origem com--no-allow-unauthenticatedpara que o Cloud Run rejeite solicitações não autenticadas:
gcloud run deploy destination \
--source . \
--region="$REGION" \
--service-account="destination-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--no-allow-unauthenticated
- Armazene o URL determinista do serviço de destino e o URI completo do recurso em variáveis de ambiente:
export DESTINATION_URL="https://destination-${PROJECT_NUMBER}.${REGION}.run.app"
export DESTINATION_URI="//run.googleapis.com/projects/${PROJECT_NUMBER}/locations/${REGION}/services/destination"
echo "DESTINATION_URL: $DESTINATION_URL"
echo "DESTINATION_URI: $DESTINATION_URI"
- Conceda à sua conta de usuário o papel de invocador do Cloud Run (
roles/run.invoker) emdestinationpara testá-lo diretamente no Cloud Shell:
gcloud run services add-iam-policy-binding destination \
--member="user:$ACTIVE_ACCOUNT" \
--role="roles/run.invoker" \
--region="$REGION"
- Envie uma solicitação autenticada para
/pingusando seu próprio token de identidade para confirmar quedestinationestá em execução:
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$DESTINATION_URL/ping"
Você verá a seguinte resposta:
Hello from destination
4. Chamar o destino sem o Express Link
Antes de apresentar o Express Link, crie caller-oidc para ver o que a autenticação entre serviços exige hoje e verifique se um serviço de chamada pode acessar destination. Para chamar destination com segurança sem o Express Link, é preciso configurar duas camadas:
- Autorização do IAM: conceda à conta de serviço
caller-oidco papelroles/run.invokeremdestination. - Injeção de token no nível do aplicativo: adicione a biblioteca
google-authacaller-oidce analise o URL de destino para extrair o público-alvo raiz do OIDC. Em seguida, busque um token de ID assinado no servidor de metadados e anexeAuthorization: Bearer ID_TOKENà solicitação HTTPS de saída.
Siga estas etapas para configurar e implantar o caller-oidc:
- Crie uma conta de serviço dedicada para
caller-oidc:
gcloud iam service-accounts create caller-oidc-identity \
--display-name="Cloud Run OIDC caller service account"
- Autorize
caller-oidc-identitya invocardestination:
gcloud run services add-iam-policy-binding destination \
--member="serviceAccount:caller-oidc-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/run.invoker" \
--region="$REGION"
- Crie o diretório
caller-oidcao lado dedestination:
mkdir -p ~/express-link-codelab/caller-oidc
cd ~/express-link-codelab/caller-oidc
- Execute o comando a seguir para criar um arquivo
requirements.txt. Adicionegoogle-authespecificamente para processar a recuperação de tokens no contêiner do aplicativo:
cat << 'EOF' > requirements.txt
Flask==3.0.0
google-auth==2.23.0
requests==2.31.0
gunicorn==21.2.0
EOF
- Execute o comando a seguir para criar um arquivo
main.pycom injeção manual de token OIDC:
cat << 'EOF' > main.py
import os
from urllib.parse import urlparse
from flask import Flask, request
from google.auth.transport.requests import Request as GoogleAuthRequest
from google.oauth2 import id_token
import requests
app = Flask(__name__)
@app.route("/ping")
def ping():
service_name = os.environ.get("K_SERVICE", "unknown")
return f"Hello from {service_name}"
@app.route("/")
def call_destination():
target_url = request.args.get("target_url")
if not target_url:
return "Error: target_url query parameter not set.", 400
try:
# 1. Extract the root service URL (scheme + host) for the OIDC audience claim
parsed_url = urlparse(target_url)
target_audience = f"{parsed_url.scheme}://{parsed_url.netloc}"
# 2. Fetch a Google-signed OIDC ID token from the metadata server
auth_req = GoogleAuthRequest()
token = id_token.fetch_id_token(auth_req, target_audience)
# 3. Inject the token as an HTTP Bearer header
headers = {"Authorization": f"Bearer {token}"}
response = requests.get(target_url, headers=headers, timeout=10)
return f"I called the destination and it replied: '{response.text}'"
except Exception as e:
return f"Error calling destination: {str(e)}", 500
if __name__ == "__main__":
app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
EOF
- Implante
caller-oidcno Cloud Run:
gcloud run deploy caller-oidc \
--source . \
--region="$REGION" \
--service-account="caller-oidc-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--no-allow-unauthenticated
- Conceda à sua conta de usuário permissão para invocar
caller-oidc:
gcloud run services add-iam-policy-binding caller-oidc \
--member="user:$ACTIVE_ACCOUNT" \
--role="roles/run.invoker" \
--region="$REGION"
- Armazene o URL determinista de
caller-oidce invoque-o, transmitindo o URL HTTPS$DESTINATION_URL/pingcomotarget_url:
export CALLER_OIDC_URL="https://caller-oidc-${PROJECT_NUMBER}.${REGION}.run.app"
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$CALLER_OIDC_URL/?target_url=$DESTINATION_URL/ping"
Você vai receber uma resposta de destination:
I called the destination and it replied: 'Hello from destination'
5. Implantar o serviço de chamada para o Express Link
Agora você vai criar um segundo serviço de chamada chamado caller-express-link em um diretório irmão. Com o Express Link, o caller-express-link não precisa de nenhum código de injeção de token. Ele chama o requests.get(target_url, timeout=10) diretamente.
- Crie uma conta de serviço dedicada para
caller-express-link:
gcloud iam service-accounts create caller-express-link-identity \
--display-name="Cloud Run Express Link caller service account"
- Conceda a
caller-express-link-identityo papelroles/trafficdirector.clientpara que o sidecar gerenciado da Rede Ambiente possa baixar a configuração de roteamento e segurança do Express Link. Conceda tambémroles/cloudtrace.agentpara que o arquivo secundário possa exportar períodos de trace:
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/trafficdirector.client"
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/cloudtrace.agent"
- Crie o diretório
caller-express-linkao lado decaller-oidc:
mkdir -p ~/express-link-codelab/caller-express-link
cd ~/express-link-codelab/caller-express-link
- Execute o comando a seguir para criar um arquivo
requirements.txtsemgoogle-auth:
cat << 'EOF' > requirements.txt
Flask==3.0.0
requests==2.31.0
gunicorn==21.2.0
EOF
- Execute o comando a seguir para criar um arquivo
main.pycom uma chamadarequests.get(target_url, timeout=10)simples e sem lógica de injeção de token:
cat << 'EOF' > main.py
import os
from flask import Flask, request
import requests
app = Flask(__name__)
@app.route("/ping")
def ping():
service_name = os.environ.get("K_SERVICE", "unknown")
return f"Hello from {service_name}"
@app.route("/")
def call_destination():
target_url = request.args.get("target_url")
if not target_url:
return "Error: target_url query parameter not set.", 400
try:
response = requests.get(target_url, timeout=10)
return f"I called the destination and it replied: '{response.text}'"
except Exception as e:
return f"Error calling destination: {str(e)}", 500
if __name__ == "__main__":
app.run(host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
EOF
- Execute
diffem../caller-oidc/main.pypara ver o código boilerplate de autenticação que você eliminou:
diff -u ../caller-oidc/main.py main.py || true
- Implante
caller-express-linkusandogcloud beta run deploycom--ambient-networkinge--ambient-scope=globalativados:
gcloud beta run deploy caller-express-link \
--source . \
--region="$REGION" \
--service-account="caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--no-allow-unauthenticated \
--ambient-networking \
--ambient-scope=global
- Verifique se a rede ambiente está ativa em
caller-express-link:
gcloud run services describe caller-express-link --region="$REGION"
No final do resumo da revisão, verifique se Ambient Networking e Ambient Scope aparecem:
Ambient Networking: Enabled Ambient Scope: global
- Conceda à sua conta de usuário permissão para invocar
caller-express-linke autorizecaller-express-link-identitya invocardestination:
gcloud run services add-iam-policy-binding caller-express-link \
--member="user:$ACTIVE_ACCOUNT" \
--role="roles/run.invoker" \
--region="$REGION"
gcloud run services add-iam-policy-binding destination \
--member="serviceAccount:caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/run.invoker" \
--region="$REGION"
- Armazene o URL e o URI de recurso de
caller-express-link, além do URL determinista HTTP (http://) dedestination:
export CALLER_EL_URL="https://caller-express-link-${PROJECT_NUMBER}.${REGION}.run.app"
export CALLER_EL_URI="//run.googleapis.com/projects/${PROJECT_NUMBER}/locations/${REGION}/services/caller-express-link"
export DESTINATION_HTTP_URL="http://destination-${PROJECT_NUMBER}.${REGION}.run.app"
echo "CALLER_EL_URL: $CALLER_EL_URL"
echo "CALLER_EL_URI: $CALLER_EL_URI"
echo "DESTINATION_HTTP_URL: $DESTINATION_HTTP_URL"
- Teste a chamada de
destinationporcaller-express-linkantes de criar um Express Link:
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$CALLER_EL_URL/?target_url=$DESTINATION_HTTP_URL/ping"
Como esperado, a chamada falha com 403 Forbidden porque ainda não há um Express Link para interceptar a solicitação e injetar credenciais:
I called the destination and it replied: ' <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>/ping</code> from this server.</h2> <h2></h2> </body></html> '
6. Conectar os serviços com um Express Link
Agora, você vai declarar um recurso ExpressLink que conecta caller-express-link (o serviço de origem) a destination, sem mudar uma única linha de código ou reimplantar qualquer um dos serviços do Cloud Run.
- Crie o recurso de express link no local
global:
gcloud beta network-services express-links create caller-to-destination \
--location=global \
--description="Express Link from caller-express-link to destination" \
--source-services="$CALLER_EL_URI" \
--destination-services="$DESTINATION_URI"
- Liste seus Express Links para confirmar se o recurso existe:
gcloud beta network-services express-links list --location=global
Resposta ao comando:
NAME caller-to-destination
- Inspecione os detalhes de configuração do Express Link:
gcloud beta network-services express-links describe caller-to-destination --location=global
Resposta ao comando:
createTime: '2026-10-27T19:30:04.492105068Z' description: Express Link from caller-express-link to destination destination: services: - //run.googleapis.com/projects/PROJECT_NUMBER/locations/us-west1/services/destination etag: ... name: projects/PROJECT_ID/locations/global/expressLinks/caller-to-destination source: services: - //run.googleapis.com/projects/PROJECT_NUMBER/locations/us-west1/services/caller-express-link updateTime: '2026-10-27T19:30:11.309054865Z'
- Execute novamente a mesma solicitação
curlemcaller-express-link:
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$CALLER_EL_URL/?target_url=$DESTINATION_HTTP_URL/ping"
Desta vez, o arquivo secundário do Ambient intercepta a solicitação HTTP para destination, injeta o token de identidade para caller-express-link-identity, faz upgrade da conexão para TLS e retorna a resposta do destino:
I called the destination and it replied: 'Hello from destination'
Comparar a injeção manual de tokens com o Express Link
A tabela a seguir resume o que mudou entre caller-oidc e caller-express-link:
Dimensão | Sem o Express Link ( | Com o Express Link ( |
Bibliotecas Auth em | Requer a coluna " | Nenhum (somente |
Chamada de saída em | Analisar o URL do público-alvo, chamar |
|
Esquema de URL de destino no app |
|
|
Configuração do Cloud Run do autor da chamada | Implantação padrão |
|
Configuração do Cloud Run de destino |
| Inalterado ( |
7. Limpar
Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.
- Exclua o recurso do Express Link:
gcloud beta network-services express-links delete caller-to-destination --location=global --quiet
- Exclua os três serviços do Cloud Run:
gcloud run services delete caller-express-link --region="$REGION" --quiet
gcloud run services delete caller-oidc --region="$REGION" --quiet
gcloud run services delete destination --region="$REGION" --quiet
- Remova as vinculações da política do IAM para envolvidos no projeto e exclua as três contas de serviço:
gcloud projects remove-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/trafficdirector.client" \
--quiet
gcloud projects remove-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/cloudtrace.agent" \
--quiet
gcloud iam service-accounts delete "caller-express-link-identity@${PROJECT_ID}.iam.gserviceaccount.com" --quiet
gcloud iam service-accounts delete "caller-oidc-identity@${PROJECT_ID}.iam.gserviceaccount.com" --quiet
gcloud iam service-accounts delete "destination-identity@${PROJECT_ID}.iam.gserviceaccount.com" --quiet
- (Opcional) Se você criou um projeto dedicado do Google Cloud estritamente para este codelab, é possível excluir o projeto inteiro:
# Run only if you want to delete the entire project and all its resources
gcloud projects delete "$PROJECT_ID"
8. Parabéns
Você implantou um serviço de back-end particular do Cloud Run e o chamou usando a injeção manual de token do OIDC em Python. Em seguida, você substituiu todo o código de autenticação no nível do aplicativo por um Cloud Run Express Link declarativo.
O que você aprendeu
- Por que a injeção manual de tokens OIDC acopla a lógica de negócios do aplicativo às bibliotecas de autenticação e aos modos de segurança da plataforma
- Como implantar um serviço de destino autenticado do Cloud Run que funciona sem alterações com ou sem o Express Link
- Como ativar a rede ambiente (
--ambient-networkingcom--ambient-scope=global) e conceder permissões de cliente do Traffic Director (roles/trafficdirector.client) em um serviço de chamada do Cloud Run - Como criar e inspecionar um recurso
ExpressLinkdo Network Services que injeta automaticamente tokens de identidade e faz upgrade de chamadashttp://de texto simples do seu contêiner para conexões TLS criptografadas
Próximas etapas
- Leia Como autenticar serviço a serviço na documentação do Cloud Run.
- Confira as notas da versão do Cloud Run para ver as atualizações mais recentes sobre a rede de ambiente e o Express Link.