Token Service

Context

The token service Cloud Function is triggered by an HTTP request and generates a JSON Web Token (JWT) for the caller. The JWT can then be used as a bearer token to authenticate to the QuantaCorp API. See ADR ADR-0015 Token Service for QuantaCorp API for motivation and background.

Input

This function requires no input; the caller identity is determined from the bearer token, which must be a Firebase id token issued by the same project in which the Cloud Function is configured.

Invocation

The token service Cloud Function implements the https.onCall protocol supported by the Firebase client SDKs.

The client SDK will take care of authentication and error handling. See TokenServiceDisplay.jsx for an example of calling this using the Firebase Javascript SDK.

Output

On successful invocation, the function returns HTTP status 200 and a JSON payload with a signed JWT; for example:

{"result": {"Token": "XXX.YYY.ZZZ"}}

If an error occurs and the function is unable to complete the request, the function will return an HTTP error status and a JSON payload that contains an error key rather than result. For example, if a request is made with no bearer token, the HTTP status will be 401 and response payload:

{"error": {"status": "UNAUTHENTICATED", "message": "Missing bearer token"}}

See the protocol specification for more details. If you are using one of the Firebase SDKs, the library will take care of deserializing the result or throwing an error.

Validating a token

If you are implementing an API that uses bearer authentication, it is the responsibility of your API to verify the bearer token. A JWT consists of three parts: header, payload, and signature. You must verify both the algorithm in the header and the signature before trusting any claims in the payload. The algorithm should be RS256 (RSA Signature with SHA-256) which requires a public key for verification. You can download the public key for the eTryOn token service here.

JWT Libraries exist for most languages. See JWT Libraries to find a library for your chosen language.

After verifying a token, you will find the Firebase user id in the sub (subject) field.

Source code

See token-service.

Deployment

This function can be deployed to a Firebase project using the token-service Terraform module.