Google App Engine

Using Auth with Endpoints

Requirements: a Google API project

The instructions on this page assume that you have already have a project for your application in the Google Developers Console. If you don't have one yet, here's how to create one:

Visit the Google Developers Console and select Create Project. Enter a name and a project ID, or accept the defaults, and select Create.

Adding authorization to an API backend

If you wish to restrict all or part of your API to only authorized apps, you must:

  1. Specify the client IDs (clientIds) of apps authorized to make requests to your API backend.
  2. Add a User parameter to all exposed methods to be protected by authorization.
  3. Regenerate client Libraries and redeploy it.
  4. If you have an Android client,update the regenerated jar file to your Android project.
  5. If you have an iOS client, regenerate the Objective-C library.

Specifying authorized clients in the API backend

You must specify which clients are allowed to access the API backend by means of a whitelist of client IDs. A client ID is generated by the Google Developers 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 API backend if its client secret matches one contained in a client ID within the API backend's client ID whitelist.

To specify which clients can be authenticated by 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 clientIds attribute of the @Api or @ApiMethod annotations 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 clientIds whitelist.
    • For a javascript app, supply its web client ID in the clientIds whitelist.
    • For an Android app, you must supply both its Android client ID and a web client ID in clientIds 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 attribute for the @Api annotation, set to the web client ID mentioned in the preceding step. The same web client ID must be in both clientIds and audiences.

The following sample snippet shows how to supply client IDs for a javascript client, for an iOS client, and an Android client:

@Api(
    name = "tictactoe",
    version = "v1",
    scopes = {Constants.EMAIL_SCOPE},
    clientIds = {Constants.WEB_CLIENT_ID, Constants.ANDROID_CLIENT_ID, Constants.IOS_CLIENT_ID},
    audiences = {Constants.ANDROID_AUDIENCE}
)

public class Constants {
  public static final String WEB_CLIENT_ID = "1-web-apps.apps.googleusercontent.com";
  public static final String ANDROID_CLIENT_ID = "2-android-apps.googleusercontent.com";
  public static final String IOS_CLIENT_ID = "3-ios-apps.googleusercontent.com";
  public static final String ANDROID_AUDIENCE = WEB_CLIENT_ID;

  public static final String EMAIL_SCOPE = "https://www.googleapis.com/auth/userinfo.email";
}

In the snippet, note the use of a class to map constants to the actual client ID values so you need only make changes in one place whenever you change the client IDs. Notice also that audiences is set to the web client ID value.

Adding a user parameter to methods for auth

When you declare a parameter of type User in your API method, the API backend framework automatically authenticates the user and enforces the authorized clientIds whitelist, ultimately by supplying the valid User or not. If the request from the app has a valid auth token or is in the list of authorized clientIDs, the framework supplies a valid User to the parameter. If the incoming request does not have a valid auth token or if the client is not on the clientIDs whitelist, the framework sets the User parameter to null. Your own code must handle the null case and the non-null case, as shown below.

To add a User param to your method

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

    import com.google.appengine.api.users.User;
    
  2. Add a parameter of type User to each class method you wish to require authorization for, as shown in the following snippet: Score.insert() method:

    /**
     * Provides the ability to insert a new Score entity.
     */
    @ApiMethod(name = "scores.insert")
    public Score insert(Score score, User user) throws OAuthRequestException, IOException {
      ...
    }
    

If an incoming client request has no authorization token or an invalid one, user is null. In your code, you need to check whether user is null and do ONE of the following, depending on the condition:

  • If the user is present, perform the authorized action.
  • If the user is null, throw an OAuthRequestException.
  • Alternatively, if the user is null, perform some action for an unauthorized client access if some sort of unauthorized access is desired.

Providing authorization from clients

If your API backend requires authorization, you need to also support this 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 annotation attribute. 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.

Creating a web client ID

Client IDs are automatically created when you register an application in the Google Developers Console.

To register a new application, do the following:

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one.
  3. In the sidebar on the left, select APIs & auth. In the list of APIs, make sure all of the APIs you are using show a status of ON.
  4. In the sidebar on the left, select Registered apps.
  5. At the top of the page, select Register App.
  6. Fill out the form and select Register.

To find your project's client ID and client secret, do the following:

  1. Go to the Google Developers Console.
  2. Select a project.
  3. In the sidebar on the left, select APIs & auth. In the list of APIs, make sure all of the APIs you are using show a status of ON.
  4. In the sidebar on the left, select Credentials.
  5. Find the correct set of OAuth 2.0 credentials in the list, and then find the Client ID and Client secret for those credentials. Note that your project might list different credentials for web applications, service accounts, Compute Engine and App Engine, and several types of installed applications (Android, Chrome, iOS, other). Some types of credentials may have a client ID without a client secret, and you can create additional credentials by selecting Create New Client ID.

Creating an Android client ID

In order to create the Android client ID, you'll need to have the SHA1 fingerprint of the key you are using. If you use Eclipse with the Android Developer Tools (ADT) plugin, a debug keystore and a debug key is created automatically. You can use the debug key for testing purposes. (You must use a release key for your release version!) These instructions assume you are using the debug key.

The default debug keystore password is android, and the key alias is androiddebugkey. The default location for Linux and Mac OSX 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 OSX terminal window, you can get the SHA1 fingerprint of the debug key using the keytool (included with the Java SDK) and OpenSSL as follows:
    keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1
    When prompted for a keystore password, for debug, enter the value android.
  3. Copy the SHA fingerprint key that is displayed after your run the above keytool command. You'll need to supply this when you generate the Android client ID in the console.
  4. Open the Google Developers Console.
  5. When your project appears in the projects pulldown menu, select it to make it the active project.
  6. Click APIs and Auth and select Registered Apps.
  7. If your app is not yet registered, click Register App.
  8. For Application type, select Android and Accessing APIs directly from Android.
  9. In the textbox labeled Package name enter your Android application package name.
  10. In the textbox labeled SHA1 certificate fingerprint, enter the SHA1 fingerprint you obtained above.
  11. Click Register.
  12. Select OAuth 2.0 Client ID. The Client ID is listed on this screen.

Creating an iOS client ID

  1. Open the Google Developers Console.
  2. When your project appears in the projects pulldown menu, select it to make it the active project.
  3. Click APIs and Auth and select Registered Apps.
  4. If your app is not yet registered, select the Register App button.
  5. For Application type, select iOS and Accessing APIs directly from iOS.
  6. In the textbox labeled Bundle ID enter your application’s bundle identifier as listed in your application's .plist file (e.g. com.example.myapp).
  7. In the textbox labeled App Store ID, enter the App Store ID if the app was published in the Apple iTunes® App Store.
  8. Click Register.
  9. Select OAuth 2.0 Client ID. The Client ID is listed on this screen.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.