Como usar parâmetros e cabeçalhos de consulta

Nesta página, você aprenderá como usar parâmetros e cabeçalhos de consulta do Identity-Aware Proxy (IAP, na sigla em inglês) para melhorar a IU do aplicativo ou para oferecer alternativas para solucionar problemas.

Query Parameters

Ações diferentes podem ser executadas configurando o parâmetro gcp-iap-mode na string de consulta de URL. Esses parâmetros de consulta podem ser incluídos com qualquer caminho, não só com o URL raiz.

Passar a identidade do usuário

Transmitir o seguinte valor de parâmetro retorna um dicionário JSON com a identidade do usuário:

YOUR_APP_URL?gcp-iap-mode=IDENTITY

Isso está disponível em qualquer conta do Google conectada, mesmo que a conta não tenha acesso ao app. É possível navegar diretamente ao URL ou referenciá-lo para fazer solicitações ao URL. Veja a seguir um exemplo de valor retornado pelo URL:

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

Esse valor pode ser útil para personalizar seu app, como exibir o nome do usuário, transmitir a identidade para outra página ou coletar dados de uso em registros.

Limpar o login do usuário

O valor de parâmetro a seguir limpa o cookie de login do IAP:

YOUR_APP_URL?gcp-iap-mode=CLEAR_LOGIN_COOKIE

Por padrão, a transmissão desse parâmetro navega pelo navegador até a página 403 para ajudar os usuários que possam estar conectados ao lugar errado. Outra opção é fornecer o URL ao usuário que ficar preso ou usá-lo para ativar a troca de perfil no seu aplicativo.

Como testar a verificação do JWT

O IAP ajuda você a testar a lógica de verificação do JWT ao transmitir JWTs inválidos para páginas da Web de teste.

Por exemplo, o IAP transmite um JWT com uma assinatura inválida para qualquer solicitação que contenha os parâmetros de consulta gcp-iap-mode=SECURE_TOKEN_TEST e iap-secure-token-test-type=SIGNATURE. Sua lógica de verificação capturará a assinatura inválida.

É possível testar sua lógica de verificação em qualquer um dos cenários a seguir. Basta anexar os parâmetros apropriados a uma solicitação.

Parâmetros Caso de teste
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=NOT_SET Um JWT válido.
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=FUTURE_ISSUE A data de emissão está definida no futuro.
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=PAST_EXPIRATION A data de expiração está definida no passado.
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=ISSUER Emissor incorreto.
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=AUDIENCE Público-alvo incorreto.
?gcp-iap-mode=SECURE_TOKEN_TEST&iap-secure-token-test-type=SIGNATURE Assinado usando um assinante incorreto.

Cabeçalhos especiais

Como detectar as respostas do IAP

Quando o IAP gera uma resposta HTTP, como ao negar o acesso (403) ou solicitar a autenticação (302 ou 401), ele inclui o cabeçalho de resposta HTTP X-Goog-IAP-Generated-Response. Ao detectar a presença desse cabeçalho, é possível executar ações como as seguintes:

  • Diferenciar as mensagens de erro geradas pelo IAP das mensagens de erro geradas por seu aplicativo.

  • Detectar quando é necessário incluir as credenciais do IAP em uma solicitação.