使用查询参数和标头

本页面介绍如何使用 Identity-Aware Proxy (IAP) 查询参数和标头来增强应用界面或提供问题排查选项。

查询参数

您可以通过在网址查询字符串中设置 gcp-iap-mode 参数来执行不同的操作。这些查询参数可以包含在任何路径中,而不仅仅是根网址。

传递用户身份

传递以下参数值会返回包含用户身份的 JSON 字典:

YOUR_APP_URL?gcp-iap-mode=IDENTITY

任何已登录的 Google 帐号均可提供此信息,即使该帐号无权访问应用。您可以直接导航到该网址,也可以引用该网址来向它发出请求。以下是该网址的返回值示例:

{"email":"accounts.google.com:USER_EMAIL","sub":"accounts.google.com:118133858486581853996"}

您可能会发现,这个值对于个性化您的应用(例如通过显示用户的姓名)、将身份传递到其他页面或捕获日志中的使用情况数据非常有用。

清除用户登录

以下参数值会清除 IAP 登录 Cookie:

YOUR_APP_URL?gcp-iap-mode=CLEAR_LOGIN_COOKIE

默认情况下,传递此参数会将浏览器导航到 403 页面,以帮助可能登录到错误位置的用户。您也可以向无法打开链接的用户提供该网址,或者使用该网址来切换应用中的个人资料。

测试 JWT 验证

IAP 通过将无效的 JWT 传递给测试网页来帮助您测试 JWT 验证逻辑。

例如,对于包含查询参数 gcp-iap-mode=SECURE_TOKEN_TESTiap-secure-token-test-type=SIGNATURE 的任何请求,IAP 会传递包含无效签名的 JWT。您的验证逻辑应该可以捕获无效签名。

您可以将相应的参数附加到请求,从而针对以下任一场景测试验证逻辑。

参数 测试用例
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=NOT_SET 有效的 JWT。
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=FUTURE_ISSUE 颁发日期设在未来。
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=PAST_EXPIRATION 到期日期设在过去。
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=ISSUER 颁发者错误。
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=AUDIENCE 受众错误。
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=SIGNATURE 使用了不正确的签名者签名。

特殊标头

检测 IAP 的响应

当 IAP 生成 HTTP 响应时,例如拒绝访问 (403) 或请求身份验证(302 或 401),则会添加 X-Goog-IAP-Generated-Response HTTP 响应标头。通过检测此标头是否存在,您可以执行如下操作:

  • 区分 IAP 生成的错误消息和应用生成的错误消息。

  • 检测何时需要将 IAP 凭据添加到请求中。