MyTime's JWT authentication is meant for the marketplace API. It is used by our merchants to auto-provision and authenticate users who are logged in to an external (to MyTime) authentication platform. This authentication provider is responsible for generating JSON Web Tokens. If the web token is validated by MyTime as having originated from the merchant (ie if the signature is verified), we give access to the corresponding user account's data.

User accounts not seen before by MyTime will be automatically provisioned during initial authentication. These user accounts are logically separated from user accounts used across other MyTime merchants in our multi-tenant infrastructure.

Configuration

A MyTime engineer can configure JWT authentication by creating a JwtConfiguration object. This object is not accessible via any API, but holds details of what the algorithm expected is and any keys required for signature verification, the nature of which depends on the algorithm.

Alternatively, a JSON API endpoint may be provided that returns a JWK Set, eg here is an example payload: https://tools.ietf.org/html/rfc7517#appendix-A.1

The list of supported algorithms is thus:

• HS256

• HS384

• HS512

• RS256

• RS384

• RS512

• ES256

• ES384

• ES512

Token Specification

Header

The "kid" header, ie the key id header, is required and refers to the primary key for the JwtConfiguration object which a MyTime engineer sets up during configuration.

Alternatively, if a JWK Set endpoint is being used, both "iss" and "kid" are required. The "iss" must be unique across all of MyTime's customers, whereas the kid is specified by the merchant via the JWK Set endpoint.

Payload

The payload must be a JSON object with the following structure:

{

  "id": "Required: unique/stable string primary key",

}

Example of encoding a token

Ruby (using the ruby-jwt gem):

header = {kid: 1, iss: 'issuer_name'}

payload = {id: 'test123'}

algorithm = 'RS256'

rsa_private = OpenSSL::PKey::RSA.generate(2048)

token = JWT.encode(payload, rsa_private, algorithm, header)

# decoding to validate token

rsa_public = rsa_private.rsa_public

decoded_token = JWT.decode(token, rsa_public, true, {algorithm: algorithm})

Usage

There are two ways to authenticate requests to MyTime's APIs using JWT:

1. Using a query string parameter named "jwt". eg: /api/endpoint?jwt=abc.123.xyz

2. With the "Authorization" HTTP header, using the Bearer scheme, eg: Authorization: Bearer abc.123.xyz