OAuth API for Java

Python |Java |PHP |Go

The App Engine OAuth API uses the OAuth protocol and provides a way for your app to authenticate a user who is requesting access without asking for her credientials (username and password).

  1. OAuth 2.0
    1. Generating an access token
    2. Using the API
  2. OAuth 1.0
    1. Three-legged Authentication
    2. OAuth 1.0 endpoints
    3. Getting a request token
    4. Redirecting a user to authorize
    5. Getting an access token

OAuth 2.0

OAuth 2.0 access tokens supplied by the Google Sign-In library and low-level OAuth 2.0 endpoints can be used to authenticate clients with the OAuth API and retrieve user identity information.

Generating an access token

Follow the steps outlined at Using OAuth 2.0 to Access Google APIs.

The client should send the resulting OAuth 2.0 access token in the Authorization: Bearer HTTP Request Header on every request to your AppEngine app.

You can also obtain an access token using one of the Google Sign-in client libraries for Android, iOS, or the web.

Using the API

When a client sends a request to your app, the authorization header of the request includes an OAuth access token that has one or more scopes associated with it, indicating what APIs the client can access. Your app can retreive information about the user who granted the access token by running this code:

OAuthService oauth = OAuthServiceFactory.getOAuthService();
String scope = "";
Set<String> allowedClients = new HashSet<>();
allowedClients.add(""); // list your client ids here

try {
  User user = oauth.getCurrentUser(scope);
  String tokenAudience = oauth.getClientId(scope);
  if (!allowedClients.contains(tokenAudience)) {
    throw new OAuthRequestException("audience of token '" + tokenAudience
        + "' is not in allowed list " + allowedClients);
  // proceed with authenticated user
  // ...
} catch (OAuthRequestException ex) {
  // handle auth error
  // ...
} catch (OAuthServiceFailureException ex) {
  // optionally, handle an oauth service failure
  // ...

getCurrentUser returns an object representing the user associated with the request. If the access token is invalid, the method returns an error.

OAuth 1.0

App Engine apps can provide web service endpoints to consumers, using OAuth to authenticate users and consumers. Google Accounts handles all aspects of the OAuth protocol. The app uses the App Engine OAuth API to identify the user on whose behalf the consumer is acting for a request.

The user must have a Google account to sign in and authorize a consumer. If an app uses federated logins (OpenID), the user is sent directly to Google Accounts to sign in to authorize a consumer. Other OpenID identity providers are not supported for OAuth authentication.

The scope of an authorization, how much the consumer is allowed to access, is for all of a single app. App Engine only supports whole-app scopes, and does not support more granular scope requests. When Google Accounts prompts the user to authorize a consumer, the prompt explains that the consumer is requesting permission to access the full app.

You implement request handlers for OAuth-authorized web service endpoints just as you would any other request handler. To access the OAuth user information, you call the App Engine OAuth API. Calling the OAuth API throws an exception if the caller is not authorized to access the app, or otherwise did not provide valid OAuth information.

Here is a simple example of accessing OAuth user information in a Java servlet:


// ...
User user = null;
try {
    OAuthService oauth = OAuthServiceFactory.getOAuthService();
    user = oauth.getCurrentUser();

} catch (OAuthRequestException e) {
    // The consumer made an invalid OAuth request, used an access token that was
    // revoked, or did not provide OAuth information.
    // ...

On the local development server, oauth.getCurrentUser() always returns a User object with email set to "" and user ID set to 0 regardless of whether or not a valid OAuth request was made.

Three-legged Authentication

The complete interaction between the consumer and the service provider involves several steps (in what is called "three-legged authentication"):

  1. To initiate access on behalf of a user, the consumer calls a web service endpoint to get a request token for the app. This is a temporary token used solely for the authentication process. The call to get the request token includes a URL where the user's browser will be directed after authentication is complete.
  2. The consumer directs the user's browser to the Google Accounts authorization URL with parameters, including the request token. The user signs in with her credentials, then tells Google Accounts that the consumer is authorized to access the service provider on her behalf. Google Accounts redirects the user back to the consumer web application at the URL provided when the consumer got the request token.
  3. The consumer calls a web service endpoint to exchange the request token for an access token.
  4. The consumer can now call the service provider application's own web service endpoints using the access token.
Your application sends a token request to the Google Authorization Server, receives an authorization code, 
exchanges the code for a token, and uses the token to call a Google API endpoint.

OAuth 1.0 endpoints

The consumer performs OAuth actions using a set of standard web service endpoints. These endpoints use reserved paths on your app's domain. For example, if your app uses a Google Apps domain of, the endpoints for the OAuth protocol begin as follows:

If the app uses its domain for its web services, the OAuth endpoints begin as follows:

These endpoints are part of the OAuth authorization protocol. The app's own web service endpoints can use any URL path.

Google Apps domains and domains, including version-specific domains, are supported. Note that authorization is associated with the domain used to access the endpoints: an access token produced using endpoints on one domain cannot be used to access the app using a different domain. If the access token came from a version-specific domain, it can only be used to access that version of the app, and only at that domain.

Getting a request token

To initiate the authorization process on behalf of a user, a consumer calls an OAuth endpoint to get a request token. This temporary token is used to facilitate the rest of the authorization process. For more information about this part of the protocol, see Accounts API: OAuthGetRequestToken.

An App Engine app's request token endpoint has the following path:

Request tokens are valid for 10 minutes.

App Engine does not support the scope and xoauth_displayname parameters. The scope for the request is the entire app.

Redirecting a user to authorize

Once the consumer has a request token, it must direct the user to sign in using Google Accounts and authorize the consumer to access the service provider on her behalf. The consumer must direct the user's browser to visit a URL that prompts the user using a web-based user interface. This URL includes parameters for the request token and other data. For more information about this part of the protocol, see Accounts API: OAuthAuthorizeToken.

For a service provider using App Engine OAuth, the consumer directs the user's browser to the following path, with appropriate arguments:

App Engine removes or replaces the hd argument to represent the authorization domain of the application, if any.

Getting an access token

Once authorized, the consumer calls the service provider to get an access token. The consumer includes this token with all requests to the application's web service endpoints. The access token is valid until the user revokes the access using the Google Accounts management interface. For more information about this part of the protocol, see Accounts API: OAuthGetAccessToken.

An App Engine app's access token endpoint has the following path: