JWTs

Passage uses JSON Web Tokens (JWTs) to prove the identity of users for your applications. A critical part of using Passage is ensuring that the JWTs created on behalf of your users are valid.

What is a JWT?

A JSON Web Token (JWT) (pronounced "jot") is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload and can be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. A JWT is represented as a sequence of URL-safe parts separated by period ('.') characters. Each part contains a base64url-encoded value.

The main benefits of JWTs are that they are easy to use and more secure than a shared secret. JWTs can use a private/public keypair for signing, which provides better security in the case of Passage, where users need to be able to retrieve the verification information from Passage. In the case of private/public key pairs, Passage can just share the public key and keep the private key protected.

JWTs can be used for authentication and authorization. A valid JWT containing a userID indicates that the user has successfully authenticated to the application. This token can also be used to perform access checks for that user to grant them access to specific application resources. JWTs are most commonly sent in HTTP headers.

Anatomy of a Passage JWT

An example Passage JWT is shown below:

// A header describing the algorithm and token type:
{
    "alg": "RS256",
    "typ": "JWT"
}.
// The payload/claims:
{
  "exp": 1623725098,
  "iss": "dk8fn3fns93kJD6Vdj1k",
  "sub": "kDqAfJcRExEXccEpEYNI"
}.
// The signature:
WUro5...FxA

Claim

Description

exp

Expiration – the time when the token is no longer valid. The session expiration time is configurable in the Passage Console.

iss

Issuer – the ID of the Passage App that issued the auth token.

sub

Subject – the ID of the Passage User who was issued the auth token.

Verifying a JWT on Your Server

The easiest way to verify a Passage JWT on your web server is using one of the Passage backend libraries. For any language without a Passage backend library, there is likely a popular JWT library you can use. We've compiled a list of popular third-party JWT libraries below:

Last updated