JWT

What is a JWT?

JSON Web Token (JWT) is an open standard that defines a compact and self-contained way for sharing information between parties as a JSON object. You can read more about how JWT's work at JWT.io. These are commonly used for authorisation in web APIs.

Host Building has a custom implementation for passing user data to a third party via webview link. It has a customisable expiry, and contains a configurable subset of the user's information (name, email etc), their building and tenancy details. The token is signed using an ES265/Elliptic curve digital signature which can be verified as issued by Host.

The token is not encrypted and can be read by any consumer but the signature should be verified before trusting the payload (see Retrieving the public certificate)

Getting setup

Contact Host Building to have the JWT configured on a webview. You will need to provide:

• The URL to open
• The JWT time-to-live
• The JWT URL parameter
• The scopes to send (see below)

Token specification

The token follows the RFC-7519 standard and implements the standard structure for:

Header

• typ (type, always ‘JWT’)
• alg (algorithm, ES256 implemented)
• kid (key id, effectively the signing key version) Host Building provides a public endpoint to retrieve the public key for signature verification, the appropriate key can be retrieved using the kid (key id)

Standard payload claims

• iat (issued at)
• exp (expires)
• iss (issuer), this will be the Host Building environment. e.g. india.host-building.com

Optional claims for

Type	Key	Desc
	id	User id
	name	Full name
	email	Email address
	mobile	Mobile
User Building
	building	Building name
	building_id	Building id
	building_address	Building address
	building_location	Building location (lat, long)
User Tenancy
	tenant	Tenancy name
	tenant_id	Tenancy id
Branding
	branding.color_primary	Primary color
	branding.color_secondary	Secondary color

Once configured the token will be appended to the link and a third party can verify the token as being issued by host and trust that the user matches the provided details. The parameter the token is appended as, the expiry and claims are configurable.

Example token

The following is an example an (expired) token and the optional claims that can be configured: https://jwt.io/#debugger-io?token=eyJ0eXAiOiJKV1QiLCJ...

{ // Headers
  "typ": "JWT",
  "alg": "ES256",
  "kid": "14.1"
}
{ // Claims
  "iat": 1636346255,
  "id": "44009",
  "name": "Dave Lang",
  "email": "dave.lang1@cbre.com",
  "mobile": "0450050035",
  "building_id": "152",
  "building": "Host",
  "building_address": "1 Eagle Street, Brisbane, QLD, 4000, Australia",
  "building_location": "-27.470323689138915, 153.03043397802065",
  "tenant": "CBRE",
  "tenant_id": "822",
  "branding": {
     "color_primary": "#fff000",
     "color_secondary": "#fff000"
  },
  "exp": 1636346315,
  "iss": "test.host-building.com"
}

Retrieving the public certificate

caution

It is important to implement the key verification to ensure that only Host Building tokens are accepted.

To determine your endpoint for retreiving the key:

1. Take the iss claim from the token, ensure this is a *.host-building.com domain
2. Append /app/public.php?action=public:jwt-token to the URL
3. Get the c & v values by splitting the kid header (see below)
4. Append these values &c=14&v=1 to the URL
5. You should end up with a URL like http://test.host-building.com/app/public.php?action=public:jwt-token&c=14&v=1

Determining key version

The parameters can be retrieved from the kid (key id) header of the token. This will have the format client.version, e.g. 14.1 which is client 14 (c=14) and key version 1 (v=1). The endpoint will return the current and previous key so tokens can be verified after the key has been rolled over but before the token expires.

Depending on the library used, you will need to ensure the key is decoded correctly. E.g. Unescaping new lines

Example response:

{
   "current": {
      "key": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE0WOoe0wKUtaj7viSuycW7eQpJ/LF\nce4PNhE9ErMWT1WEedjpc2UDjZ0KA+SHMvBWkuE9VOZl15Pu3Ww6EqsjSA==\n-----END PUBLIC KEY-----",
      "version": 1
   },
   "last": null
}

JWT Flow

In many cases the JWT library being used will handle the decoding and expiry checks, however the steps to retrieve the public key and handle the token parameter will need to be implemented.

All app user interaction is via the Host app, third party content will be loaded within a webview.

More information

See Webviews for information on webview limitations and allowed usage.