oidc-tools

oidc-tools is a lightweight library designed for seamless integration with OpenID Connect (OIDC) authentication. This library simplifies the management of OIDC tokens, enabling developers to easily implement secure authentication flows in their applications.

Features

• Token Handling: Simplifies the decoding and verification of JWT tokens to ensure secure authentication.
• User Authentication: Generates URLs for logging in and logging out users with OIDC providers, facilitating a straightforward user experience.
• Environment Configuration: Utilizes environment variables to keep sensitive information, such as client secrets, secure and organized.
• PKCE Support: Implements Proof Key for Code Exchange (PKCE) by default, enhancing security for public clients.

Quick Start

To get started with oidc-tools, follow these usage examples that demonstrate its core functionality:

Initializing the Library

Begin by importing the library and configuring it with the necessary credentials:

import OidcTools from 'oidc-tools';

const { decodeToken, getLoginUrl, getLogoutUrl } = await OidcTools({
  issuerURL: process.env.OIDC_ISSUER_URL,
  clientId: process.env.OIDC_CLIENT_ID,
  clientSecret: process.env.OIDC_CLIENT_SECRET,
  redirectUri: process.env.OIDC_REDIRECT_URI,
  cache: true,
  cacheDuration: 300000,
  usePKCE: true
});

Decoding a JWT Token

Decode and verify the contents of a JWT token:

try {
  const payload = await decodeToken('your-jwt-token');
  console.log(payload);
} catch (error) {
  console.error('Token verification failed:', error.message);
}

Generating Login and Logout URLs

Facilitate user authentication by generating login and logout URLs:

const { url } = getLoginUrl();
console.log(`Redirect user to: ${url}`);

const logoutUrl = getLogoutUrl({
  postLogoutRedirectUri: 'https://your-app/logged-out'
});
console.log(`Logout URL: ${logoutUrl}`);

Complete Authentication Flow Example

For a comprehensive illustration, the repository includes an example demonstrating a full authentication flow using an HTTP server, available in the examples/auth-flow.js file.

API Overview

The following methods are provided by oidc-tools:

• OidcTools(options): Initialize the library with OIDC provider details.
• decodeToken(token): Verifies and decodes a given JWT token.
• getLoginUrl(params): Generates a login URL for user redirection.
• getLogoutUrl(params): Produces a URL for logging the user out of their OAuth session.
• exchangeToken(params): Exchanges an authorization code for access and ID tokens, with support for PKCE.

By leveraging this library, developers can enhance the security and efficiency of their user authentication processes, ensuring a smooth and reliable experience for their applications.