@manisharma7575/oauthx

OAuthX is a lightweight OAuth 2.0 client library that simplifies authentication using the Authorization Code flow with PKCE. It provides easy-to-use methods for generating authorization URLs, handling authentication callbacks, and refreshing access tokens.

OAuth Flow Supported:

Authorization Code
PKCE
Implicit

Scope of Improvement

Example for the Server Side Rendering
Integrating Client Credentials Flow
Jest test

Installation

Install the package via npm:

npm install @manisharma7575/oauthx

Demo Application

https://oauthx.netlify.app/

cd examples/my-oauth-client-app

Make sure the credentails are set in the .env file

npm install
npm run dev

Usage

Initialize OAuthXClient

To set up OAuthXClient, provide the necessary OAuth 2.0 configurations:

import { OAuthXClient } from "@manisharma7575/oauthx";

const oauthClient = new OAuthXClient({
  server: "AUTH_SERVER",
  client_id: "CLIENT_ID",
  client_secret: "CLIENT_SECRET",
  redirect_uri: "REDIRECT_URI",
  token_endpoint: "TOKEN_ENDPOINT", // Default Value: "/token"
  authorization_endpoint: "AUTHORIZE_ENDPOINT" // Default Value: "/authorize"
});

Public Methods

getAuthorizeURI(params)

Generates the authorization URL for initiating the OAuth flow.

Params:

response_type (string, required) - The response type (e.g., "code", "token").
scope (array, required) - The list of scopes.
codeVerifier (string, optional) - PKCE code verifier.
state (string, optional) - A custom state value.

Example:

const authUrl = await oauthClient.getAuthorizeURI({
  response_type: "code",
  scope: ["openid", "profile", "email", "offline_access"],
  codeVerifier: "random_code_verifier",
  state: "custom_state",
});

window.location.href = authUrl;

handleCallback(params)

Handles the OAuth callback and exchanges the authorization code for an access token.

Params:

grant_type (string, required) - The type of grant (e.g., "authorization_code").
uri (string, required) - The callback URI containing the authorization code.
code_verifier (string, required) - The PKCE code verifier used in the request.
state (string, optional) - The state value from the authorization request.

Example:

const tokenResponse = await oauthClient.handleCallback({
  grant_type: "authorization_code",
  uri: window.location.href,
  code_verifier: localStorage.getItem("code_verifier") || "",
  state: "custom_state",
});

console.log(tokenResponse.access_token);

refreshToken(refreshToken, params)

Refreshes the access token using a refresh token.

Params:

refreshToken (string, required) - The refresh token.
params (object, optional) - Additional parameters for the refresh request.

Example:

const newTokenResponse = await oauthClient.refreshToken("your_refresh_token");
console.log(newTokenResponse.access_token);

PKCE Utility

generateRandomCodeVerifier()

Generates a secure random code verifier for PKCE.

Example:

import { PKCE } from "@manisharma7575/oauthx";

const verifier = await PKCE.generateRandomCodeVerifier();
console.log(verifier);

Example Workflow

Generate an authorization URL using getAuthorizeURI and redirect the user to the OAuth provider.
Handle the authentication callback using handleCallback to exchange the authorization code for an access token.
Store the access and refresh tokens securely (e.g., local storage or secure storage).
Use the access token to make authenticated API requests.
Refresh the access token using refreshToken when it expires.