クエリ パラメータとヘッダーの使用

このページでは、Identity-Aware Proxy(IAP)クエリ パラメータとヘッダーを使用して、アプリケーションの UI の改善やトラブルシューティングの手段を提供する方法について説明します。

クエリ パラメータ

URL クエリ文字列にパラメータ gcp-iap-mode を設定すると、さまざまなアクションを実行できます。これらのクエリ パラメータは、ルート URL だけでなく、任意のパスに含めることができます。

ユーザー ID の引き渡し

次のパラメータ値を渡すと、ユーザーの ID を含む JSON 辞書が返されます。

YOUR_APP_URL?gcp-iap-mode=IDENTITY

これは、アプリにアクセスできない場合でも、ログインしている任意の Google アカウントで利用できます。URL に直接移動することも、URL を参照してリクエストを送信することもできます。この URL から返される値の例を次に示します。

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

この値は、ユーザー名を表示するなどの方法でアプリをカスタマイズする場合に役立ちます。また、別のページに ID を渡す場合や、使用状況データをログに取り込む場合にも役立ちます。

ユーザー ログインのクリア

次のパラメータ値は、IAP のログイン Cookie をクリアします。

YOUR_APP_URL?gcp-iap-mode=CLEAR_LOGIN_COOKIE

デフォルトでは、このパラメータを渡すとブラウザによって 403 ページが表示され、間違った場所にログインしているユーザーを手引きできるようになります。行き詰まったユーザーにこの URL を提供したり、この URL を使用してアプリケーション内でプロファイルの切り替えを有効にしたりすることもできます。

JWT 検証のテスト

IAP は、無効な JWT をテスト用ウェブページに渡すことで、JWT 検証ロジックをテストするのに役立ちます。

たとえば、IAP を使用して、クエリ パラメータ gcp-iap-mode=SECURE_TOKEN_TESTiap-secure-token-test-type=SIGNATURE を含むリクエストに対して無効な署名を含む 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 がアクセスを拒否したとき(403)または認証をリクエストしたとき(302 または 401)に HTTP レスポンスを生成する場合、X-Goog-IAP-Generated-Response HTTP レスポンス ヘッダーが追加されます。このヘッダーの存在を検出することで、次のアクションが可能になります。

  • IAP によって生成されたエラー メッセージと、アプリケーションによって生成されたエラー メッセージを区別する。

  • IAP 認証情報をリクエストに追加する必要があるタイミングを検出する。