Verifying user identity via JWTs

Like many identity systems, Passport issues signed JSON Web Tokens (JWTs) as user credentials.

Once a user successfully authenticates in your application, Passport will issue an ID token and access token:

View on GitHub

const idToken = await passportInstance.getIdToken();

View on GitHub

const accessToken = await passportInstance.getAccessToken();

Token type	Description
Access Token	Access tokens are internally used by the SDK to perform actions on the Immutable X API on behalf of the user. Most applications won't use this explicitly.
ID Token	ID tokens identify Passport users.

Validating JWTs

If you are using Passport's ID tokens to identify users in your backend, simply base64 decoding a token and reading the sub claim is not sufficient to guarantee that the user is who they claim they are.

JWTs must be cryptographically verified by using the issuer’s (Immutable) public key which ensures that the token was in fact signed with Immutable’s private key. Passport uses the RS256 algorithm to sign the tokens.

info

Note: The getAccessToken & getIdToken methods will attempt to refresh the tokens if they have expired. For this reason, it is recommended to call these methods when you need the tokens, rather than storing them in your application.

How to validate JWTs?

If you are using Passport's ID tokens to identify users in your backend, simply base64 decoding a token and reading the sub claim is not sufficient to guarantee that the user is who they claim they are.

JWTs can be cryptographically verified by using the issuer’s (Immutable) public key which ensures that the token was in fact signed with Immutable’s private key. Passport uses the RS256 algorithm to sign the tokens.

You can fetch the JSON web key set containing the public key using the jwks_uri endpoint and use a trusted open-source JWT verification library to verify the tokens. You may choose to cache the public key in your application for performance reasons, but we don't recommend caching it for longer than 1 hour, as the signing keys may be rotated from time to time.

JWKs URIs

JSON Web Keys (JWKs) are a standardized format for representing cryptographic keys in JSON format, used to verify any JSON Web Token (JWT) issued by the Authorization Server and signed using the RS256 signing algorithm. Immutable's JWKs URIs are as follows:

Environment	URI
Production	https://auth.immutable.com/.well-known/jwks.json
Sandbox	https://auth.immutable.com/.well-known/jwks.json

Decoding JWTs

A decoded ID token will have the following structure:

interface IDToken {
    "iss": string // Issuer domain:   
    "aud": string // Your Passport client ID  
    "iat": number, // UNIX timestamp when the token was issued  
    "exp": number, // UNIX timestamp when the token expires
    "sub": string, // User identifier  
    "sid": string // Session identifier  
}

The sub attribute will uniquely identify the Passport user.