Simplify Cloud Run service-to-service authentication with Express Link

1. Overview

When you build microservices or multi-agent applications on Cloud Run, internal backend services shouldn't be open to the public internet. Instead, you configure each backend service to require authentication (--no-allow-unauthenticated) and grant the Cloud Run Invoker (roles/run.invoker) IAM role only to authorized callers.

Traditionally, calling an authenticated Cloud Run service requires your calling application to perform manual token injection in code. Before sending an HTTP request, your code queries the Compute Metadata Server for a Google-signed OpenID Connect (OIDC) ID token. That token is scoped to the destination service's audience URL, and your code attaches it to the Authorization: Bearer header. Writing and maintaining authentication plumbing inside application code introduces unnecessary friction:

  • It couples your business logic to Google Cloud authentication libraries, reducing readability and portability across environments.
  • Token acquisition logic varies across destination types and security modes. For example, Cloud Run expects OIDC ID tokens, Google APIs expect OAuth 2.0 access tokens, and mTLS requires bound tokens.

Cloud Run Express Link (Preview) removes manual token injection from your application code. You enable Ambient Networking on the calling (source) Cloud Run service and create a declarative ExpressLink resource that binds the source service to the destination service. A Google-managed sidecar proxy intercepts outbound plaintext HTTP requests to the destination, injects the caller service's identity token automatically, and encrypts the connection to the destination.

In this codelab, you'll compare both approaches against the same private backend service:

  1. Deploy a private destination service and a caller service (caller-oidc) that fetches an OIDC ID token from the Compute Metadata Server in Python. This step confirms end-to-end connectivity to the backend and shows the authentication code required without Express Link.
  2. Deploy a second caller service (caller-express-link) with the metadata token-fetching code removed, and connect it to the destination service using Ambient Networking and an Express Link.
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)     |
+----------------------------------------------+          +-----------------+

Prerequisites

  • Basic familiarity with Python and HTTP web services
  • Basic familiarity with Google Cloud IAM service accounts and Cloud Run deployments

What you'll learn

  • How to deploy a private Cloud Run destination service that enforces IAM authentication
  • How to authenticate service-to-service requests manually in Python using google-auth OIDC ID tokens from the metadata server to verify baseline connectivity
  • How to remove manual token-fetching code and deploy a Cloud Run caller service with Ambient Networking enabled
  • How to create a Cloud Run Express Link so your caller service can invoke an authenticated destination service with zero authentication code

What you'll build

  • destination: A private Python Flask service on Cloud Run that exposes a /ping endpoint
  • caller-oidc: A Python Flask service that calls destination by manually fetching and injecting OIDC ID tokens in application code
  • caller-express-link: A side-by-side Python Flask service with zero token-injection code that calls the same destination service through an Express Link

What you'll need

  • A web browser, such as Chrome
  • A Google Cloud project with billing enabled and permissions to create IAM service accounts, Cloud Run services, and Network Services resources

2. Set up your environment

Set up a Google Cloud project

  1. If you don't already have a Google Account, you must create a Google Account.
    • Use a personal account instead of a work or school account. Work and school accounts may have restrictions that prevent you from enabling the APIs needed for this lab.
  2. Sign-in to the Google Cloud Console.
  3. Enable billing in the Cloud Console.
    • Completing this lab should cost less than $1 USD in Cloud resources.
    • You can follow the steps at the end of this lab to delete resources to avoid further charges.
    • New users are eligible for the $300 USD Free Trial.
  4. Create a new project or choose to reuse an existing project.
    • If you see an error about project quota, reuse an existing project or delete an existing project to create a new project.

Start Cloud Shell

In this codelab, you use Cloud Shell, a browser-based command-line environment preinstalled with the Google Cloud CLI (gcloud), Python, and curl.

  1. In the Google Cloud console, click Activate Cloud Shell in the top navigation bar. If prompted, click Authorize.
  2. Export your project ID and deployment region, and configure gcloud to use $PROJECT_ID. Replace YOUR_PROJECT_ID with your project ID, and optionally replace us-west1 with another Cloud Run region:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="us-west1"
gcloud config set project "$PROJECT_ID"
  1. Export your project number and active Google Cloud account, and confirm that all four variables are populated:
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"

Update gcloud and enable APIs

  1. Update your gcloud components so you have the latest beta commands for Ambient Networking and Express Link:
gcloud components update --quiet
  1. Enable the required Google Cloud APIs for Cloud Run source deployments, IAM service accounts, Ambient Networking, and Network Services Express Link:
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

Create a workspace directory

Create a working directory to hold the three service folders you'll build in this codelab:

mkdir -p ~/express-link-codelab
cd ~/express-link-codelab

3. Deploy the private destination service

First, you'll deploy a private Cloud Run service named destination. You'll reuse this single destination service for both parts of the codelab:

  • A destination service never performs outbound token injection.
  • A destination service doesn't need Ambient Networking enabled to receive traffic over an Express Link.
  1. Create a dedicated IAM service account for the destination service:
gcloud iam service-accounts create destination-identity \
    --display-name="Cloud Run destination service account"
  1. Create a destination folder and move into it:
mkdir -p ~/express-link-codelab/destination
cd ~/express-link-codelab/destination
  1. Run the following command to create a requirements.txt file with Flask and Gunicorn:
cat << 'EOF' > requirements.txt
Flask==3.0.0
gunicorn==21.2.0
EOF
  1. Run the following command to create a main.py file that exposes a /ping endpoint returning the Cloud Run service name from the K_SERVICE environment variable:
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
  1. Deploy destination from source with --no-allow-unauthenticated so Cloud Run rejects unauthenticated requests:
gcloud run deploy destination \
    --source . \
    --region="$REGION" \
    --service-account="destination-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
    --no-allow-unauthenticated
  1. Store the destination service's deterministic URL and full resource URI in environment variables:
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"
  1. Grant your user account the Cloud Run Invoker (roles/run.invoker) role on destination so you can test it directly from Cloud Shell:
gcloud run services add-iam-policy-binding destination \
    --member="user:$ACTIVE_ACCOUNT" \
    --role="roles/run.invoker" \
    --region="$REGION"
  1. Send an authenticated request to /ping using your own identity token to confirm destination is running:
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$DESTINATION_URL/ping"

You should see the following response:

Hello from destination

4. Call the destination without Express Link

Before introducing Express Link, build caller-oidc to see what service-to-service authentication requires today and verify that a calling service can reach destination. To call destination securely without Express Link, you must configure two layers:

  • IAM authorization: Grant the caller-oidc service account the roles/run.invoker role on destination.
  • Application-level token injection: Add the google-auth library to caller-oidc and parse the target URL to extract the root OIDC audience. Then fetch a signed ID token from the metadata server and attach Authorization: Bearer ID_TOKEN to the outbound HTTPS request.

Follow these steps to configure and deploy caller-oidc:

  1. Create a dedicated service account for caller-oidc:
gcloud iam service-accounts create caller-oidc-identity \
    --display-name="Cloud Run OIDC caller service account"
  1. Authorize caller-oidc-identity to invoke destination:
gcloud run services add-iam-policy-binding destination \
    --member="serviceAccount:caller-oidc-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region="$REGION"
  1. Create the caller-oidc directory alongside destination:
mkdir -p ~/express-link-codelab/caller-oidc
cd ~/express-link-codelab/caller-oidc
  1. Run the following command to create a requirements.txt file. Notice that you must add google-auth specifically to handle token retrieval in your application container:
cat << 'EOF' > requirements.txt
Flask==3.0.0
google-auth==2.23.0
requests==2.31.0
gunicorn==21.2.0
EOF
  1. Run the following command to create a main.py file with manual OIDC token injection:
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
  1. Deploy caller-oidc to Cloud Run:
gcloud run deploy caller-oidc \
    --source . \
    --region="$REGION" \
    --service-account="caller-oidc-identity@${PROJECT_ID}.iam.gserviceaccount.com" \
    --no-allow-unauthenticated
  1. Grant your user account permission to invoke caller-oidc:
gcloud run services add-iam-policy-binding caller-oidc \
    --member="user:$ACTIVE_ACCOUNT" \
    --role="roles/run.invoker" \
    --region="$REGION"
  1. Store the deterministic URL of caller-oidc and invoke it, passing the HTTPS URL $DESTINATION_URL/ping as target_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"

You should receive a successful reply from destination:

I called the destination and it replied: 'Hello from destination'

5. Deploy the caller service for Express Link

Now you'll build a second caller service named caller-express-link in a sibling directory. With Express Link, caller-express-link needs zero token-injection code—it calls requests.get(target_url, timeout=10) directly.

  1. Create a dedicated service account for caller-express-link:
gcloud iam service-accounts create caller-express-link-identity \
    --display-name="Cloud Run Express Link caller service account"
  1. Grant caller-express-link-identity the roles/trafficdirector.client role so the managed Ambient Networking sidecar can download Express Link routing and security configuration. Also grant roles/cloudtrace.agent so the sidecar can export trace spans:
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"
  1. Create the caller-express-link directory alongside caller-oidc:
mkdir -p ~/express-link-codelab/caller-express-link
cd ~/express-link-codelab/caller-express-link
  1. Run the following command to create a requirements.txt file without google-auth:
cat << 'EOF' > requirements.txt
Flask==3.0.0
requests==2.31.0
gunicorn==21.2.0
EOF
  1. Run the following command to create a main.py file with a plain requests.get(target_url, timeout=10) call and no token-injection logic:
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
  1. Run diff against ../caller-oidc/main.py to see the authentication boilerplate you eliminated:
diff -u ../caller-oidc/main.py main.py || true
  1. Deploy caller-express-link using gcloud beta run deploy with --ambient-networking and --ambient-scope=global enabled:
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
  1. Verify that Ambient Networking is active on caller-express-link:
gcloud run services describe caller-express-link --region="$REGION"

At the end of the revision summary, verify that Ambient Networking and Ambient Scope appear:

  Ambient Networking: Enabled
  Ambient Scope:     global
  1. Grant your user account permission to invoke caller-express-link, and authorize caller-express-link-identity to invoke destination:
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"
  1. Store the URL and resource URI of caller-express-link, along with the HTTP (http://) deterministic URL of destination:
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"
  1. Test calling destination through caller-express-link before creating an Express Link:
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$CALLER_EL_URL/?target_url=$DESTINATION_HTTP_URL/ping"

As expected, the call fails with 403 Forbidden because no Express Link exists yet to intercept the request and inject credentials:

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. Connect the services with an Express Link

Now you'll declare an ExpressLink resource connecting caller-express-link (the source service) to destination—without changing a single line of code or redeploying either Cloud Run service.

  1. Create the Express Link resource in the global location:
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"
  1. List your Express Links to confirm the resource exists:
gcloud beta network-services express-links list --location=global

Command output:

NAME
caller-to-destination
  1. Inspect the Express Link configuration details:
gcloud beta network-services express-links describe caller-to-destination --location=global

Command output:

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'
  1. Re-run the exact same curl request against caller-express-link:
TOKEN=$(gcloud auth print-identity-token)
curl -H "Authorization: Bearer $TOKEN" "$CALLER_EL_URL/?target_url=$DESTINATION_HTTP_URL/ping"

This time, the Ambient sidecar intercepts the HTTP request to destination, injects the identity token for caller-express-link-identity, upgrades the connection to TLS, and returns the destination's response:

I called the destination and it replied: 'Hello from destination'

The following table summarizes what changed between caller-oidc and caller-express-link:

Dimension

Without Express Link (caller-oidc)

With Express Link (caller-express-link)

Auth libraries in requirements.txt

Requires google-auth

None (Flask, requests, gunicorn only)

Outbound call in main.py

Parse audience URL, call id_token.fetch_id_token(), attach Authorization: Bearer header

Plain requests.get(target_url, timeout=10)

Target URL scheme in app

https://destination-PROJECT_NUMBER.REGION.run.app

http://destination-PROJECT_NUMBER.REGION.run.app (upgraded to TLS by Ambient sidecar)

Caller Cloud Run configuration

Standard deployment

--ambient-networking --ambient-scope=global + roles/trafficdirector.client on caller service account

Destination Cloud Run configuration

--no-allow-unauthenticated + roles/run.invoker

Unchanged (--no-allow-unauthenticated + roles/run.invoker)

7. Clean up

To avoid incurring ongoing charges to your Google Cloud account, delete the resources you created during this codelab.

  1. Delete the Express Link resource:
gcloud beta network-services express-links delete caller-to-destination --location=global --quiet
  1. Delete the three Cloud Run services:
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
  1. Remove the project-level IAM policy bindings and delete the three service accounts:
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
  1. (Optional) If you created a dedicated Google Cloud project strictly for this codelab, you can delete the entire project:
# Run only if you want to delete the entire project and all its resources
gcloud projects delete "$PROJECT_ID"

8. Congratulations

You deployed a private Cloud Run backend service and called it using manual OIDC token injection in Python. You then replaced all application-level authentication code with a declarative Cloud Run Express Link.

What you learned

  • Why manual OIDC token injection couples application business logic to platform authentication libraries and security modes
  • How to deploy an authenticated Cloud Run destination service that works unchanged with or without Express Link
  • How to enable Ambient Networking (--ambient-networking with --ambient-scope=global) and grant Traffic Director client permissions (roles/trafficdirector.client) on a calling Cloud Run service
  • How to create and inspect a Network Services ExpressLink resource that automatically injects identity tokens and upgrades plaintext http:// calls from your container to encrypted TLS connections

Next steps