badgateway/oauth2-client

The authorization_code flow is designed for browser-based applications and involves three steps: redirecting the user, handling the redirect back to the app, and exchanging the code for a token. You can use generateCodeVerifier() to enable PKCE (Proof Key for Code Exchange) for enhanced security.

import { OAuth2Client, generateCodeVerifier } from '@badgateway/oauth2-client';

const client = new OAuth2Client({
  server: 'https://authserver.example/',
  clientId: '...',
  tokenEndpoint: '/token',
  authorizationEndpoint: '/authorize',
});

// 1. Redirect the user to the authorization server
const codeVerifier = await generateCodeVerifier();

document.location = await client.authorizationCode.getAuthorizeUri({
  redirectUri: 'https://my-app.example/',
  state: 'some-string',
  codeVerifier,
  scope: ['scope1', 'scope2'],
});

// 2. Handle the redirect back to the app and obtain token
// (This part runs on the page the user is redirected to)
const oauth2Token = await client.authorizationCode.getTokenFromCodeRedirect(
  document.location, // The current URL containing the 'code'
  {
    redirectUri: 'https://my-app.example/',
    state: 'some-string', // Must match the state sent in step 1
    codeVerifier,         // Must match the verifier sent in step 1
  }
);

OAuth2 servers vary in how they expect client_id and client_secret to be transmitted. This library defaults to using the Authorization header with client_secret_basic_interop encoding (which only percent-encodes the : character to maximize compatibility with servers like Google and Ebay).

If your server requires credentials in the POST body or requires strict standard encoding, use the authenticationMethod option during initialization.

Supported authenticationMethod values:

• client_secret_post: Encodes credentials in the POST request body. Recommended if your server supports it.
• client_secret_basic: Encodes credentials in the Authorization header using strict standard percent-encoding rules.
• client_secret_basic_interop: (Default) Encodes credentials in the Authorization header using less strict rules (only encoding :).

const client = new OAuth2Client({
  server: 'https://auth-server.example/',
  clientId: '...',
  clientSecret: '...',
  authenticationMethod: 'client_secret_post', // encode in POST body 
});

The OAuth2Fetch wrapper follows a specific lifecycle to ensure requests are authenticated with minimal latency:

1. Initialization: If getStoredToken is provided, the wrapper awaits its resolution to populate the initial token state.
2. Request Execution: When .fetch() is called, the wrapper retrieves the current access token via .getAccessToken().
3. Token Retrieval/Refresh:
   • If a valid token exists, it is used.
   • If the token is expired or near expiry, .refreshToken() is called.
   • If a refreshToken is available, it attempts to use the client.refreshToken() method. If that fails, it falls back to getNewToken().
4. Automatic Background Refresh: If scheduleRefresh is true, the wrapper sets a timer to refresh the token 1 minute before its expiresAt time. It only schedules a refresh if the token has an expiresAt value and a refreshToken available.
5. 401 Retry: If a request returns a 401 Unauthorized, the wrapper attempts to refresh the token once and retries the original request with the new token.

The OAuth2AuthorizationCodeClient class provides a specialized implementation for the authorization_code OAuth2 grant flow. This flow is typically used when a user needs to authorize your application via a browser redirect.

Workflow

1. Generate a Code Verifier: Use generateCodeVerifier() to create a high-entropy cryptographic string for PKCE support.
2. Get the Authorization URI: Use getAuthorizeUri() to generate the URL where the user should be redirected to log in.
3. Handle the Redirect: After the user authenticates, they are redirected back to your redirectUri. Use getTokenFromCodeRedirect() to automatically validate the response and exchange the code for an access token.

PKCE Support

For enhanced security (Proof Key for Code Exchange), provide the codeVerifier in both getAuthorizeUri and getToken (or via getTokenFromCodeRedirect). The client automatically handles generating the code_challenge and code_challenge_method (using S256).

import { OAuth2Client } from '../client.ts';
import { OAuth2AuthorizationCodeClient, generateCodeVerifier } from './authorization-code.ts';

const client = new OAuth2Client({ clientId: 'YOUR_CLIENT_ID' });
const authCodeClient = new OAuth2AuthorizationCodeClient(client);

// 1. Setup PKCE
const codeVerifier = await generateCodeVerifier();

// 2. Get URI for redirection
const authUri = await authCodeClient.getAuthorizeUri({
  redirectUri: 'https://yourapp.com/callback',
  codeVerifier,
  scope: ['openid', 'profile'],
  state: 'random_state_string'
});

// ... User visits authUri and is redirected back to https://yourapp.com/callback?code=XYZ&state=random_state_string

// 3. Exchange code for token
const token = await authCodeClient.getTokenFromCodeRedirect('https://yourapp.com/callback?code=XYZ&state=random_state_string', {
  redirectUri: 'https://yourapp.com/callback',
  state: 'random_state_string',
  codeVerifier
});

The OAuth2Fetch class is a wrapper around the standard fetch API that automatically manages Bearer tokens. It handles injecting the Authorization: Bearer <token> header, proactively refreshing tokens before they expire, and retrying requests if a 401 Unauthorized error is encountered.

To use it, you must provide an OAuth2FetchOptions object containing an OAuth2Client and a getNewToken function to handle initial authentication.

import { OAuth2Fetch } from '@badgateway/oauth2-client';

const oauth2Fetch = new OAuth2Fetch({
  client: myOAuth2Client,
  getNewToken: async () => {
    // Implement your logic to get a fresh token (e.g., via password or auth code grant)
    return await myOAuth2Client.getToken();
  },
  // Optional: persist tokens to localStorage/database
  storeToken: (token) => localStorage.setItem('token', JSON.stringify(token)),
  getStoredToken: async () => {
    const stored = localStorage.getItem('token');
    return stored ? JSON.parse(stored) : null;
  }
});

// Use it just like standard fetch
const response = await oauth2Fetch.fetch('https://api.example.com/data', {
  method: 'GET'
});
const data = await response.json();