Google Cloud Platform
Python

Using Auth with Endpoints

You must specify Endpoints auth following the directions provided on this page. Note that you cannot set a user login requirement following the instructions in the app.yaml reference on login: admin to configure the app.yaml file, because this will result in a deployment failure.

For information on authentication from the perspective of keeping the backend secure, see the blog post Verifying Back-End Calls from Android Apps.

Adding authorization to an API backend

If you wish to protect all or part of your API by authorization, you must:

  1. Specify the client IDs (allowed_client_ids) allowed to make requests.
  2. Add a User Check to all exposed methods to be protected by authorization.
  3. Redeploy the API backend.
  4. Generate the client library again.

Specifying authorized clients in the API backend

You must specify which clients are allowed to access the backend by means of a list of client IDs. A client ID is generated by the Google Cloud Platform Console from a client secret, such as the SHA1 fingerprint of a key used to secure an Android app, or from the Bundle ID/Apple Store ID pair for an iOS app, as described in Creating OAuth 2.0 Client IDs. At runtime, a client app is granted the authorization token it needs to send requests to the backend if its client secret matches one contained in a client ID within the backend's client ID list.

To specify which clients are authorized to access your API backend:

  1. Get a complete list of the client IDs of the clients that you want to grant access to. This list is a list of OAuth 2.0 client IDs obtained for your project following the instructions provided below under Creating OAuth 2.0 Client IDs.
  2. In the allowed_client_ids argument of the @endpoints.api decorator or @endpoints.method decorator for your API, supply the list of client IDs that you want to authenticate.
    • For an iOS app, supply its iOS client ID in the allowed_client_ids whitelist.
    • For a javascript app, supply its web client ID in the allowed_client_ids whitelist.
    • For an Android app, supply both its Android client ID and a web client ID in allowed_client_ids whitelist. (You must add that same web client ID to the audiences list as shown next.)
  3. If you have an Android client, you must also supply the audiences argument for the @endpoints.api decorator, set to the web client ID mentioned in the preceding step. The same web client ID must be in both allowed_client_ids and audiences.

Adding a user check to methods

The API backend framework automatically authenticates the user and enforces the allowed_client_ids whitelist of authorized clients, by supplying a valid User or not in the API backend, which you can obtain using endpoints.get_current_user(). If the request from the app has a valid auth token or is in the list of allowed_client_ids, the framework supplies a valid User. If the incoming request does not have a valid auth token or if the client is not on the allowed_client_ids, the framework sets the User to null. Your own code must handle the null case and the non-null case, as shown below.

To require user authorization for a method, you need to check for the existence of a valid User obtained from the incoming request. To do this:

  1. Import the App Engine Endpoints API in your API class:

    import endpoints
    
  2. Inside the method, get the current authorized user by invoking endpoints.get_current_user() in your method. If the incoming method has a valid auth or ID token, endpoints.get_current_user() returns a User, otherwise it returns None.

  3. If there is no valid User, raise the exception endpoints.UnauthorizedException, as shown in the following snippet:

    current_user = endpoints.get_current_user()
    if raise_unauthorized and current_user is None:
      raise endpoints.UnauthorizedException('Invalid token.')
    

Supporting authorization in clients

If your API backend requires authentication, you need to also provide support for authorization in your Android, iOS, or JavaScript client. Instructions for this vary slightly by client type, so more information is provided in these client-specific pages:

Creating OAuth 2.0 client IDs

If you wish to require authorization to access your API backend, you must obtain the required client IDs and supply them to the backend using the proper API decorator argument. Precisely which client IDs are required and how you need to supply them can vary depending on whether the client is an Android app, iOS app, or javascript app. For details, see [Specifying Authorized Clients in the API Backend](#Specifying_authorized_clients_in_the_API_backend).

Android

In order to create the OAuth 2.0 Android client ID, you'll need to have a certificate key fingerprint. If you use Eclipse with the Android Developer Tools (ADT) plugin, a debug keystore and a debug key are created automatically. You can use the debug key for testing purposes, but you must use a release key for production.

Note that the default debug keystore password is android, and the key alias is androiddebugkey. The default location for Linux and Mac OS X is ~/.android.

  1. Generate a debug (or release) key for your Android application, if you don't already have one. If you use Eclipse with the Android Developer Tools plugin, Eclipse automatically generates a debug key in the debug keystore the first time you build an Android project.
  2. In a Linux or Mac OS X terminal window, you can get the fingerprint of the key using the keytool (included with the Java SDK) as follows:
    keytool -exportcert -alias androiddebugkey -keystore path-to-debug-or-production-keystore -list -v
    The fingerprint looks something like this: DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09
  3. Copy and save the key fingerprint that is displayed after your run the above keytool command. You'll need to supply this next to generate the Android client ID in the console.
  4. Go to the Credentials page in the Cloud Platform Console.
    Go to the Credentials page.
    1. Select Android as the application type.
    2. In Signing-certificate fingerprint, enter the fingerprint you obtained above..
    3. In Package name, enter the Android application package name, as specified in your AndroidManifest.xml file.
  5. Click Create.
  6. Note the client ID that is generated. This is the client ID you need to use in your backend and in your client application.

iOS

  1. Go to the Credentials page in the Cloud Platform Console.
    Go to the Credentials page.
    1. Select iOS as the application type.
    2. In Name, enter the name of your iOS app.
    3. In Bundle ID, specify your application’s bundle identifier as listed in your application's .plist file (e.g. com.example.myapp).
    4. In App Store ID, optionally enter the App Store ID if the app was published in the Apple iTunes® App Store.
  2. Click Create.
  3. Note the client ID that is generated. This is the client ID you need to use in your backend and in your client application.

web client

  1. Go to the Credentials page in the Cloud Platform Console.
    Go to the Credentials page
    1. Select Web application as the application type.
    2. In Name, enter the name of your web client.
    3. In Authorized JavaScript origins, enter one of the following:
      • http://localhost:8080 if you are testing the backend locally.
      • https://your_project_id.appspot.com, replacing your_project_id with your actual App Engine project ID if you are deploying your backend API to production App Engine.

  2. Click Create.
  3. Note the client ID that is generated. This is the client ID you need to use in your backend and in your client application.