User Verification Terms

JSON (JavaScript Object Notation)

What is it?

JSON is an open standard data format that uses a simple, human-readable syntax to store and transfer data. Even though it has “JavaScript” in the name, the format is language independent. The basic concept is an element that consists of a key, followed by a colon (:), followed by a value. You can create elements for strings, numbers, and boolean values. You can also create a comma-separated list of elements, or you can nest elements within elements by creating objects.

To learn more, see RFC 8259.

How do we use it for Enhanced Chat?

Our tokens and keys are stored using JSON.

Show me an example!

Here’s an example of some JSON.

{
  "name": "Carrie",
  "age": 135, 
  "isHappy": true,
  "favorite_colors": ["blue", "green", "yellow"],
  "catch_phrase": "I can’t believe I’m 135 years old!"
}

JSON Web Token (JWT, pronounced “jot”)

What is it?

A JWT is a compact, self-contained way to pass information between two parties. The data in a JWT is stored as a JSON object. It’s often digitally signed so that the recipient can verify the integrity of the data. A JWT is also typically encoded to ensure that it’s URL-safe when being passed.

A JWT consists of three parts: a header, a payload, and a signature. The header contains information about how the token is signed. The payload contains information about the user and other data. The signature contains the signed result of the header, the payload, and the secret. The signature doesn’t encrypt the data, the signature ensures that the data hasn’t been tampered with.

To learn more, see RFC 7519.

How do we use it for Enhanced Chat?

A JWT ensures that we display the right conversation history for the right user. After verifying that the token is valid, we use the subject of the token, the “sub” property, to identify the user and display their conversation history. The “sub” value in the JWT is stored as part of the Messaging Platform Key field of the Messaging End User record. For instance, if the “sub” value is user-123, the Messaging Platform Key might be v2/iamessage/AUTH/{auth_id_info}/uid:user-123.

Show me an example!

This JSON is a sample header.

{
  "kid": "123456",
  "typ": "JWT",
  "alg": "RS256"
}

This JSON is a sample payload.

{
  "sub": "user-123",
  "iss": "example.com",
  "exp": 1674164345,
  "iat": 1674158345
}

When a JWT is signed and encoded, it has this format.

hhhhhhh.ppppppp.sssssss

Where hhhhhhh represents the header, ppppppp represents the payload, and sssssss represents the signature.

This data is a sample encoded JWT.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

You can use a site like JWT.io to decode an encoded JWT.

Warning Don’t share production JWTs with other organizations and don’t paste production JWTs into sites or tools.

JSON Web Key (JWK) and JSON Web Key Set (JWKS)

What is it?

A JWK represents a public cryptographic key that can be used to verify the validity of a token (for user verification, this token is a JSON Web Token). A set of JWK keys is known as a JSON Web Key Set (JWKS).

To learn more, see RFC 7517.

How do we use it for Enhanced Chat?

We use a set of JSON Web Keys to verify the validity of the JSON Web Token (JWT). That way, we can ensure that an untampered token came from the correct source. We require a 2048-bit minimum RSA key length.

Show me an example!

{
  "kid":"123456",
  "alg":"RS256",
  "use":"sig",
  "kty":"RSA",
  "x5c":["<Your public certificate>"],
  "y":"y",
  "n":"<Base64-encoded modulus>",
  "e":"<Base64-encoded public exponent>",
  "crv":"crv",
  "d":"d",
  "k":"k"
}