Using Firebase to authenticate users

This page describes how to support user authentication in Cloud Endpoints.

To authenticate a user, a client application must send a JSON Web Token (JWT) in the authorization header of the HTTP request to your backend API. The Extensible Service Proxy (ESP) 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 document to support your chosen authentication methods.

ESP validates a JWT in a performant way by using the JWT's issuer's public keys. ESP caches the public keys for five minutes. In addition, ESP caches validated JWTs for five minutes or until JWT expiry, whichever happens first.

Before you begin

  • Add authentication code to your client application, following the Firebase authentication, documentation. Firebase supports authentication by using passwords, phone numbers, and popular federated identity providers like Google, Facebook and Twitter.

  • When your client application sends an HTTP request, the authorization header in the request must contain the following JWT claims:
    • iss (issuer)
    • sub (subject)
    • aud (audience)
    • iat (issued at)
    • exp (expiration time)

Configuring your OpenAPI document

You must have a security requirement object and a security definitions object in your OpenAPI document for ESP to validate the claims in the signed JWT.

To support Firebase authentication:

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

      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"
          x-google-audiences: "YOUR-PROJECT-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: []
    

You can define multiple security definitions in the OpenAPI document, but each definition must have a different issuer. If you use security sections at both the API level and at the method level, the method-level settings override the API-level settings.

ESP supports two asymmetric public key formats defined by the x-google-jwks_uri OpenAPI extension:

  • JWK set format. For example:
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
    
  • X509. For example:
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
    

If you are using a symmetric key format, set x-google-jwks_uri to the URI of a file that contains the base64url-encoded key string.

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"

Here, ENDPOINTS_HOST and TOKEN are environment variables containing your API host name and authentication token, respectively. See Making an authenticated request to an Endpoints API. 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}"

Receiving authenticated results in your API

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

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

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI
Need help? Visit our support page.