Overview

Connect uses JSON Web Token (JWT) as an open and industry standard way to represent data to be securely transferred between two parties. The following is a small overview to help you understand what JWTs are, when we use them, and how to manipulate them.

What is a JWT?

A JWT is a JSON object encoded into a secure string using your client_secret. Each key-value pair present in a JWT is called a claim.

Example

If you receive the following encoded JWT:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NjcxNjg2NzAsImlzcyI6ImNvbm5lY3QucHJvdmlkZXIuaW5zdGFuY2UiLCJzdWIiOiI0YWM0ZWZmOC1iYzcxLTQ5OTQtOTZjNS01M2E5YzEwZGE2MjEifQ.Mc3l8q0baT0zoVQBM4OtSaAD9kAHWa99TKIx8xHjSg4

And your client_secret is:

5nFSe2fnp5Gk4pKFHtDqFyLidgdR58aPqYYcR62V5s8=

After verifying and decoding the JWT with your client_secret you will get the following JSON object:

{
  "exp": 1567168670,
  "iss": "[providerFQDN]",
  "sub": "4ac4eff8-bc71-4994-96c5-53a9c10da621"
}

Disclaimer

Warning
 JWT manipulation uses complex cryptographic concepts and should not be done by hand. You should look for a popular, well reviewed and safe library to handle this in your favorite programming language.

Connect JWT Use Cases

Access Tokens

The access_tokens generated in our authentication flows are JWT with the following claims:

  • exp: A UNIX timestamps of the Token’s expiration time

  • iss: [providerFQDN] The domain of the issuer of the token

  • sub: The unique identifier of the User on Connect

Authorization Code Flow

The access_token provided at the end of an Authorization Code Flow:

Token Exchange Flow

The access_token provided at the end of a Token Exchange Flow:

  • contains all the previously described claims

  • contains an additionnal act claim

  • is signed using the client_secret of the Application that exposes the data

The act claim is there to represent the Application that requested the Token. The reference to this Application is associated to a sub key, nested inside a JSON object.

ID Tokens

An ID Token is a JWT that your Application will receive at the end of an Authorization Code Flow, if you requested the openid scope. ID Tokens contain additional claims about the User depending on the additional openid scopes that you requested.

Connect currently supports the email and phone scopes. They must be requested along with the openid scope so that the id_token contains the following claims:

  • email: the email of the authenticated User

  • email_verified: a boolean representing whether the User’s email has been verified

  • phone_number: the phone number of the authenticated User

  • phone_number_verified: a boolean representing whether the User’s phone number has been verified

Table of Content