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:

<br />

`{"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`

Passing this parameter clears all the IAP-issued cookies
for your app and navigates the browser to `YOUR_APP_URL`. If your browser has a
valid session with the identity provider (IdP) of your app, a silent sign-in
might happen when there is only one account in use with the IdP. If there are
multiple accounts in use, an account selection page opens to allow profile switching.

### 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=<var translate="no">NOT_SET</var> | A valid JWT. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST\&iap-secure-token-test-type=<var translate="no">FUTURE_ISSUE</var> | Issue date is set in the future. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST\&iap-secure-token-test-type=<var translate="no">PAST_EXPIRATION</var> | Expiration date is set in the past. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST\&iap-secure-token-test-type=<var translate="no">ISSUER</var> | Incorrect issuer. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST\&iap-secure-token-test-type=<var translate="no">AUDIENCE</var> | Incorrect audience. |
| ?gcp-iap-mode=SECURE_TOKEN_TEST\&iap-secure-token-test-type=<var translate="no">SIGNATURE</var> | 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.