API Users para serviços agrupados antigos

A API Users permite que uma aplicação:

  • Detetar se o utilizador atual tem sessão iniciada.
  • Redirecionar o utilizador para a página de início de sessão adequada para iniciar sessão.
  • Peça ao utilizador da aplicação para criar uma nova Conta Google se ainda não tiver uma.

Enquanto um utilizador tem sessão iniciada na aplicação, a app pode aceder ao endereço de email do utilizador. A app também pode detetar se o utilizador atual é um administrador (também denominado "utilizador administrador"), o que facilita a implementação de áreas da app apenas para administradores.

Autenticação de utilizadores em Java 8

O exemplo seguinte saúda um utilizador que iniciou sessão na app com uma mensagem personalizada e um link para terminar sessão. Se o utilizador não tiver sessão iniciada, a app oferece um link para a página de início de sessão das Contas Google.

Pode testar se o utilizador tem sessão iniciada e obter o endereço de email do utilizador através da API servlet padrão, com o método getUserPrincipal() do objeto de pedido. Pode usar a API User service para gerar URLs de início e fim de sessão.


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 User service pode devolver as informações do utilizador atual como um objeto User. Embora os objetos User possam ser armazenados como um valor de propriedade no arquivo de dados, recomendamos vivamente que evite fazê-lo, uma vez que inclui o endereço de email juntamente com o ID exclusivo do utilizador. Se um utilizador alterar o respetivo endereço de email e comparar o valor User antigo armazenado com o novo valor User, não vai haver correspondência. Em alternativa, considere usar o User valor de ID do utilizador como o identificador exclusivo estável do utilizador.

Impor o início de sessão e o acesso de administrador com o ficheiro web.xml

Se tiver páginas às quais o utilizador não deve ter acesso, a menos que tenha sessão iniciada, pode estabelecer uma restrição de segurança para essas páginas no descritor de implementação (o ficheiro web.xml). Se um utilizador aceder a um URL com uma restrição de segurança e não tiver sessão iniciada, o App Engine redireciona o utilizador automaticamente para a página de início de sessão (para autenticação de Contas Google ou do Google Workspace) e, em seguida, redireciona o utilizador de volta para o URL após iniciar sessão ou registar-se com êxito.

Uma restrição de segurança também pode exigir que o utilizador seja um administrador registado para a aplicação, ou seja, o utilizador tem de ter a função de visualizador, editor, proprietário ou administrador do App Engine. Isto facilita a criação de secções do site apenas para administradores, sem ter de implementar um mecanismo de autorização separado.

Para saber como definir restrições de segurança para URLs, consulte o artigo O descritor de implementação: segurança e autenticação para web.xml.

Opções de autenticação

A sua app pode autenticar utilizadores através de uma destas opções:

  • Uma Conta Google
  • Uma conta no seu domínio do Google Workspace

Escolher uma opção de autenticação

Depois de criar a app, pode escolher a opção de autenticação que quer usar. Por predefinição, a sua app usa Contas Google para autenticação. Para escolher outra opção, como o domínio do Google Workspace, aceda à página de definições do seu projeto na Google Cloud consola e clique em Editar. No menu pendente Autenticação Google, selecione o tipo de autenticação pretendido e, de seguida, clique em Guardar.

Iniciar e terminar sessão

Uma aplicação pode detetar se um utilizador iniciou sessão na app com a opção de autenticação escolhida pela app. Se o utilizador não tiver sessão iniciada, a app pode direcioná-lo para as Contas Google para iniciar sessão ou criar uma nova Conta Google. A app obtém o URL da página de início de sessão chamando um método da API Users. A app pode apresentar este URL como um link ou pode emitir um redirecionamento HTTP para o URL quando o utilizador visita uma página que requer autenticação.

Se a sua app usar Contas Google ou o Google Workspace para autenticação, o nome da sua aplicação aparece na página de início de sessão quando o utilizador inicia sessão na sua aplicação. O nome apresentado é o nome da aplicação que especificou quando registou a aplicação. Pode alterar este nome no campo Nome da aplicação da página Credenciais da Google Cloud consola Google Cloud .

Assim que o utilizador tiver iniciado sessão ou criado uma Conta Google, é redirecionado de volta para a sua aplicação. A app fornece o URL de redirecionamento ao método que gera o URL de início de sessão.

A API Users inclui um método para gerar um URL para terminar sessão na app. O URL de saída anula a autenticação do utilizador na app e, em seguida, redireciona-o de volta para o URL da app sem apresentar nada.

Um utilizador não tem sessão iniciada numa aplicação até que a aplicação lhe peça para o fazer e introduza o endereço de email e a palavra-passe da respetiva conta. Isto é verdade mesmo que o utilizador tenha iniciado sessão noutras aplicações com a respetiva Conta Google.

Aceder às informações da conta

Enquanto um utilizador tem sessão iniciada numa app, a app pode aceder ao endereço de email da conta para cada pedido que o utilizador faz à app. A app também pode aceder a um ID do utilizador que identifica o utilizador de forma exclusiva, mesmo que o utilizador altere o endereço de email da respetiva conta.

A app também pode determinar se o utilizador atual é um administrador da app. Um utilizador administrador é qualquer utilizador que tenha a função de leitor, editor, proprietário ou administrador do App Engine. Pode usar esta funcionalidade para criar funcionalidades administrativas para a app, mesmo que não autentique outros utilizadores. As APIs Go, Java, PHP e Python facilitam a configuração de URLs como "apenas para administradores".

Utilizadores e armazenamento de dados

A API Users service pode devolver as informações do utilizador atual como um objeto User. Embora os objetos User possam ser armazenados como um valor de propriedade no arquivo de dados, recomendamos vivamente que evite fazê-lo, uma vez que inclui o endereço de email juntamente com o ID exclusivo do utilizador. Se um utilizador alterar o respetivo endereço de email e comparar o valor User antigo armazenado com o novo valor User, não vai haver correspondência. Em alternativa, considere usar o User valor de ID do utilizador como o identificador exclusivo estável do utilizador.

Contas Google e o servidor de programação

O servidor de desenvolvimento simula o sistema de Contas Google através de um ecrã de início de sessão falso. Quando a sua aplicação chama a API Users para obter o URL do ecrã de início de sessão, a API devolve um URL de servidor de desenvolvimento especial que pede um endereço de email, mas não uma palavra-passe. Pode escrever qualquer endereço de email neste comando e a app vai comportar-se como se tivesse sessão iniciada com uma conta com esse endereço.

O ecrã de início de sessão falso também inclui uma caixa de verificação que indica se a conta falsa é um administrador, ou seja, se a conta tem a função de visualizador, editor, proprietário ou administrador do App Engine. Se selecionar esta caixa, a app vai comportar-se como se tivesse sessão iniciada com uma conta de administrador.

Da mesma forma, a API Users devolve um URL de saída que cancela o início de sessão falso.