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:
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: 'react.localhost.pomerium.io',
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;
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
and audience
parameters should both be set to the domain 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
Parameters | Description | Value |
---|---|---|
issuer | The domain of the upstream application (for example, httpbin.corp.example.com ). | String |
audience | The same value as issuer . | String |
expirationBuffer | Adds padding in seconds to prevent throwing errors for expired JWTs that may have differing server times. Defaults to 0 | Integer |
firstUse | Decides whether or not to trust the first JWT. | Boolean |
jwtData | The JSON payload containing JWT claims. | Object |
verifiedJwtData | The verified JSON payload containing JWT claims. | Object |
Methods
Method | Description |
---|---|
getClientJwt | Fetches client JWT from the /.pomerium/jwt endpoint. |
parseJWT | Decodes JWT token. |
getJWKsData | Fetches JWKs data from the /.well-known/pomerium/jwks.json endpoint. |
verifyPomeriumJWT | Verifies JWT using the jwt , authenticateBaseUrl , issuer , and audience parameters. |
withHttps | Prepends the URL with the https:// protocol. |
signOut | Signs 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: