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).
- OAuth 2.0
- OAuth 1.0
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.
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:
from google.appengine.api import oauth scope = 'https://www.googleapis.com/auth/userinfo.email' self.response.write('\noauth.get_current_user(%s)' % repr(scope)) try: user = oauth.get_current_user(scope) allowed_clients = ['407408718192.apps.googleusercontent.com'] # list your client ids here token_audience = oauth.get_client_id(scope) if token_audience not in allowed_clients: raise oauth.OAuthRequestError('audience of token \'%s\' is not in allowed list (%s)' % (token_audience, allowed_clients)) self.response.write(' = %s\n' % user) self.response.write('- auth_domain = %s\n' % user.auth_domain()) self.response.write('- email = %s\n' % user.email()) self.response.write('- nickname = %s\n' % user.nickname()) self.response.write('- user_id = %s\n' % user.user_id()) except oauth.OAuthRequestError, e: self.response.set_status(401) self.response.write(' -> %s %s\n' % (e.__class__.__name__, e.message)) logging.warn(traceback.format_exc())
get_current_user returns an object representing the user associated with the
request. If the access token is invalid, the method
raises an exception.
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 raises 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 Python request handler:
from google.appengine.api import oauth # ... try: # Get the db.User that represents the user on whose behalf the # consumer is making this request. user = oauth.get_current_user() except oauth.OAuthRequestError, e: # The request was not a valid OAuth request. # ...
On the local development server,
oauth.get_current_user() always returns a User object with
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.
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
www.example.com, the endpoints for the OAuth protocol begin as follows:
If the app uses its
appspot.com 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
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:
Request tokens are valid for 10 minutes.
App Engine does not support the
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: