This page describes how to use Identity-Aware Proxy (IAP) query parameters and headers to enhance your application UI or provide troubleshooting options.
Query Parameters
Different actions can be performed by setting the parameter gcp-iap-mode in the URL query string.
These query parameters can be included with any path, not just the root URL.
Passing user identity
Passing the following parameter value returns a JSON dictionary with the user's identity:
YOUR_APP_URL?gcp-iap-mode=IDENTITY
This is available from any signed-in Google account, even if the account doesn't have access to the app. You can navigate to the URL directly or you can reference it to make requests to the URL. Following is an example value returned by the URL:
{"email":"accounts.google.com:USER_EMAIL","sub":"accounts.google.com:118133858486581853996"}
You might find this value useful to personalize your app, such as by displaying the user's name, to pass identity to another page, or capture usage data in logs.
Clearing user login
The following parameter value clears the IAP login cookie:
YOUR_APP_URL?gcp-iap-mode=CLEAR_LOGIN_COOKIE
By default, passing this parameter navigates the browser to the 403 page to help users who might be signed in to the wrong place. You can also provide the URL to a user who gets stuck, or use it to enable profile switching in your application.
Testing JWT verification
IAP helps you test your JWT verification logic by passing invalid JWTs to testing webpages.
For example, IAP passes a JWT with an invalid signature
for any request that contains the query parameters
gcp-iap-mode=SECURE_TOKEN_TEST and iap-secure-token-test-type=SIGNATURE.
Your verification logic should catch the invalid signature.
You can test your verification logic against any of the following scenarios by appending the appropriate parameters to a request.
| Parameters | Test case |
|---|---|
| ?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=NOT_SET | A valid JWT. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=FUTURE_ISSUE | Issue date is set in the future. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=PAST_EXPIRATION | Expiration date is set in the past. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=ISSUER | Incorrect issuer. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=AUDIENCE | Incorrect audience. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=SIGNATURE | Signed using an incorrect signer. |
Special headers
Detecting responses from IAP
When IAP generates an HTTP response, such as when it denies
access (403) or requests authentication (302 or 401), it adds the
X-Goog-IAP-Generated-Response HTTP response header. By detecting the presence
of this header, you can perform actions like:
Distinguish between error messages generated by IAP and error messages generated by your application.
Detect when IAP credentials need to be added to a request.