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

このページでは、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

このパラメータを渡すと、IAP で発行されたアプリの Cookie がすべて消去され、ブラウザで YOUR_APP_URL に移動します。ブラウザでアプリの ID プロバイダ（IdP）との有効なセッションがある場合、IdP で使用されているアカウントが 1 つのみであれば、ログインがサイレントモードで行われることがあります。使用中のアカウントが複数ある場合は、アカウントの選択ページが開き、プロファイルの切り替えを行うことができます。

JWT 検証のテスト

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

たとえば、IAP を使用して、クエリパラメータ gcp-iap-mode=SECURE_TOKEN_TEST と iap-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 認証情報をリクエストに追加する必要があるタイミングを検出する。

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