Como autenticar usuários com o PHP

---

Apps em execução nas plataformas gerenciadas do Google Cloud, como o App Engine, podem evitar o gerenciamento da autenticação de usuários e de sessões usando o Identity-Aware Proxy (IAP) para controlar o acesso a eles. O IAP não só controla o acesso ao aplicativo como também fornece informações sobre os usuários autenticados, incluindo o endereço de e-mail e um identificador permanente para o aplicativo na forma de novos cabeçalhos HTTP.

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:

• App Engine
• IAP

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

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

1. 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.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Install the Google Cloud CLI.

4. To initialize the gcloud CLI, run the following command:

   gcloud init

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Install the Google Cloud CLI.

7. 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;

Observação :a função getallheaders está disponível apenas para NGINX no PHP 7.3 ou posterior.

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

1. Use um editor de texto para criar um arquivo chamado index.php e cole o código a seguir nele:

   authenticate-users/index.php

   Ver no GitHub

   require_once __DIR__ . '/vendor/autoload.php';
   
   /**
    * Checks that the JWT assertion is valid (properly signed, for the
    * correct audience) and if so, returns strings for the requesting user's
    * email and a persistent user ID. If not valid, returns null for each field.
    *
    * @param string $idToken The JWT string to assert.
    * @param string $audience The audience of the JWT.
    *
    * @return string[] array containing [$email, $id]
    * @throws Exception on failed validation
    */
   function validate_assertion(string $idToken, string $audience) : array
   {
       $auth = new Google\Auth\AccessToken();
       $info = $auth->verify($idToken, [
         'certsLocation' => Google\Auth\AccessToken::IAP_CERT_URL,
         'throwException' => true,
       ]);
   
       if ($audience != $info['aud'] ?? '') {
           throw new Exception(sprintf(
               'Audience %s did not match expected %s', $info['aud'], $audience
           ));
       }
   
       return [$info['email'], $info['sub']];
   }
   
   /**
    * This is an example of a front controller for a flat file PHP site. Using a
    * static list provides security against URL injection by default.
    */
   switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
       case '/':
           if (!Google\Auth\Credentials\GCECredentials::onGce()) {
               throw new Exception('You must deploy to appengine to run this sample');
           }
           $metadata = new Google\Cloud\Core\Compute\Metadata();
           $audience = sprintf(
               '/projects/%s/apps/%s',
               $metadata->getNumericProjectId(),
               $metadata->getProjectId()
           );
           $idToken = getallheaders()['X-Goog-Iap-Jwt-Assertion'] ?? '';
           try {
               list($email, $id) = validate_assertion($idToken, $audience);
               printf("<h1>Hello %s</h1>", $email);
           } catch (Exception $e) {
               printf('Failed to validate assertion: %s', $e->getMessage());
           }
           break;
       case '': break; // Nothing to do, we're running our tests
       default:
           http_response_code(404);
           exit('Not Found');
   }

   Esse arquivo index.php é explicado em detalhes na seção Como entender o código mais adiante neste tutorial.

2. Crie outro arquivo chamado composer.json e cole o seguinte nele:

   authenticate-users/composer.json

   Ver no GitHub

   {
     "require": {
       "php": ">=7.1",
       "google/auth": "^1.9",
       "google/cloud-core": "^1.32",
       "kelvinmo/simplejwt": "^0.4.0"
     }
   }
   

   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.

3. Crie um arquivo chamado app.yaml e digite o seguinte texto:

   authenticate-users/app.yaml

   Ver no GitHub

   runtime: php73
   

   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:

authenticate-users/index.php

Ver no GitHub

/**
 * This is an example of a front controller for a flat file PHP site. Using a
 * static list provides security against URL injection by default.
 */
switch (@parse_url($_SERVER['REQUEST_URI'])['path']) {
    case '/':
        if (!Google\Auth\Credentials\GCECredentials::onGce()) {
            throw new Exception('You must deploy to appengine to run this sample');
        }
        $metadata = new Google\Cloud\Core\Compute\Metadata();
        $audience = sprintf(
            '/projects/%s/apps/%s',
            $metadata->getNumericProjectId(),
            $metadata->getProjectId()
        );
        $idToken = getallheaders()['X-Goog-Iap-Jwt-Assertion'] ?? '';
        try {
            list($email, $id) = validate_assertion($idToken, $audience);
            printf("<h1>Hello %s</h1>", $email);
        } catch (Exception $e) {
            printf('Failed to validate assertion: %s', $e->getMessage());
        }
        break;
    case '': break; // Nothing to do, we're running our tests
    default:
        http_response_code(404);
        exit('Not Found');
}

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.

authenticate-users/index.php

Ver no GitHub

/**
 * Checks that the JWT assertion is valid (properly signed, for the
 * correct audience) and if so, returns strings for the requesting user's
 * email and a persistent user ID. If not valid, returns null for each field.
 *
 * @param string $idToken The JWT string to assert.
 * @param string $audience The audience of the JWT.
 *
 * @return string[] array containing [$email, $id]
 * @throws Exception on failed validation
 */
function validate_assertion(string $idToken, string $audience) : array
{
    $auth = new Google\Auth\AccessToken();
    $info = $auth->verify($idToken, [
      'certsLocation' => Google\Auth\AccessToken::IAP_CERT_URL,
      'throwException' => true,
    ]);

    if ($audience != $info['aud'] ?? '') {
        throw new Exception(sprintf(
            'Audience %s did not match expected %s', $info['aud'], $audience
        ));
    }

    return [$info['email'], $info['sub']];
}

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.

authenticate-users/index.php

Ver no GitHub

$metadata = new Google\Cloud\Core\Compute\Metadata();
$audience = sprintf(
    '/projects/%s/apps/%s',
    $metadata->getNumericProjectId(),
    $metadata->getProjectId()
);

É 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.

1. 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
   

2. Quando solicitado, selecione uma região próxima.

3. 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.

4. Ver o aplicativo:

   gcloud app browse
   

   Na saída, copie web-site-url, o endereço da Web do aplicativo.

5. 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:

1. No console do Google Cloud, acesse a página Identity-Aware Proxy.

   Acessar a página do Identity-Aware Proxy

2. 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.

3. 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 tecla Enter 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.

4. Clique em Save. Quando for solicitado que você crie credenciais, feche a janela.

5. No console do Google Cloud, acesse a página Identity-Aware Proxy.

   Acessar a página do Identity-Aware Proxy

6. Para atualizar a página, clique em Atualizar . A página exibe uma lista de recursos que são possíveis proteger.

7. Na coluna IAP, clique para ativar o IAP para o aplicativo.

8. No seu navegador, acesse web-site-url novamente.

9. 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

1. No console do Google Cloud, acesse a página "Identity-Aware Proxy".

   Acessar a página do Identity-Aware Proxy

2. Marque a caixa de seleção correspondente ao aplicativo do App Engine e clique em Adicionar principal.

3. Insira allAuthenticatedUsers e selecione o papel Cloud IAP/Usuário do app da Web protegido pelo IAP.

4. 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

1. No seu navegador, acesse web-site-url.

2. Para atualizar a página, clique em Atualizar .

3. 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	O app pode ser executado em qualquer plataforma, com ou sem conexão de Internet Os usuários não precisam usar nenhum outro serviço para gerenciar a autenticação	O app precisa gerenciar as credenciais do usuário com segurança e proteger contra divulgação O aplicativo precisa manter os dados da sessão dos usuários conectados O app precisa fornecer registro de usuários, alterações de senha e recuperação de senha
OAuth2	O app pode ser executado em qualquer plataforma conectada à Internet, incluindo uma estação de trabalho do desenvolvedor O app não precisa de registro de usuários, alterações de senha ou funções de recuperação de senha. O risco de divulgação de informações do usuário é delegado a outro serviço Novas medidas de segurança de login são processadas fora do app	Os usuários precisam se registrar no serviço de identidade O aplicativo precisa manter os dados da sessão dos usuários conectados
IAP	O app não precisa de códigos para gerenciar usuários, a autenticação ou o estado da sessão. O app não tem credenciais de usuário que possam ser violadas	O aplicativo só pode ser executado em plataformas compatíveis com o serviço. Especificamente, determinados serviços do Google Cloud compatíveis com o IAP, como o App Engine.

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.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

A seguir

• Saiba mais sobre o IAP.
• Gerenciar sessões com o Firestore
• Adicionar processamento de segundo plano com Pub/Sub e Cloud Run
• Implantar um app no Compute Engine
• Implantar um app no Google Kubernetes Engine