Skip to main content

JWT verification

Pomerium's JavaScript SDK provides a client-side solution to verify JWTs issued by the authorization service.

Requirements to use the JavaScript SDK​

The JavaScript SDK is available as an NPM package and can be imported using CommonJS or ECMAScript modules.

To use the JavaScript SDK, you need:

  • Node.js (version 18+)
  • NPM (to install Node.js and Yarn)
  • Yarn (preferred package manager)

Basic usage​

The following code provides a minimum working example of how JWT verification works using the JavaScript SDK in a React app:

import { useEffect, useState } from 'react';
import { PomeriumVerifier, signOut } from '@pomerium/js-sdk';

function App() {

  const [jwt, setJwt ] = useState('');

  useEffect(() => {
    const jwtVerifier = new PomeriumVerifier({
      issuer: 'authenticate.localhost.pomerium.io:4443',
      audience: 'react.localhost.pomerium.io',
      expirationBuffer: 1000
    });
    jwtVerifier.verifyBrowserUser()
      .then(r => setJwt(r))
      .catch(e => console.log(e));
  }, [])

  return (
    <div style={{margin: '20px'}}>
      <pre>{JSON.stringify(jwt, null, 2)}</pre>
      <div style={{marginTop: '20px'}}>
        <button onClick={() => signOut('https://www.pomerium.io')} type="button">Sign Out Test</button>
      </div>
    </div>
  );
}

export default App;
tip

See the JavaScript SDK guide for more complete client- and server-side examples using React and Express.

Trust on first use (TOFU)

The issuer and audience parameters are optional. If you don’t define them, PomeriumVerifier applies firstUse by default to the JWT provided by the identity provider. PomeriumVerifier verifies subsequent requests with these claims.

If you define the issuer and audience parameters, PomeriumVerifier verifies their values against the claims provided by the identity provider.

The issuer is your authenticate service URL without the prefixed protocol (for example, authenticate.corp.example). The audience is the URL of the upstream application without the prefixed protocol (for example, httpbin.corp.example.com).

PomeriumVerifier reference​

The PomeriumVerifier class is the easiest way to verify JWTs. See the reference below for more information:

Parameters​

ParametersDescriptionValue
issuerThe URL of your authentication domain e.g. authenticate.corp.example.String
audienceThe client's final domain e.g. httpbin.corp.example.com.String
expirationBufferAdds padding in seconds to prevent throwing errors for expired JWTs that may have differing server times. Defaults to 0Integer
firstUseDecides whether or not to trust the first JWT.Boolean
jwtDataThe JSON payload containing JWT claims.Object
verifiedJwtDataThe verified JSON payload containing JWT claims.Object

Methods​

MethodDescription
getClientJwtFetches client JWT from the /.pomerium/jwt endpoint.
parseJWTDecodes JWT token.
getJWKsDataFetches JWKs data from the /.well-known/pomerium/jwks.json endpoint.
verifyPomeriumJWTVerifies JWT using the jwt, authenticateBaseUrl, issuer, and audience parameters.
withHttpsPrepends the URL with the https:// protocol.
signOutSigns user out and redirects them with the /.pomerium/sign_out endpoint.

Server-side JWT verification​

Pomerium also provides server-side solutions in Go and JavaScript: