Using JWT for API Authentication

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

Webex Connect allows you to use JWT tokens for API authentication as an alternative in addition to the 'Service Key' based authentication.

A JWT is composed of a header, a payload, and a signature. The payload contains information called claims which describe the subject to whom the token was issued.

Here's a quick sample:

Header

alg - A string used in the header, identifying the algorithm used to encode the payload. The alg value is always HS256.

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

iss - A claim that is a string identifying the principal that issued the JWT. This value is always the Service ID (this is available on the API tab within a Service in Webex Connect when you select JWT Token as the Auth Type) when exchanging messages.

iat - A claim that is a numeric date—that is, an integer—identifying the time at which the JWT was issued. The value is the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date and time, ignoring leap seconds. For more information, see the Terminology section in RFC 7519.

{
  "iss": "<SERVICE ID available on the API tab within a Service in Webex Connect when you select JWT Token as the Auth Type >",
  "iat": 1516239022
}

Verify Signature

Decode the base64 encoded 'SERVICE SECRET' which is accessible within the API tab when you select JWT Auth type and use it to generate the signed bearer token (that is to be passed to Webex Connect for API authentication as a header parameter) using the HS256 algorithm.

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  <Decode the base64 encoded SERVICE SECRET and use it here>
)

🚧

JWT Tokens Expiry

• Token Expiry: The JWT token expires after 60 minutes from the time that you have generated the token.
• Token Regeneration: Please note that JSON Web Tokens generated using above approach have limited expiry time. You will need to implement the business logic for regeneration of JWTs in your system/application if you want to use it.

A decoded JWT token should contain the following:

header
{
  "alg": HS256,
}
claims
{
  "iss": <Service ID>,
  "iat": <issued at unix-timestamp (in seconds)>
}