Users API for legacy bundled services

The Users API allows an application to:

  • Detect whether the current user has signed in.
  • Redirect the user to the appropriate sign-in page to sign in.
  • Request that your application user create a new Google account if they don't have one already.

While a user is signed in to the application, the app can access the user's email address. The app can also detect whether the current user is an administrator (also called "admin user"), making it easy to implement admin-only areas of the app.

User authentication in Java 8

The following example greets a user who has signed in to the app with a personalized message and a link to sign out. If the user is not signed in, the app offers a link to the sign-in page for Google Accounts.

You can test if the user is signed in and get the user's email address using the standard servlet API, with the request object's getUserPrincipal() method. You can use the User service API to generate sign-in and sign-out URLs.


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>");
    }
  }
}

The User service API can return the current user's information as a User object. Although User objects can be stored as a property value in the datastore, we strongly recommend that you avoid doing so because this includes the email address along with the user's unique ID. If a user changes their email address and you compare their old, stored User to the new User value, they won't match. Instead, consider using the User user ID value as the user's stable unique identifier.

Enforcing sign in and admin access with web.xml

If you have pages that the user should not be able to access unless signed in, you can establish a security constraint for those pages in the deployment descriptor (the web.xml file). If a user accesses a URL with a security constraint and the user is not signed in, App Engine redirects the user to the sign-in page automatically (for Google Accounts or Google Workspace authentication), then directs the user back to the URL after signing in or registering successfully.

A security constraint can also require that the user be a registered administrator for the application; that is, the user must have the Viewer, Editor, Owner, or App Engine Admin role. This makes it easy to build administrator-only sections of the site, without having to implement a separate authorization mechanism.

To learn how to set security constraints for URLs, see The Deployment Descriptor: Security and Authentication for web.xml.

Authentication options

Your app can authenticate users using one of these options:

  • A Google Account
  • An account on your Google Workspace domain

Choosing an authentication option

After you create your app, you can choose the authentication option you want to use. By default, your app will use Google Accounts for authentication. To choose another option, such as Google Workspace domain, go to the settings page for your project in the Google Cloud console and click Edit. In the Google authentication dropdown menu, select the desired authentication type, and then click Save.

Signing in and out

An application can detect whether a user has signed in to the app with your app's chosen authentication option. If the user is not signed in, the app can direct the user to Google Accounts to sign in or create a new Google account. The app gets the URL for the sign-in page by calling a method of the Users API. The app can display this URL as a link, or it can issue an HTTP redirect to the URL when the user visits a page that requires authentication.

If your app uses Google Accounts or Google Workspace for authentication, the name of your application appears on the sign-in page when the user signs in to your application. The name shown is the application name that you specified when registering the application. You can change this name in the Application name field of the Google Cloud console Credentials page.

Once the user has signed in or created a Google account, the user is redirected back to your application. The app provides the redirect URL to the method that generates the sign-in URL.

The Users API includes a method to generate a URL for signing out of the app. The sign-out URL de-authenticates the user from the app, then redirects back to the app's URL without displaying anything.

A user is not signed in to an application until they are prompted to do so by the app and enter their account's email address and password. This is true even if the user has signed in to other applications using their Google Account.

Accessing account information

While a user is signed in to an app, the app can access the account's email address for every request the user makes to the app. The app can also access a user ID that identifies the user uniquely, even if the user changes the email address for their account.

The app can also determine whether the current user is an administrator for the app. An admin user is any user that has the Viewer, Editor, Owner, or App Engine Admin role. You can use this feature to build administrative features for the app, even if you don't authenticate other users. The Go, Java, PHP and Python APIs make it easy to configure URLs as "administrator only".

Users and the Datastore

The Users service API can return the current user's information as a User object. Although User objects can be stored as a property value in the datastore, we strongly recommend that you avoid doing so because this includes the email address along with the user's unique ID. If a user changes their email address and you compare their old, stored User to the new User value, they won't match. Instead, consider using the User user ID value as the user's stable unique identifier.

Google accounts and the development server

The development server simulates the Google Accounts system using a fake sign-in screen. When your application calls the Users API to get the URL for the sign-in screen, the API returns a special development server URL that prompts for an email address, but no password. You can type any email address into this prompt, and the app will behave as if you are signed in with an account with that address.

The fake sign-in screen also includes a checkbox that indicates whether the fake account is an administrator; that is, whether the account has the Viewer, Editor, Owner, or App Engine Admin role. If you check this box, the app will behave as if you are signed in using an administrator account.

Similarly, the Users API returns a sign-out URL that cancels the fake sign-in.