API Users para serviços agrupados legados

Com a API Users um aplicativo pode:

• detectar se o usuário atual fez login;
• redirecionar o usuário para a página de login correta;
• solicitar que o usuário do aplicativo crie uma nova conta do Google se ainda não tiver uma.

Essa API é compatível com os ambientes de execução de primeira geração e pode ser usada ao fazer upgrade para os ambientes de execução de segunda geração correspondentes. Se você estiver atualizando para o ambiente de execução do PHP 7 ou 8 no App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos no pacote.

Quando um usuário está conectado, o aplicativo pode acessar o endereço de e-mail dele. O app também pode detectar se o usuário atual é um administrador, também chamado de usuário administrador, facilitando a implementação de áreas exclusivas para administradores do aplicativo.

Observação: um usuário administrador é qualquer usuário que tenha papel de Leitor, Editor, Proprietário ou Administrador do APP Engine. Para mais informações sobre como definir funções do usuário, consulte Funções que concedem acesso ao App Engine.

Autenticação do usuário em PHP 5

No exemplo a seguir, um usuário que se conectou ao app recebe uma mensagem personalizada de saudação e um link para sair. Se o usuário não estiver conectado, o aplicativo oferece um link para a página de login das Contas do Google.

Primeiro, inclua a classe UserService na parte superior do arquivo:

use google\appengine\api\users\UserService;

Em seguida, chame o serviço Usuários para receber informações sobre o usuário atual:

$user = UserService::getCurrentUser();

if (isset($user)) {
    return sprintf('Welcome, %s! (<a href="%s">sign out</a>)',
        $user->getNickname(),
        UserService::createLogoutUrl('/'));
} else {
    return sprintf('<a href="%s">Sign in or register</a>',
        UserService::createLoginUrl('/'));
}

Login e acesso de administrador obrigatórios com app.yaml

Se você tem páginas que exigem que o usuário faça login para acessá-las, é possível aplicar isso no arquivo app.yaml. Se um usuário acessa um URL configurado para exigir login, mas não está conectado, esse usuário é redirecionado pelo App Engine para a página de login do Google apropriada e levado de volta ao URL do aplicativo depois de se conectar ou se registrar com sucesso.

A configuração do gerenciador também pode exigir que o usuário seja um administrador registrado no aplicativo, ou seja, o usuário precisa ter o papel de Visualizador, Editor, Proprietário ou Administrador do App Engine. Isso facilita a criação de seções exclusivas para administradores do site, sem a necessidade de implementar um mecanismo de autorização separado.

Para saber como configurar a autenticação de URLs, veja como exigir status de administrador ou login na referência do app.yaml.

Opções de autenticação

O aplicativo pode autenticar usuários usando uma destas opções:

• uma Conta do Google
• uma conta no domínio do Google Workspace

Como escolher uma opção de autenticação

Depois de criar o aplicativo, é possível escolher a opção de autenticação que você quer usar. Por padrão, o aplicativo usará Contas do Google para autenticação. Se você quiser escolher outra opção, como o domínio do Google Workspace, acesse a página de configurações do projeto no console do Google Cloud e clique em Editar. No menu suspenso Autenticação do Google, selecione o tipo de autenticação de sua escolha e clique em Salvar.

Como fazer login e logout

Um aplicativo pode detectar se o usuário fez login com a opção de autenticação escolhida do aplicativo. Se o usuário não estiver conectado, ele poderá ser direcionado pelo aplicativo às Contas do Google para fazer login ou criar uma nova conta. O aplicativo obtém o URL da página de login chamando um método da API Users. O aplicativo pode exibir esse URL como um link ou emitir um redirecionamento HTTP para o URL quando o usuário visitar uma página que exija autenticação.

Se o aplicativo usar Contas do Google ou Google Workspace para autenticação, o nome do aplicativo aparecerá na página de login quando o usuário fizer login no aplicativo. O nome mostrado é o nome do aplicativo que você especificou ao registrá-lo. É possível alterar esse nome no campo Nome do aplicativo da página Credenciais do console do Google Cloud.

Depois que o usuário faz login ou cria uma conta do Google, ele é redirecionado para o aplicativo novamente. O aplicativo fornece o URL de redirecionamento ao método que gera o URL de login.

A API Users inclui um método que gera um URL para sair do aplicativo. O URL de logout cancela a autenticação do usuário do aplicativo e o redireciona para o URL do aplicativo sem exibir nada.

Um usuário não estará conectado a um aplicativo até que o login seja solicitado e ele insira o endereço de e-mail e a senha da conta. Isso é válido mesmo se o usuário tiver feito login em outros aplicativos usando a Conta do Google.

Como acessar informações da conta

Enquanto um usuário estiver conectado, o app poderá acessar o endereço de e-mail da conta para cada solicitação feita. O app também terá acesso a um ID exclusivo que identifica o usuário, mesmo que ele altere o endereço de e-mail da conta.

O aplicativo também pode determinar se o usuário atual é um administrador do aplicativo. Um usuário administrador é qualquer usuário que tenha o papel de Leitor, Editor, Proprietário ou Administrador do App Engine. É possível usar essa funcionalidade para criar recursos administrativos para o aplicativo, ainda que você não autentique usuários. As APIs Go, Java, PHP e Python facilitam a configuração de URLs como "somente administrador".

Observação: todos os usuários têm o mesmo ID para todos os aplicativos do App Engine. Se seu aplicativo usar o ID do usuário em dados públicos, incluindo-o em um parâmetro de URL, por exemplo, será necessário usar um algoritmo de hash com um valor de "salt" adicionado para ocultar o ID. A exposição de IDs brutos pode permitir que alguém associe a atividade de um usuário em um aplicativo à de outro aplicativo ou que receba o endereço de e-mail do usuário compelindo-o a fazer login em outro aplicativo.

Contas do Google e o servidor de desenvolvimento

O servidor de desenvolvimento simula o sistema de Contas do Google usando uma tela de login falsa. Quando o aplicativo chama a API Users para conseguir o URL da tela de login, a API retorna um URL especial do servidor de desenvolvimento que solicita um endereço de e-mail, mas não uma senha. Digite qualquer endereço de e-mail nessa solicitação e o aplicativo se comportará como se você tivesse feito login usando uma conta com esse endereço.

A tela de login falsa também inclui uma caixa de seleção que indica se a conta falsa é um administrador. Ou seja, se a conta tem o papel de Leitor, Editor, Proprietário ou Administrador do App Engine. você marcar essa caixa de seleção, o aplicativo se comportará como se você tivesse feito login usando uma conta de administrador.

Da mesma forma, a API Users retorna um URL de logout que cancela o login falso.

O ID exclusivo de um objeto User no servidor de desenvolvimento é calculado a partir do endereço de e-mail. Dois endereços de e-mail exclusivos sempre representam dois usuários exclusivos no servidor de desenvolvimento.