Adding a Method Protected by OAuth 2.0

In this tutorial, we are adding a new protected method called greetings.authed.

Any client can access your Endpoints API methods unless you protect them with OAuth 2.0. In some scenarios, you may want to restrict access to some or all of the API methods.

To protect a method in the backend API, you need to do the following:

  • Use the allowed_client_ids argument in the @endpoints.api decorator to provide a whitelist of allowed clients.
  • Add the email scope (endpoints.EMAIL_SCOPE) to your @endpoints.api decorator.
  • Add a current user check (endpoints.get_current_user) to each method you wish to protect.

Adding an OAuth 2.0-protected method

The auth configuration is used to define which client IDs can access the API. If you're testing locally with the API explorer you don't need to fill these in, but if you want to try to use your API from a web or mobile client you will need to configure this section with your project-specific values. For more information on creating client IDs, see Creating OAuth 2.0 client IDs.

WEB_CLIENT_ID = 'replace this with your web client application ID'
ANDROID_CLIENT_ID = 'replace this with your Android client ID'
IOS_CLIENT_ID = 'replace this with your iOS client ID'

Because we specify that the endpoints.API_EXPLORER_CLIENT_ID, you can use test this locally without any configuration.

The ANDROID_AUDIENCE is required only for android client and isn't used by any other clients. For more information, see Allowed Client IDs and Audiences

The AuthedGreetingApi service shows how to provide the auth configuration to the @endpoints.api decorator and how to call endpoints.get_current_user:

    # Only allowed configured Client IDs to access this API.
    # Only allow auth tokens with the given audience to access this API.
    # Require auth tokens to have the following scopes to access this API.
class AuthedGreetingApi(remote.Service):

    def greet(self, request):
        user = endpoints.get_current_user()
        user_name = if user else 'Anonymous'
        return Greeting(message='Hello, {}'.format(user_name))

Notice that we supplied the email scope, endpoints.EMAIL_SCOPE. Although you can add other scopes, you must always include the email scope if you use OAuth.

Deploying and Testing

To test the backend API with real Auth, you must deploy your backend API to the App Engine project you created at the beginning of this tutorial.

To deploy and run:

  1. Deploy the backend you just created to App Engine by invoking the following:

    ~/path/to/python/sdk/google_appengine/ update -A your-app-id -V v1 .

    When the backend finishes deploying, a message similar to this one is displayed:

    09:08 AM Completed update of app: your-app-id, version: v1
  2. Check the logs for your project to make sure the backend deployed successfully.

  3. Open API Explorer at this URL in your browser:
  4. In the API Explorer, click authed_greeting API > authed_greeting.greet.

  5. Click Authorize and execute.

  6. When prompted to supply additional scopes, use the default scope provided by clicking Authorize and execute again.

  7. Observe the authorization in the request, and a greeting with your user name in the response.

Code summary

If the request coming in from the client has a valid auth token or is in the list of authorized clientIDs, the backend framework supplies a valid User when endpoints.get_current_user() is invoked. If the incoming request does not have a valid auth token or if the client is not on the clientIDs whitelist, endpoints.get_current_user() returns None.

Accordingly, if the request comes from a client that isn't in the whitelist, there will be no current user. Your own code must handle both the case where the current user is null and the case where there is a valid current user. If there is no user, for example, you could choose to return a not-authenticated error or perform some other desired action. In this tutorial, we simply identify the non authenticated user as Anonymous.

What's next

This completes the tutorial.

For the advanced topics such as using datastore and creating clients of the API backend, see the following:

Send feedback about...

App Engine standard environment for Python