Authenticating Users

This page describes how to add support in your API for user authentication from client applications using Google Cloud Endpoints Frameworks. Note that Android and Javascript clients are currently supported.

Cloud Endpoints Frameworks supports user authentication from client apps that use any of the following methodologies:

No matter which authentication method you use, in each API method where you want to check for proper authentication, you must check for a valid User as described in the following sections:

Before you begin

  1. Enable billing for your project.

    Enable billing

  2. Add Cloud Endpoints API management to your API in Python or Java.
  3. If you use JWT in your client to send authenticated requests to the API, the JWT must be in the authorization header of a HTTP request. The JWT should have the following required claims:
    • iss
    • sub
    • aud
    • iat
    • exp
  4. If you are using Google Accounts authentication, obtain an OAuth 2 client ID for each client app. The client app owner must generate the client ID from the Google Cloud Platform Console. For instructions, see Creating OAuth 2.0 Client IDs

Authenticating with Firebase Auth

To support Firebase Auth in your API using Cloud Endpoints Frameworks, follow the instructions in the tab for your language:

Python

To support calls from clients that use Firebase Auth:

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

    import endpoints
    
  2. Add a Firebase issuer object for each client to the API decorator. For example:

    @endpoints.api(
        name='echo',
        version='v1',
        issuers={'firebase': endpoints.Issuer(
            'https://securetoken.google.com/YOUR-PROJECT-ID',
            'https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com')})
    

    Replace YOUR-PROJECT-ID with the Google Cloud Platform project ID of the client, replace echo with the name of your API, and replace v1 with your API version.

  3. In each API method where you want to check for proper authentication, check for a valid User and raise error 401 if there isn't one, as shown in this sample method definition:

    user = endpoints.get_current_user()
    # If there's no user defined, the request was unauthenticated, so we
    # raise 401 Unauthorized.
    
  4. Deploy the API. You need to redeploy the API whenever you add new clients.

Java

To support calls from clients that use Firebase Auth:

  1. Add the following to your @Api or method annotation:

    • Add an authenticators param to your annotation, set to the value {EspAuthenticator.class}.
    • Add an issuers param containing an @ApiIssuer set to Firebase.
    • Add an issuerAudiences param containing an @ApiIssuerAudienceAPI set to Firebase and your project ID.

    For example:

    @Api(
        name = "echo",
        version = "v1",
        authenticators = {EspAuthenticator.class},
        issuers = {
            @ApiIssuer(
                name = "firebase",
                issuer = "https://securetoken.google.com/YOUR-PROJECT-ID",
                jwksUri = "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com")
        },
        issuerAudiences = {
            @ApiIssuerAudience(name = "firebase", audiences = "YOUR-PROJECT-ID")
        })
    

    Replace YOUR-PROJECT-ID with the client's Google Cloud Platform project ID, replace echo with the name of your API, and replace v1 with your API version.

  2. In your API implementation code, import Users:

    import com.google.api.server.spi.auth.common.User;
    
  3. In each API method where you want to check for proper authentication, check for a valid User and throw an exception if there isn't one, as shown in this sample method definition:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  4. Deploy the API. You need to redeploy the API whenever you add new clients.

Adding Firebase authentication to a client

You can add Firebase authentication to your code as described in the Firebase documentation. The client must have a Google Cloud Platform project associated with it, and the project ID must be listed in the API's Firebase issuer configuration as shown in the above tabs.

Authenticating with Auth0

To support Auth0 in your API using Cloud Endpoints Frameworks, follow the instructions in the tab for your language:

Python

To support calls from clients that use Auth0:

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

    import endpoints
    
  2. Add an Auth0 issuer object for each client to the API decorator. For example:

    @endpoints.api(
        name='echo',
        version='v1',
        issuers={'auth0': endpoints.Issuer(
            'https://YOUR-ACCOUNT-NAME.auth0.com',
            'https://YOUR-ACCOUNT-NAME.auth0.com/.well-known/jwks.json')})
    

    Replace YOUR-ACCOUNT-NAME with the Auth0 account name used for the client, replace echo with the name of your API, and replace v1 with your API version.

  3. In each API method where you want to check for proper authentication, check for a valid User and raise error 401 if there isn't one, as shown in this sample method definition:

    user = endpoints.get_current_user()
    # If there's no user defined, the request was unauthenticated, so we
    # raise 401 Unauthorized.
    
  4. Deploy the API. You need to redeploy the API whenever you add new clients.

Java

To support calls from clients that use Auth0:

  1. Add the following to your @Api or method annotation:

    • Add an authenticators param to your annotation, set to the value {EspAuthenticator.class}.
    • Add an issuers param containing an @ApiIssuer set to Auth0.
    • Add an issuerAudiences param containing an @ApiIssuerAudienceAPI set to Auth0 and your Auth0 client ID.

    For example:

    @Api(
        name = "echo",
        version = "v1",
        authenticators = {EspAuthenticator.class},
        issuers = {
            @ApiIssuer(
                name = "auth0",
                issuer = "https://YOUR-ACCOUNT-NAME.auth0.com/",
                jwksUri = "https://YOUR-ACCOUNT-NAME.auth0.com/.well-known/jwks.json")
         },
         issuerAudiences = {
             @ApiIssuerAudience(name = "auth0", audiences = "AUTH0-CLIENT-ID")
        })
    

    Replace YOUR-ACCOUNT-NAME with the Auth0 account name used for the client, replace AUTH0-CLIENT-ID with the ID you want to use for your client, replace echo with the name of your API, and replace v1 with your API version.

  2. In your API implementation code, import Users:

    import com.google.api.server.spi.auth.common.User;
    
  3. In each API method where you want to check for proper authentication, check for a valid User and throw an exception if there isn't one, as shown in this sample method definition:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  4. Deploy the API. You need to redeploy the API whenever you add new clients.

Adding Auth0 authentication to a client

You can add Auth0 authentication to your code as described in the Auth0 documentation. The client must be listed in the API's Auth0 issuer configuration as shown in the above tabs.

Authenticating with Google Accounts

To support authentication with Google Accounts in your API using Cloud Endpoints Frameworks, follow the instructions in the tab for your language:

Python

To support calls from clients that authenticate using Google Accounts:

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

    import endpoints
    
  2. Specify all of the client IDs you want to grant access to your API in the allowed_client_ids, and also specify client IDs belonging to Android clients in theaudiences field in the API decorator. For example:

     @endpoints.api(
         name='authed_greeting',
         version='v1',
         allowed_client_ids=ALLOWED_CLIENT_IDS,
         audiences=[ANDROID_AUDIENCE])
     class AuthedGreetingApi(remote.Service):
         # ...
    

    Replace ALLOWED_CLIENT_IDS with the list of OAuth 2 client IDs generated from each client's Google Cloud Platform Console project, and replace ANDROID_AUDIENCE with the list of Android web client IDs. The web client ID is the client ID with .apps.googleusercontent.com appended, for example:YOUR-CLIENT-ID.apps.googleusercontent.com.

  3. In each API method where you want to check for proper authentication, check for a valid User and raise error 401 if there isn't one, as shown in this sample method definition:

    user = endpoints.get_current_user()
    # If there's no user defined, the request was unauthenticated, so we
    # raise 401 Unauthorized.
    
  4. Deploy the API. You need to redeploy the API whenever you add new clients.

Java

To support calls from clients that use Firebase Auth:

  1. Add a clientIds entry containing the client ID for each client app you are granting access to, and an audiences entry as well for each Android client, in your @Api annotation. For example:

    @Api(
       name = "echo",
       version = "v1",
       clientIds = {"YOUR-CLIENT-ID"}
       audience = {"YOUR-CLIENT-ID.apps.googleusercontent.com"}
    )
    

    Replace YOUR-CLIENT-ID with the OAuth 2 client ID that was generated in the client app project. Replace echo with your API name, and v1 with your API version.

  2. In your API implementation code, import Users:

    import com.google.api.server.spi.auth.common.User;
    
  3. In each API method where you want to check for proper authentication, check for a valid User and throw an exception if there isn't one, as shown in this sample method definition:

    @ApiMethod(httpMethod = ApiMethod.HttpMethod.GET)
    public Email getUserEmail(User user) throws UnauthorizedException {
      if (user == null) {
        throw new UnauthorizedException("Invalid credentials");
      }
    
      Email response = new Email();
      response.setEmail(user.getEmail());
      return response;
    }
    
  4. Deploy the API. You need to redeploy the API whenever you add new clients.

Adding Google Accounts authentication to a client

For information on adding authentication code to clients using Google Accounts, see the documentation appropriate to your language and client authentication library (OAuth 2 or JWT):

Further reading

For background information about user authentication and how it differs from API key authorization, see When and Why to use API Keys.

Send feedback about...

Cloud Endpoints Frameworks for App Engine