GSP499

Overview

In this lab, you build a minimal web application with Cloud Run, then explore various ways to use Identity-Aware Proxy (IAP) to restrict access to the application and provide user identity information to it. Your app will:

• Display a welcome page.
• Access user identity information provided by IAP.
• Use cryptographic verification to prevent spoofing of user identity information.

What you'll learn

In this lab, you learn how to perform the following tasks:

• Write and deploy a simple Cloud Run service using Python.
• Enable and disable IAP to restrict access to your app.
• Get user identity information from IAP into your app.
• Verify information from IAP cryptographically to protect against spoofing.

Prerequisites

A basic knowledge of the Python programming language will enhance your learning experience.

This lab is focused on Cloud Run and IAP. Non-relevant concepts and code blocks are glossed over and are provided for you to simply copy and paste.

Introduction to Identity-Aware Proxy

Authenticating users of your web app is often necessary, and usually requires special programming in your app. For Google Cloud apps you can hand those responsibilities off to the Identity-Aware Proxy service. If you only need to restrict access to selected users there are no changes necessary to the application. Should the application need to know the user's identity (such as for keeping user preferences server-side) Identity-Aware Proxy can provide that with minimal application code.

What is Identity-Aware Proxy?

Identity-Aware Proxy (IAP) is a Google Cloud service that intercepts web requests sent to your application, authenticates the user making the request using the Google Identity Service, and only lets the requests through if they come from a user you authorize. In addition, it can modify the request headers to include information about the authenticated user.

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources are made available to you.

This hands-on lab lets you do the lab activities in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

Note: Use an Incognito (recommended) or private browser window to run this lab. This prevents conflicts between your personal account and the student account, which may cause extra charges incurred to your personal account.

• Time to complete the lab—remember, once you start, you cannot pause a lab.

Note: Use only the student account for this lab. If you use a different Google Cloud account, you may incur charges to that account.

How to start your lab and sign in to the Google Cloud console

1. Click the Start Lab button. If you need to pay for the lab, a dialog opens for you to select your payment method. On the right is the Lab setup and access panel with the following:

   • The Open Google Cloud console button
   • The temporary credentials (username and password) that you must use for this lab
   • Other information, if needed, to step through this lab

   Note that the lab timer is located near the top of the page, showing the remaining time.

2. Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).

   The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username below and paste it into the Sign in dialog.

   {{{user_0.username | "Username"}}}

   You can also find the Username in the Lab setup and access panel.

4. Click Next.

5. Copy the Password below and paste it into the Welcome dialog.

   {{{user_0.password | "Password"}}}

   You can also find the Password in the Lab setup and access panel.

6. Click Next.

   Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

7. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Google Cloud console opens in this tab.

Note: To access Google Cloud products and services, click the Navigation menu or type the service or product name in the Search field.

Activate Cloud Shell

Cloud Shell is a virtual machine that is loaded with development tools. It offers a persistent 5GB home directory and runs on the Google Cloud. Cloud Shell provides command-line access to your Google Cloud resources.

1. Click Activate Cloud Shell at the top of the Google Cloud console.

2. Click through the following windows:

   • Continue through the Cloud Shell information window.
   • Authorize Cloud Shell to use your credentials to make Google Cloud API calls.

When you are connected, you are already authenticated, and the project is set to your Project_ID, . The output contains a line that declares the Project_ID for this session:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.

3. (Optional) You can list the active account name with this command:

gcloud auth list

4. Click Authorize.

Output:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Optional) You can list the project ID with this command:

gcloud config list project

Output:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Note: For full documentation of gcloud, in Google Cloud, refer to the gcloud CLI overview guide.

Download the code

Click the command line area in the Cloud Shell so you can type commands.

Download the code from a public storage bucket and then change to the code folder:

gcloud storage cp gs://{{{project_0.project_id}}}-bucket/user-authentication-with-iap.zip . unzip user-authentication-with-iap.zip cd user-authentication-with-iap

This folder contains one subfolder for each step of this lab. You will change to the correct folder to perform each step.

Task 1. Deploy the application and protect it with IAP

This is a Cloud Run service written in Python that simply displays a "Hello, World" welcome page. We will deploy and test it, then restrict access to it using IAP.

Review the application code

• Change from the main project folder to the 1-HelloWorld subfolder that contains code for this step.

cd 1-HelloWorld

The application code is in the main.py file. It uses the Flask web framework to respond to web requests with the contents of a template. That template file is in templates/index.html, and for this step contains only plain HTML. A second template file contains a skeletal example privacy policy in templates/privacy.html.

There is one other file: requirements.txt lists all the non-default Python libraries the application uses.

You can list each file in the shell using the cat command, as in:

cat main.py

Or you can launch the Cloud Shell code editor by clicking the Open Editor (Pencil) icon in the Cloud Shell toolbar, and examine the code that way.

You do not need to change any files for this step.

Deploy to Cloud Run

1. Deploy the app to Cloud Run:

gcloud run deploy user-auth-lab --source . --allow-unauthenticated --region={{{ project_0.default_region | "REGION" }}}

2. If prompted to enable the API, enter Y for yes. If prompted to create an Artifact Registry repository to continue, enter Y for yes.

In a few minutes the deployment completes. You will see a message with the Service URL.

3. Open the displayed Service URL in a new browser tab to view the web page. Access is not yet restricted.

Click Check my progress to verify the objective. Deploy a Cloud Run service

Restrict access with IAP

1. In the Google Cloud console, on the Navigation menu (), click Security > Identity-Aware Proxy.

2. Click Enable API.

3. Click Go to Identity Aware Proxy.

4. Click the toggle button in the IAP column next to user-auth-lab to turn IAP on.

5. Click Turn On to confirm.

Test that IAP is turned on

1. Open a new browser tab and navigate to the URL for your app. A Sign in with Google page opens.

2. Sign in with the student account credentials you used to log into the console.

   A screen denying you access appears. You have successfully protected your app with IAP, but you have not yet authorized any user accounts.

3. Return to the Identity-Aware Proxy page in the console.

4. Select the checkbox next to the user-auth-lab Cloud Run service to open the details sidebar on the right.

5. Click Add Principal.

6. For New principals, enter your student email address.

7. For Select a role, select Cloud IAP > IAP-Secured Web App User.

8. Click Save. The message "Policy Updated" appears at the bottom of the page.

9. Navigate back to your app and reload the page. Since you are already logged in with an authorized account, you should now see your web app.

Note: It takes a minute for the role change to take effect. If the page still shows the "You don't have access" message, wait a minute and try refreshing the page.

Click Check my progress to verify the objective. Enable and add policy to IAP

If you still see the access denied page, clear the IAP login cookie:

1. Append /_gcp_iap/clear_login_cookie to the end of your service URL (e.g., https://user-auth-lab-[random-hash].run.app/_gcp_iap/clear_login_cookie) and open it.
2. When the new Sign in with Google page appears, click Use another account, and re-enter your student credentials.

Task 2. Access user identity information

Once an app is protected with IAP, it can use the identity information that IAP provides in the web request headers it passes through. In this step, the application will get the logged-in user's email address and a persistent unique user ID assigned by the Google Identity Service to that user. That data will be displayed to the user in the welcome page.

• In Cloud Shell, change to the folder for this step:

cd ~/user-authentication-with-iap/2-HelloUser

Deploy to Cloud Run

1. Deploy the app to Cloud Run:

gcloud run deploy user-auth-lab --source . --region={{{ project_0.default_region | "REGION" }}}

2. If prompted to continue, enter Y for yes.

In a few minutes the deployment should complete. While you are waiting you can examine the application files as described below.

Click Check my progress to verify the objective. Access User Identity Information

Examine the application files

1. View the main application file in the Cloud Shell using the cat command:

cat main.py

2. View the template file to see how it displays the user data:

cat templates/index.html

This folder contains the same set of files as seen in the previous app you deployed, 1-HelloWorld, but two of the files have been changed: main.py and templates/index.html. The program has been changed to retrieve the user information that IAP provides in request headers, and the template now displays that data.

There are two lines in main.py that get the IAP-provided identity data:

user_email = request.headers.get('X-Goog-Authenticated-User-Email') user_id = request.headers.get('X-Goog-Authenticated-User-ID')

The X-Goog-Authenticated-User- headers are provided by IAP, and the names are case-insensitive, so they could be given in all lower or all upper case if preferred. The render_template statement now includes those values so they can be displayed:

page = render_template('index.html', email=user_email, id=user_id)

The index.html template can display those values by enclosing the names in double curly braces:

Hello, {{ email }}! Your persistent ID is {{ id }}.

As you can see, the provided data is prefixed with accounts.google.com, showing where the information came from. Your application can remove everything up to and including the colon to get the raw values if desired.

Test the updated app

1. Retrieve the URL for your application:

gcloud run services describe user-auth-lab --region={{{ project_0.default_region | "REGION" }}} --format='value(status.url)'

2. Open that URL in a new browser tab.
3. Refresh the page if needed to see your email address and persistent ID displayed.

Turn off IAP

What happens to this app if IAP is disabled or bypassed? Turn off IAP to see.

1. In the cloud console window, on the Navigation menu, click Security > Identity-Aware Proxy.
2. Click the IAP toggle switch next to your Cloud Run service (e.g., user-auth-lab) to turn IAP off.
3. Click Allow public access.
4. Refresh the application web page. You should see the same page, but without any user information.

Since the application is now unprotected, a user could send a web request that appeared to have passed through IAP. For example, run the following curl command from the Cloud Shell (replace <your-url-here> with the URL of your app):

curl -X GET YOUR_URL -H "X-Goog-Authenticated-User-Email: totally fake email"

The web page will be displayed on the command line, showing the fake email:

<!doctype html> <html> <head> <title>IAP Hello User</title> </head> <body> <h1>Hello World</h1> <p> Hello, totally fake email! Your persistent ID is None. </p> <p> This is step 2 of the User Authentication with IAP</em> codelab. </p> </body> </html>

There is no way for the application to know that IAP has been disabled or bypassed. For cases where that is a potential risk, Cryptographic Verification shows a solution.

Task 3. Use cryptographic verification

If there is a risk of IAP being turned off or bypassed, your app can check to make sure the identity information it receives is valid. This uses a third web request header added by IAP, called X-Goog-IAP-JWT-Assertion. The value of the header is a cryptographically signed object that also contains the user identity data. Your application can verify the digital signature and use the data provided in this object to be certain that it was provided by IAP without alteration.

Digital signature verification requires several extra steps, such as retrieving the latest set of Google public keys. You can decide whether your application needs these extra steps based on the risk that someone might be able to turn off or bypass IAP, and the sensitivity of the application.

• In Cloud Shell, change to the folder for this step:

cd ~/user-authentication-with-iap/3-HelloVerifiedUser

Deploy to Cloud Run

1. Find the Signed Header JWT Audience Client ID for your IAP-secured Cloud Run service:

   • Go to the Identity-Aware Proxy page in the Cloud Console.

   • Locate the user-auth-lab in the list.

   • Note: You may need to scroll the resources table to the right (using the horizontal scrollbar at the bottom of the table) to reveal the Actions column on the far right.

   • Under Actions, click the three vertical dots button next to the resource and select Get JWT audience code.

   • From the modal that appears, copy and paste into a text editor the displayed Client ID string and select Ok.

2. Deploy the app to Cloud Run, setting the IAP_AUDIENCE environment variable with the Client ID value you copied:

gcloud run deploy user-auth-lab --source . --set-env-vars IAP_AUDIENCE="YOUR_CLIENT_ID" --region={{{ project_0.default_region | "REGION" }}}

3. If prompted to continue, enter Y for yes.

In a few minutes the deployment should complete. While you are waiting you can examine the application files as described below.

Click Check my progress to verify the objective. Use Cryptographic Verification

Examine the application files

1. View the new authentication helper file in the Cloud Shell using the cat command:

cat auth.py

2. View the main application file to see how the verified user method is integrated:

cat main.py

This folder contains the same set of files as seen in 2-HelloUser, with two files altered and one new file. The new file is auth.py, which provides a user() method to retrieve and verify the cryptographically signed identity information. The changed files are main.py and templates/index.html, which now use the results of that method. The unverified headers as found in the last deployment are also shown for comparison.

• The new functionality is primarily in the user() function:

def user(): assertion = request.headers.get('X-Goog-IAP-JWT-Assertion') if assertion is None: return None, None info = jwt.decode( assertion, keys(), algorithms=['ES256'], audience=audience() ) return info['email'], info['sub']

The assertion is the cryptographically signed data provided in the specified request header. The code uses a library to validate and decode that data. Validation uses the public keys that Google provides for checking data it signs, and knowing the audience that the data was prepared for (essentially, the Google Cloud project that is being protected). Helper functions keys() and audience() gather and return those values.

The signed object has two pieces of data we need: the verified email address, and the unique ID value (provided in the sub, for subscriber, standard field).

This completes Step 3.

Test the cryptographic verification

When the deployment is ready, you can get the URL for your application with:

gcloud run services describe user-auth-lab --region={{{ project_0.default_region | "REGION" }}} --format='value(status.url)'

1. Open that URL in a new browser tab.
2. Recall that you previously disabled IAP, so the application provides no IAP data. Verify that you see a page showing None for email and ID.
3. Go to the Identity-Aware Proxy page in the console.
4. Click the IAP toggle switch next to your Cloud Run service to turn IAP on again.
5. Click Turn On to confirm.
6. In Cloud Shell, run the following command to grant the IAP service agent permission to invoke your Cloud Run service:

gcloud run services add-iam-policy-binding user-auth-lab \ --member="serviceAccount:service-$(gcloud projects describe {{{project_0.project_id}}} --format='value(projectNumber)')@gcp-sa-iap.iam.gserviceaccount.com" \ --role="roles/run.invoker" \ --region={{{ project_0.default_region | "REGION" }}}

7. Refresh the application page. Verify that the cryptographically signed email and user ID are now correctly displayed and verified!

Notice that the email address provided by the verified method does not have the accounts.google.com: prefix.

If IAP is turned off or bypassed, the verified data would either be missing, or invalid, since it cannot have a valid signature unless it was created by the holder of Google's private keys.

Congratulations!

You deployed a Cloud Run service. First, you restricted access to the application to only users you chose. Then you retrieved and displayed the identity of users that IAP allowed access to your application, and saw how that information might be spoofed if IAP were disabled or bypassed. Lastly, you verified cryptographically signed assertions of the user's identity, which cannot be spoofed.

Next steps / Learn more

• Get more detail about Cloud Identity-Aware Proxy.
• Check out other Google Security products.

Google Cloud training and certification

...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.

Manual Last Updated May 28, 2026

Lab Last Tested May 28, 2026

Copyright 2026 Google LLC. All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.