Authenticating Users

This page describes how to support user authentication in Google Cloud Endpoints, in which a client application or a service sends an authenticated request to your backend API.

When a client application or a service using authentication sends a request to your backend API, the Extensible Service Proxy validates the token on behalf of your API, so you don't have to add any code in your API to process the authentication. However, you do need to configure your OpenAPI configuration file to support the authentication methods you want to support.

The Extensible Service Proxy validates a JSON Web Token (JWT) in a performant way using the JWT's issuer's public keys. The public keys are cached in proxy for five minutes. In addition, the successfully validated JWTs are cached in the proxy for five minutes or until JWT expiry, whichever happens first.

To authenticate a user, the authorization header of an incoming HTTP request should contain a JWT with required claims as listed below.

Before you begin

  • Add authentication code to your client application, following the documentation provided by the authentication method. Cloud Endpoints supports client-side authentication using a variety of authentication choices:

    • Firebase authentication, which is Google’s federated authentication supporting end user sign-in at the client app using third party credentials, for example, from Google or Facebook.
    • Auth0, as an alternative to Firebase authentication.
    • Google authentication allows users to authenticate by signing in with a Google account.
    • Custom authentication methods.
  • A JWT should be contained in the authorization header of a HTTP request. The JWT should have the following required claims:

    • iss (issuer)
    • sub (subject)
    • aud (audience)
    • iat (issued at)
    • exp (expiration time)

Configuring Extensible Service Proxy to support client authentication

You can define multiple security definitions in the OpenAPI configuration file, but each definition must have a different issuer.

The following tabs show how to set the server proxy for various types of authentication.

Firebase

To support Firebase authentication:

  1. Add the following to the security definition in your OpenAPI configuration file:

      securityDefinitions:
        firebase:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          # Replace YOUR-PROJECT-ID with your project ID
          x-google-issuer: "https://securetoken.google.com/YOUR-PROJECT-ID"
          x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
          # Optional. Replace YOUR-CLIENT-ID with your client ID
          x-google-audiences: "YOUR-CLIENT-ID"
    
  2. Add a security section at either the API level to apply to the entire API, or at the method level to apply to a specific method.

      security:
        - firebase: []
    

    Notice that if you use security sections at both the API level and at the method level, the method-level settings override the API-level settings.

Auth0

To support Auth0 authentication:

  1. Add the following to the security definition in your OpenAPI configuration file:

      securityDefinitions:
        auth0_jwk:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          # Replace YOUR-ACCOUNT-NAME with your Auth0 account name.
          x-google-issuer: "https://YOUR-ACCOUNT-NAME.auth0.com/"
          x-google-jwks_uri: "https://YOUR-ACCOUNT-NAME.auth0.com/.well-known/jwks.json"
          # Optional. Replace YOUR-CLIENT-ID with your client ID
          x-google-audiences: "YOUR-CLIENT-ID"
    
  2. Add a security section at either the API level to apply to the entire API, or at the method level to apply to a specific method.

      security:
        - auth0_jwk: []
    

    Notice that if you use security sections at both the API level and at the method level, the method-level settings override the API-level settings.

Google

To support Google authentication:

  1. Add the following to the security definition in your OpenAPI configuration file:

      securityDefinitions:
        google_id_token:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          x-google-issuer: "https://accounts.google.com"
          x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
          # Optional. Replace YOUR-CLIENT-ID with your client ID
          x-google-audiences: "YOUR-CLIENT-ID"
    
  2. Add a security section at either the API level to apply to the entire API, or at the method level to apply to a specific method.

      security:
        - google_id_token: []
    

    Notice that if you use security sections at both the API level and at the method level, the method-level settings override the API-level settings.

Custom

To support custom authentication:

  1. Add the following to the security definition in your OpenAPI configuration file:

      securityDefinitions:
        your_custom_auth_id:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          # The value below should be unique
          x-google-issuer: "issuer of the token"
          x-google-jwks_uri: "url to the public key"
          # Optional. Replace YOUR-CLIENT-ID with your client ID
          x-google-audiences: "YOUR-CLIENT-ID"
    
  2. Add a security section at either the API level to apply to the entire API, or at the method level to apply to a specific method.

      security:
        - your_custom_auth_id: []
    

    Notice that if you use security sections at both the API level and at the method level, the method-level settings override the API-level settings.

The Extensible Service Proxy supports two asymmetric public key formats defined by the x-google-jwks_uri OpenAPI extension:

If you are using a symmetric key format, set x-google-jwks_uri to the base64 encoded key string.

Examples of public key format are available in the Auth0 and Firebase samples. The Auth0 sample uses the JWK set format while the Firebase sample uses the X509 format. See the Further Reading section below for a list of samples.

Note that x-google-audiences is not required. If it is not specified, the Extensible Service Proxy accepts JWTs that have the backend service name in the form of https://SERVICE_NAME in aud claim. You can specify x-google-audiences if you want to whitelist certain client IDs that are allowed to access the backend service, in which case, the JWT aud claim should match one of the client IDs whitelisted in x-google-audiences.

Making an authenticated call to an Endpoints API

When you send a request using an authentication token, for security reasons, we recommend that you put the token in the Authorization:Bearer header. For example:

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

where ENDPOINTS_HOST and TOKEN are environment variables containing your API host name and authentication token, respectively. See the last step of Using a JWT signed only by the service account and Using a Google ID token for sample code that sends a request using the Authorization:Bearer header.

If you cannot use the header when sending the request, you can put the authentication token in a query parameter called access_token. For example:

curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Service to service authentication

For information on service to service authentication, see Service-to-Service Authentication.

Receiving auth results in your API

Endpoints forwards all headers it receives, including the original Authorization header, to the API. In addition, Endpoints sends the authentication result in X-Endpoint-API-UserInfo header to the API. This header is base64 encoded and contains following JSON object.

{
  "issuer": TOKEN_ISSUER,     // optional
  "id": USER_ID,              // optional
  "email" : USER_EMAIL        // optional
}

For examples on how to process these headers, see the samples listed below.

Further reading

For background information about Api keys and how they differ from user authentication, see When and Why to use Api Keys.

For examples that show how to send tokens and required asserts in a security header in an API request from clients, and process user information from authentication in your API, see the Cloud Endpoints samples for:

Send feedback about...

Cloud Endpoints with OpenAPI