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 Auth0, documentation.
-
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 ESP to support client authentication
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 Auth0 authentication:
Add the following to the security definition in your OpenAPI document:
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"
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: []
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.
The x-google-audiences
field isn't required. ESP
accepts all JWTs with the backend service name in the form of
https://SERVICE_NAME
in the aud
claim. To
allow additional client IDs to access the backend service, you can specify the
allowed client IDs in the x-google-audiences
field by using
comma-separated values. ESP then accepts the JWTs with any of the
specified client IDs in the aud
claim.
You may also customize JWT locations by adding x-google-extensions
. For details, see openAPI extensions.
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 usually forwards all headers it receives. However, it overrides the
original Authorization
header when the backend address is specified by
x-google-backend
in OpenAPI specification or BackendRule
in gRPC service configuration.
ESP will send the authentication result in the X-Endpoint-API-UserInfo
to the backend API. We recommend using this header instead of the original
Authorization
header. This header is a string that base64url
encodes
a JSON object. The JSON object format differs between ESPv2 and ESP.
For ESPv2, the JSON object is exactly the original JWT payload. For ESP,
the JSON object uses different field names and put original JWT payload under claims
field.
See Handle JWTs in the backend service
for more information on the format.
Samples
What's next