@resonant/oauth-client

resonant-oauth-client

A TypeScript library for performing OAuth login to a Resonant server.

Description

This provides support for authenticating with Resonant servers, using the OAuth2.0 Authorization Code Grant with PKCE flow.

Usage

• Install the library:

  npm install @resonant/oauth-client
  

• Instantiate an OauthClient with your application-specific configuration:

  import OauthClient from '@resonant/oauth-client';
  
  const oauthClient = new OauthClient(
    new URL(process.env.OAUTH_API_ROOT), // e.g. 'http://localhost:8000/oauth/'
    process.env.OAUTH_CLIENT_ID, // e.g. 'Qir0Aq7AKIsAkMDLQe9MEfORbHEBKsViNhAKJf1A'
  );
  

• Call redirectToLogin when it's time to start a login flow:

  document.querySelector('#sign-in-link').addEventListener('click', (event) => {
    event.preventDefault();
    oauthClient.redirectToLogin();
    // This will redirect away from the current page
  });
  

• At the start of every page load, unconditionally call maybeRestoreLogin, to attempt to restore a login state; this will no-op if no login is present. Afterwards, get and store HTTP headers for authentication from authHeaders.

  let authHeaders;
  oauthClient.maybeRestoreLogin()
    .then(() => {
      authHeaders = oauthClient.authHeaders;
    });
  

  or, if using ES6 and async/await:

  await oauthClient.maybeRestoreLogin();
  const { authHeaders } = oauthClient;
  

• Include these headers with every Ajax API request:

  fetch('http://localhost:8000/api/files', {
    headers: authHeaders,
  });
  

• The login state will persist across page refreshes. Call logout to clear any active login:

  document.querySelector('#sign-out-link').addEventListener('click', (event) => {
    event.preventDefault();
    oauthClient.logout()
      .then(() => {
        authHeaders = oauthClient.authHeaders;
      });
  });
  

Example app

This repository comes bundled with an example application. Run it with:

git clone https://github.com/kitware-resonant/resonant-oauth-client.git
npm install
npm run build
cd example
npm install
npm run serve
# Visit http://localhost:1234/

Development

To develop the library using the example app:

# From the root of the repository
npm install
npm run watch

In another terminal:

# From the root of the repository
cd example
npm install
npm run serve