Skip to page content Skip to main navigation
English | Site Directory

e.g. "templates" or "datastore"

# Google Accounts Java API Overview

App Engine applications can authenticate users with Google Accounts. An application can detect whether the current user has signed in with a Google Account, and can redirect the user to the Google Accounts sign-in page to sign in or create a new account. 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, making it easy to implement admin-only areas of the app.

Google Accounts integration is an optional feature of App Engine. If you do not wish to integrate your app with Google Accounts, you can always build your own system for user authentication. Google Accounts offers a robust, easy to use authentication mechanism with a mature set of features and millions of active users.

- Using Google Accounts in Java
- Signing In and Out
- Accessing Account Information
- Users and the Datastore
- Google Accounts and the Development Server

## Using Google Accounts in Java

You can test if the user is signed in with a Google Account 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.

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

    public class MyServlet extends HttpServlet {
        public void doGet(HttpServletRequest request, HttpServletResponse response)
                throws IOException {
            UserService userService = UserServiceFactory.getUserService();

            String thisURL = request.getRequestURI();
            if (request.getUserPrincipal() != null) {
                response.getWriter().println("<p>Hello, " +
                                             request.getUserPrincipal().getName() +
                                             "!  You can <a href=\"" +
                                             userService.createLogoutURL(thisURL) +
                                             "\">sign out</a>.</p>");
            } else {
                response.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. User objects can be stored as property value in the datastore.

### 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 Google Accounts sign-in page automatically, 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. This makes it easy to implement 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.

## Signing In and Out

An application can detect whether a user has signed in to the app with a Google Account. 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 Google Accounts sign-in screen 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.

The Google Accounts sign-in screen informs the user that she is signing in to your application, using the application name you chose when registering the application. You can change your application name in the "Application Settings" section of the Admin Console.

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 also 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 she is prompted to do so by the app and enters her account's email address and password. This is true even if the user has signed in to other applications using her 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 determine whether the current user is an administrator (a "developer") for the app. You can use this feature to build administrative features for the app, even if you don't use Google Accounts to authenticate other users. The Java and Python APIs make it easy to configure URLs as "administrator only."

## Users and the Datastore

The App Engine datastore supports storing the User object returned by the Google Accounts API as a special value type. As of this writing, User values do not behave as stable identifiers for users: if an app stores a User value and the user changes her email address, the User value will no longer refer to a valid user. In practice, users rarely change their Google Account email addresses, but it's worth designing for this rare case. A future update to the service may update User values in the datastore automatically. Until then, it is a best practice to not rely on the User value for stability.

The Java API does not currently expose a unique user ID beyond the email address.

## Google Accounts and the Development Server

The development server simulates the Google Accounts system using a dummy 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 dummy sign-in screen also includes a checkbox that indicates whether the dummy account is an administrator. 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 dummy sign-in.