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.

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.

Autenticação de usuário em Java 8

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.

Você pode testar se o usuário está conectado e recebe o endereço de e-mail do usuário usando a API do servlet padrão, com o método getUserPrincipal() do objeto da solicitação. É possível usar a API do serviço Usuários para gerar URLs de login e logout.


package com.example.appengine.users;

import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;
import java.io.IOException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

// With @WebServlet annotation the webapp/WEB-INF/web.xml is no longer required.
@WebServlet(
    name = "UserAPI",
    description = "UserAPI: Login / Logout with UserService",
    urlPatterns = "/userapi"
)
public class UsersServlet extends HttpServlet {

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    UserService userService = UserServiceFactory.getUserService();

    String thisUrl = req.getRequestURI();

    resp.setContentType("text/html");
    if (req.getUserPrincipal() != null) {
      resp.getWriter()
          .println(
              "<p>Hello, "
                  + req.getUserPrincipal().getName()
                  + "!  You can <a href=\""
                  + userService.createLogoutURL(thisUrl)
                  + "\">sign out</a>.</p>");
    } else {
      resp.getWriter()
          .println(
              "<p>Please <a href=\"" + userService.createLoginURL(thisUrl) + "\">sign in</a>.</p>");
    }
  }
}

A API do serviço Usuários pode retornar as informações do usuário atual como um objeto User. Os objetos User podem ser salvos como um valor de propriedade no armazenamento de dados. No entanto, é altamente recomendável evitar isso, pois esse tipo de armazenamento inclui o endereço de e-mail junto com o ID exclusivo do usuário. Se um usuário alterar o endereço de e-mail e você comparar o User antigo armazenado com o novo valor de User, eles não serão correspondentes. Em vez disso, use o valor de ID do usuário User como o identificador exclusivo estável do usuário.

Como aplicar o login e o acesso administrativo com o web.xml

Se você tem páginas que o usuário não pode acessar a menos que esteja conectado, é possível estabelecer uma restrição de segurança para essas páginas no descritor de implantação (o arquivo web.xml). Se um usuário acessar um URL com restrição de segurança sem estar logado, o App Engine o redirecionará automaticamente para a página de login, para autenticação do Google Workspace ou das Contas do Google, e depois direcionará o usuário de volta ao URL após fazer login ou se registrar.

Uma restrição de segurança também pode exigir que o usuário seja um administrador registrado no aplicativo, ou seja, o usuário precisa ter o papel de Leitor, 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 definir restrições de segurança para URLs, consulte Descritor de implantação: segurança e autenticação para web.xml.

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

Usuários e o armazenamento de dados

A API do serviço Usuários pode retornar as informações do usuário atual como um objeto User. Os objetos User podem ser salvos como um valor de propriedade no armazenamento de dados. No entanto, é altamente recomendável evitar isso, porque esse tipo de armazenamento inclui o endereço de e-mail e o ID exclusivo do usuário. Se um usuário alterar o endereço de e-mail, e você comparar o User antigo armazenado com o novo valor de User, eles não serão correspondentes. Em vez disso, use o valor de ID do usuário User como o identificador exclusivo estável do usuário.

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.