idtoken-verifier

What is idtoken-verifier?

The idtoken-verifier npm package is used to verify ID tokens, typically in the context of authentication and authorization. It helps ensure that the tokens are valid, properly signed, and not tampered with.

What are idtoken-verifier's main functionalities?

Verify ID Token

This feature allows you to verify the validity of an ID token. You need to provide the issuer and audience information, and then use the `verify` method to check the token. If the token is valid, the payload is returned; otherwise, an error is provided.

const IdTokenVerifier = require('idtoken-verifier');

const verifier = new IdTokenVerifier({
  issuer: 'https://your-issuer.com/',
  audience: 'your-audience'
});

const token = 'your-id-token';

verifier.verify(token, (err, payload) => {
  if (err) {
    console.error('Token verification failed:', err);
  } else {
    console.log('Token is valid. Payload:', payload);
  }
});

Decode ID Token

This feature allows you to decode an ID token without verifying it. The `decode` method returns the decoded token, which can be useful for inspecting the token's contents.

const IdTokenVerifier = require('idtoken-verifier');

const token = 'your-id-token';

const decoded = IdTokenVerifier.decode(token);
console.log('Decoded token:', decoded);

Other packages similar to idtoken-verifier

jsonwebtoken

The jsonwebtoken package is a popular library for working with JSON Web Tokens (JWTs). It provides functionalities for signing, verifying, and decoding tokens. Compared to idtoken-verifier, jsonwebtoken offers a broader range of features for handling JWTs, including token creation.

jose

The jose package is a comprehensive library for JSON Web Algorithms (JWA), JSON Web Keys (JWK), JSON Web Signatures (JWS), and JSON Web Encryption (JWE). It provides extensive support for various cryptographic operations related to JWTs. While idtoken-verifier focuses on verifying ID tokens, jose offers a more extensive set of tools for working with JWTs and related standards.

passport-jwt

The passport-jwt package is a Passport strategy for authenticating with JSON Web Tokens. It is used in conjunction with the Passport authentication middleware for Node.js. This package is more focused on integrating JWT authentication into web applications, whereas idtoken-verifier is specifically for verifying ID tokens.

README

idtoken-verifier

A lightweight library to decode and verify RS JWT meant for the browser.

Usage

import IdTokenVerifier from 'idtoken-verifier';

const verifier = new IdTokenVerifier({
  issuer: 'https://my.auth0.com/',
  audience: 'gYSNlU4YC4V1YPdqq8zPQcup6rJw1Mbt'
});

verifier.verify(id_token, nonce, (error, payload) => {
  if (error) {
    // handle the error
    return;
  }

  // do something with `payload`
});

IdTokenVerifier

Initializes the verifier.

Parameters:

• configuration
  • issuer: the issuer you trust to sign the tokens.
  • audience: the audience the token is issued for.
  • leeway: when there is a clock skew times between the signing and verifying servers. The leeway should not be bigger than five minutes.
  • jwksCache: the verifier will try to fetch the JWKS from the /.well-known/jwks.json endpoint (or jwksURI if provided) each time it verifies a token. You can provide a cache to store the keys and avoid repeated requests. For the contract, check this example. Hint: for in-memory cache, an easy way is to just provide new Map(), which is a valid object for jwksCache.
  • jwksURI: A valid, direct URI to fetch the JSON Web Key Set (JWKS). Defaults to ${id_token.iss}/.well-known/jwks.json
• callback
  • error: the validation error if any, null otherwise
  • payload: the decoded jwt payload

verifier.verify

This method will decode the ID token, then verify the token for OIDC compliance using a series of checks on the claims found inside the token.

Parameters

• id_token: the id_token to verify.
• nonce: the nonce previously sent to tha authorization server.
• callback

verifier.decode

This method will decode the token header and payload WITHOUT doing any verification.

Parameters

• id_token: the id_token to decode.

Return

• header: the decoded header.
• payload: the decoded payload.
• encoded: the parts without decode
  • header: the header string.
  • payload: the payload string.
  • signature: the signature string.

Support

To make it as lightweight as posible, it only provides support for RS256 tokens. It can be easily extensible to other RS* algorithms.

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author

Auth0

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Changelog

v2.1.1 (2021-05-25)

Full Changelog

Fixed

• Fixed: exception when key not found in JWKS #121 (ItalyPaleAle)
• Remove inconsistencies in verify method's callback invocations #120 (ItalyPaleAle)

Security

• Fix vulnerability with crypto-js 3.3.0 and run audit fix #128 (frederikprijck)
• [Security] Bump y18n from 4.0.0 to 4.0.1 #119 (dependabot-preview[bot])