This page describes how to add support in your API for user authentication from client applications using Cloud Endpoints Frameworks. Note that Android and JavaScript clients are currently supported.
Endpoints Frameworks supports user authentication from client applications 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:
Prerequisites
This page assumes that you have already:
Created a Google Cloud project.
Authenticating with Firebase Auth
To support calls from clients that use Firebase Auth:
If you haven't already done so, create a Firebase project. Firebase projects are Google Cloud console projects that use Firebase services. For more information, see What is a Firebase project? and the Firebase documentation.
Add the following to your
@Api
or method annotation:- Add an
authenticators
parameter to your annotation, set to the value{EspAuthenticator.class}
. - Add an
issuers
parameter containing an@ApiIssuer
set to Firebase. - Add an
issuerAudiences
parameter containing an@ApiIssuerAudience
set to Firebase and your project ID.
For example:
@Api( name = "YOUR_API_NAME", version = "VERSION_NUMBER", 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_API_NAME
with the name of your API. - Replace
VERSION_NUMBER
with your API version, for example,v1
. - Replace both instances of
YOUR_PROJECT_ID
with your Firebase project ID.
- Add an
In your API implementation code, import
Users
:import com.google.api.server.spi.auth.common.User;
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; }
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 project associated with it, and the project ID must be listed in the API's Firebase issuer configuration as shown in the preceding section.
Authenticating with Auth0
To support calls from clients that use Auth0:
Add the following to your
@Api
or method annotation:- Add an
authenticators
parameter to your annotation, set to the value{EspAuthenticator.class}
. - Add an
issuers
parameter containing an@ApiIssuer
set to Auth0. - Add an
issuerAudiences
parameter containing an@ApiIssuerAudience
set to Auth0 and your Auth0 client ID.
For example:
@Api( name = "YOUR_API_NAME", version = "VERSION_NUMBER", 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_API_NAME
with the name of your API. - Replace
VERSION_NUMBER
with your API version, for example,v1
. - 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.
- Add an
In your API implementation code, import
Users
:import com.google.api.server.spi.auth.common.User;
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; }
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.
Authenticating with Google ID tokens
To support calls from clients that authenticate using Google ID tokens:
Obtain an OAuth 2 client ID for each client application. The client application owner must generate the client ID from the Google Cloud console. For instructions, see Creating client IDs.
Add a
clientIds
entry containing the client ID for each client app you are granting access to, and anaudiences
entry as well for each Android client, in your@Api
annotation.For example:
@Api( name = "YOUR_API_NAME", version = "VERSION_NUMBER", clientIds = {"YOUR_CLIENT_ID"}, audiences = {"YOUR_CLIENT_ID"} )
- Replace
YOUR_API_NAME
with the name of your API. - Replace
VERSION_NUMBER
with your API version, for example,v1
. - Replace
YOUR_CLIENT_ID
with the OAuth 2 client ID that was generated in the client application project.
- Replace
In your API implementation code, import
Users
:import com.google.api.server.spi.auth.common.User;
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; }
Redeploy the API whenever you add new clients.
Adding Google ID tokens authentication to a client
For information on adding authentication code to clients, see the following:
Sending a JWT in your client
If you use a 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
What's next
For background information about user authentication and how it differs from API key authorization, see When and why to use API keys.