Objetivos
Exigir que os usuários do seu aplicativo do App Engine se autentiquem usando o IAP.
Acessar as identidades dos usuários no aplicativo para exibir o endereço de e-mail autenticado do usuário atual.
Custos
Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.
Antes de começar
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Experiência
Neste tutorial, o IAP é usado para autenticar usuários. Essa é apenas uma das várias abordagens possíveis. Para saber mais sobre os vários métodos de autenticação de usuários, consulte a seção Conceitos de autenticação.
O aplicativo Hello user-email-address
Neste tutorial, é usado um app Hello World do App Engine mínimo com um recurso atípico: em vez de "Hello world", ele exibe "Hello user-email-address
", em que user-email-address
é o endereço de e-mail do usuário autenticado.
Essa funcionalidade é possível por meio da análise das informações autenticadas que o IAP adiciona a cada solicitação da Web que passa no aplicativo. Há três novos cabeçalhos de solicitação adicionados a cada solicitação da Web que chega ao app. Os dois primeiros cabeçalhos são strings de texto simples que podem ser usadas para identificar o usuário. O terceiro cabeçalho é um objeto assinado criptograficamente com as mesmas informações.
X-Goog-Authenticated-User-Email
: o endereço de e-mail do usuário o identifica. Não armazene informações pessoais se o aplicativo puder evitar isso. Esse aplicativo não armazena dados. Ele apenas os retorna ao usuário.X-Goog-Authenticated-User-Id
: esse ID de usuário atribuído pelo Google não mostra informações pessoais, mas permite que um aplicativo saiba que o usuário conectado é o mesmo que se conectou anteriormente.X-Goog-Iap-Jwt-Assertion
: é possível configurar aplicativos do Google Cloud para aceitar solicitações da web de outros apps na nuvem ignorando o IAP, além de solicitações da web via Internet. Se um aplicativo for configurado dessa forma, é possível que essas solicitações tenham cabeçalhos forjados. Em vez de usar um dos cabeçalhos de texto simples mencionados anteriormente, é possível usar e verificar esse cabeçalho assinado por criptografia para confirmar se as informações foram fornecidas pelo Google. O endereço de e-mail do usuário e um ID de usuário permanente estão disponíveis como parte do cabeçalho assinado.
Se você tiver certeza de que o aplicativo está configurado para que apenas solicitações da Web via Internet possam acessá-lo e que não seja possível desativar o serviço do IAP, apenas uma linha de código será necessária para recuperar um ID de usuário único:
$userId = getallheaders()['X-Goog-Authenticated-User-Id'] ?? null;
No entanto, um aplicativo resiliente está preparado para erros, como uma configuração inesperada ou problemas ambientais. Assim, recomendamos criar uma função que use e verifique o cabeçalho criptograficamente assinado. A assinatura do cabeçalho não pode ser forjada. Quando verificada, ela pode ser usada para retornar a identificação.
Criar o código-fonte
Use um editor de texto para criar um arquivo chamado
index.php
e cole o código a seguir nele:Esse arquivo
index.php
é explicado em detalhes na seção Como entender o código mais adiante neste tutorial.Crie outro arquivo chamado
composer.json
e cole o seguinte nele:O arquivo
composer.json
lista todas as bibliotecas PHP que o aplicativo precisa que o App Engine carregue para ele:firebase/php-jwt
fornece a função de verificação e decodificação do JWT.guzzle/http
é um cliente HTTP para recuperar dados de sites.
Crie um arquivo chamado
app.yaml
e digite o seguinte texto:O arquivo
app.yaml
informa ao App Engine o ambiente de linguagem que seu código requer.
Noções básicas sobre o código
Veja nesta seção como funciona o código em index.php
. Se você quiser apenas executar o app, avance para a seção Implantar o aplicativo.
O código a seguir está no arquivo index.php
. Quando uma solicitação HTTP GET
para a página inicial é recebida pelo aplicativo, a instrução switch case de /
é invocada:
A instrução de troca acessa o valor do cabeçalho de declaração JWT que o IAP adicionou da solicitação recebida e chama uma função para validar esse valor assinado criptograficamente. Em seguida, o primeiro valor retornado (e-mail) é usado em uma página da Web mínima que ela cria e retorna.
A função validate_assertion
usa a biblioteca google/auth
para verificar se a declaração está assinada corretamente e extrair as informações de payload da declaração. Se a declaração não puder ser decodificada, a função gerará uma exceção. Se for bem-sucedida, a função retornará o endereço de e-mail do usuário autenticado e um código exclusivo permanente para o usuário.
Para validar uma declaração do JWT, é preciso conhecer os certificados de chave pública da entidade que assinou a declaração (neste caso, o Google) e o público a que ela se destina. No caso de um aplicativo do App Engine, o público é uma string com informações de identificação de um projeto do Google Cloud. Essa função recebe os certificados e a string de público das funções que a precedem.
É possível procurar o ID numérico e o nome do projeto do Google Cloud e colocá-los no código-fonte, mas a função audience
faz isso consultando o serviço de metadados padrão disponibilizado para cada aplicativo do App Engine.
O serviço de metadados do App Engine, assim como serviços de metadados similares para outros serviços de computação do Google Cloud, tem a aparência de um site e recebe consultas padrão da web. No entanto, ele não é um site externo, mas um recurso interno que retorna informações solicitadas sobre o aplicativo em execução. Por isso, é seguro usar http
em vez de solicitações https
.
O serviço é usado para receber os identificadores atuais do Google Cloud necessários para definir o público da declaração do JWT.
Como implantar o app
Agora é possível implantar o aplicativo e permitir que o IAP solicite a autenticação dos usuários para que eles possam acessar o aplicativo.
Na janela do terminal, acesse o diretório que contém o arquivo
app.yaml
e implante o aplicativo no App Engine:gcloud app deploy
Quando solicitado, selecione uma região próxima.
Quando receber uma mensagem perguntando se quer continuar com a operação de implantação, insira
Y
.Em alguns minutos, seu app está ativo na Internet.
Ver o aplicativo:
gcloud app browse
Na saída, copie
web-site-url
, o endereço da Web do aplicativo.Em uma janela do navegador, cole
web-site-url
para abrir o aplicativo.Como você ainda não está usando o IAP, nenhum e-mail será exibido. Portanto, nenhuma informação de usuário será enviada para o aplicativo.
Ativar o IAP
Agora que existe uma instância do App Engine, é possível protegê-la com o IAP:
No console do Google Cloud, acesse a página Identity-Aware Proxy.
Como essa é a primeira vez que você ativa uma opção de autenticação para o projeto, você verá uma mensagem para configurar a tela de consentimento do OAuth antes de usar o IAP.
Clique em Configurar tela de consentimento.
Na guia Tela de consentimento OAuth da página Credenciais, preencha os seguintes campos:
Se a sua conta estiver em uma organização no Google Workspace, selecione Externo e clique em Criar. A princípio, o app só estará disponível para os usuários que você permitir explicitamente.
No campo Nome do aplicativo, digite
IAP Example
.No campo E-mail para suporte, digite seu endereço de e-mail.
No campo Domínio autorizado, digite a parte do nome do host do URL do aplicativo, por exemplo,
iap-example-999999.uc.r.appspot.com
. Pressione a teclaEnter
depois de inserir o nome do host no campo.No campo Link da página inicial do aplicativo, insira o URL do seu aplicativo. Por exemplo,
https://iap-example-999999.uc.r.appspot.com/
.No campo Linha da política de privacidade do aplicativo, use o mesmo URL do link da página inicial para fins de teste.
Clique em Save. Quando for solicitado que você crie credenciais, feche a janela.
No console do Google Cloud, acesse a página Identity-Aware Proxy.
Para atualizar a página, clique em Atualizar refresh. A página exibe uma lista de recursos que são possíveis proteger.
Na coluna IAP, clique para ativar o IAP para o aplicativo.
No seu navegador, acesse
web-site-url
novamente.Em vez da página da Web, há uma tela de login para autenticação. Ao fazer login, seu acesso será negado, porque o IAP não tem uma lista de usuários para permitir o acesso ao aplicativo.
Adicionar usuários autorizados ao aplicativo
No console do Google Cloud, acesse a página "Identity-Aware Proxy".
Marque a caixa de seleção correspondente ao aplicativo do App Engine e clique em Adicionar principal.
Insira
allAuthenticatedUsers
e selecione o papel Cloud IAP/Usuário do app da Web protegido pelo IAP.Clique em Save.
Agora qualquer usuário que o Google possa autenticar poderá acessar o aplicativo. Se quiser, restrinja o acesso adicionando apenas uma ou mais pessoas ou grupos como principais:
Qualquer endereço de e-mail do Gmail ou do Google Workspace
Um endereço de e-mail de Grupo do Google
Um nome de domínio do Google Workspace
Acessar o aplicativo
No seu navegador, acesse
web-site-url
.Para atualizar a página, clique em Atualizar refresh.
Na tela de login, faça login com suas credenciais do Google.
Será exibida uma página "Hello
user-email-address
" com seu endereço de e-mail.Se você ainda vir a mesma página de antes, talvez o navegador não esteja atualizando totalmente as novas solicitações, agora que você ativou o IAP. Feche todas as janelas do navegador, volte a abri-las e tente novamente.
Conceitos de autenticação
Existem várias formas de um aplicativo autenticar seus usuários e restringir o acesso somente a usuários autorizados. Veja nas seções a seguir os métodos de autenticação comuns, em nível de esforço decrescente para o aplicativo.
Opção | Vantagens | Desvantagens |
---|---|---|
Autenticação do aplicativo |
|
|
OAuth2 |
|
|
IAP |
|
|
Autenticação gerenciada pelo aplicativo
Com esse método, o aplicativo gerencia cada aspecto da autenticação de usuários por conta própria. O aplicativo precisa manter o próprio banco de dados de credenciais e gerenciar sessões de usuários, além de fornecer funções para gerenciar contas e senhas, verificar credenciais e emitir, verificar e atualizar sessões de usuário com cada login autenticado. O diagrama a seguir ilustra o método de autenticação gerenciado pelo aplicativo.
Conforme mostrado no diagrama, depois que o usuário faz login, o aplicativo cria e mantém informações sobre a sessão do usuário. Quando o usuário faz uma solicitação ao aplicativo, nela, devem estar incluídas informações da sessão que o aplicativo é responsável por verificar.
A principal vantagem dessa abordagem é que ela é autossuficiente e está sob controle do aplicativo. O app não precisa estar disponível na Internet. A principal desvantagem é que agora o aplicativo é responsável por fornecer todos os recursos de gerenciamento de contas e por proteger todos os dados confidenciais das credenciais.
Autenticação externa com OAuth2
Uma boa alternativa para gerenciar tudo no aplicativo é usar um serviço de identidade externo, como o Google, que lida com todas as informações e funcionalidades da conta do usuário e é responsável por proteger credenciais confidenciais. Quando um usuário tenta fazer login no aplicativo, a solicitação é redirecionada ao serviço de identidade, que o autentica e redireciona a solicitação de volta ao aplicativo com as informações de autenticação necessárias. Para mais informações, consulte Usar o OAuth 2.0 para aplicativos de servidor da Web.
O diagrama a seguir ilustra a autenticação externa com o método OAuth2.
O fluxo no diagrama começa quando o usuário envia uma solicitação para acessar o aplicativo. Em vez de responder diretamente, o aplicativo redireciona o navegador do usuário para a plataforma de identidade do Google, que exibe uma página de login no Google. Após o login, o navegador do usuário é direcionado de volta para o aplicativo. Essa solicitação inclui informações que o aplicativo pode usar para procurar informações sobre o usuário agora autenticado, e o aplicativo agora responde ao usuário.
Esse método tem muitas vantagens para o aplicativo. Ele delega todos os recursos e riscos de gerenciamento da conta ao serviço externo, o que pode melhorar o login e a segurança da conta sem precisar alterar o app. No entanto, como mostrado no diagrama anterior, o aplicativo precisa ter acesso à Internet para usar esse método. Além disso, o app é responsável por gerenciar as sessões depois que o usuário é autenticado.
Identity-Aware Proxy
A terceira abordagem discutida neste tutorial é usar o IAP para gerenciar todas as autenticações e as sessões com qualquer alteração no aplicativo. O IAP intercepta todas as solicitações da Web para o app, bloqueia todas que não foram autenticadas e transmite outros dados de identidade de usuário adicionados a cada solicitação.
O gerenciamento da solicitação é mostrado no diagrama a seguir.
Solicitações de usuários são interceptadas pelo IAP, que bloqueia solicitações não autenticadas. As solicitações autenticadas são transmitidas ao aplicativo, desde que o usuário autenticado esteja na lista de usuários permitidos. As solicitações transmitidas por meio do IAP têm cabeçalhos adicionados que identificam o usuário que fez a solicitação.
O aplicativo não precisa mais lidar com informações de conta ou sessão do usuário. Qualquer operação que precise de um identificador exclusivo do usuário pode consegui-lo diretamente de cada solicitação da Web recebida. No entanto, esse método só pode ser usado para serviços de computação compatíveis com o IAP, como o App Engine e os balanceadores de carga. Não é possível usar o IAP em uma máquina de desenvolvimento local.
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.