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 1.0 specification , the application seeking permission is the consumer , and the application providing the data is the service provider .
Using Google Accounts and a simple API, any App Engine application can be an OAuth 1.0 service provider. Google Accounts handles the details of the OAuth 1.0 protocol. The app accesses the consumer authentication information using the OAuth API during a service request, just as it would with the Users API if the user were accessing the app directly.
This documentation does not describe the OAuth protocol, or consumer implementation issues such as signing requests. See OAuth for Web Applications and the OAuth website for more information about the protocol.
Introducing OAuth
As users put more of their information online, it becomes increasingly useful for networked applications to access that data, even when the data is not stored in the application itself. If access to that data is restricted by a username and password, the data-consuming application (the consumer ) needs a way to tell the service holding the data (the service provider ) that it is acting on behalf of the user. One way to do this is for the user to give her username and password to the consumer—but with most services, this gives the consumer too much control over the user's account with the service provider, and risks exposing the user's password if the consumer has a security breach.
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"):
- 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.
- 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.
- The consumer calls a web service endpoint to exchange the request token for an access token .
- The consumer can now call the service provider application's own web service endpoints using the access token until the user revokes access using the Google Accounts management interface , under "Change authorized websites."
The consumer can optionally register with the service provider in advance, providing a security certificate used to sign OAuth requests. A consumer need only register once with Google for all applications, including Google applications with OAuth-backed interfaces. Registration is optional for accessing service providers on App Engine, but recommended as it provides several important features. For more information, see Registration for Web-Based Applications .
For an explanation of OAuth from the consumer's perspective, see OAuth for Web Applications and the OAuth website .
OAuth 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 returns an error 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 Go:
import (
"fmt"
"net/http"
"appengine"
"appengine/user"
)
func welcome(w http.ResponseWriter, r *http.Request) {
c := appengine.NewContext(r)
u, err := user.CurrentOAuth(c, "")
if err != nil {
http.Error(w, "OAuth Authorization header required", http.StatusUnauthorized)
return
}
if !u.Admin {
http.Error(w, "Admin login only", http.StatusUnauthorized)
return
}
fmt.Fprintf(w, `Welcome, admin user %s!`, u)
}
On the local development server,
user.CurrentOAuth()
always returns a User object with
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