Hide
Java

OAuth for Java Overview

Python |Java |PHP |Go

OAuth is a protocol that allows a user to grant a third party limited permission to access a web application on her behalf, without sharing her credentials (username and password) with the third party. The third party can be a web application, or any other application with the capability of invoking a web browser for the user, such as a desktop application or an app running on a smart phone. In the terms of the OAuth specification, the application seeking permission is the consumer, and the application providing the data is the service provider.

  1. Introducing OAuth
  2. OAuth consumer
  3. OAuth service provider and App Engine (Alpha)
  4. OAuth endpoints

Introducing OAuth

The OAuth protocol provides a way for a consumer to authenticate with a service provider and act on behalf of a user without the user having to give the consumer her username and password. For example, a travel application may have a feature to add an itinerary to a user's Google Calendar automatically. The travel application communicates with Google Calendar, and directs the user's browser to a Google Accounts authorization screen. The user signs in using her Google account, and tells Google Calendar that the travel application has permission to access her calendar data. The travel application can now access the user's calendar and add travel itineraries. It can do so until the user revokes this permission from her Google Accounts settings.

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 consumer

Google APIs use the OAuth 2.0 protocol for authentication and authorization. Google supports common OAuth 2.0 scenarios for web servers, service accounts, and client-side applications.

To begin using OAuth2, obtain OAuth 2.0 credentials from the Google Developers Console. Your client application will then request an access token from the Google Authorization Server, extracting a token from the response, and sending the token to the Google API that you want to access.

If you are using App Engine to access Google Apps or Google for Work APIs, you can create a service account with domain-wide delegation of authority. This allows domain administrators the ability to grant third party applications domain-wide access to its users' data. The Google Apps Domain-Wide Delegation of Authority page contains examples of how to implement this using Google Drive.

More information on OAuth consumer scenarios is available at Google Accounts Authentication and Authorization.

OAuth service provider and App Engine

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:

import com.google.appengine.api.users.User;
import com.google.appengine.api.oauth.OAuthRequestException;
import com.google.appengine.api.oauth.OAuthService;
import com.google.appengine.api.oauth.OAuthServiceFactory;
import com.google.appengine.api.oauth.OAuthServiceFailureException;

// ...
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 "example@example.com" and user ID set to 0 regardless of whether or not a valid OAuth request was made.

OAuth 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 www.example.com, the endpoints for the OAuth protocol begin as follows:

https://www.example.com/_ah/OAuth...

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

https://your_app_id.appspot.com/_ah/OAuth...

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 appspot.com domains, including version-specific appspot.com 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 appspot.com 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:

https://your_app_id.appspot.com/_ah/OAuthGetRequestToken

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:

https://your_app_id.appspot.com/_ah/OAuthAuthorizeToken

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:

https://your_app_id.appspot.com/_ah/OAuthGetAccessToken