girder-oauth-client

A TypeScript library for performing OAuth login to a Girder 4 (Django) server.

Description

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

Usage

Install the library:

yarn add @girder/oauth-client

or if you're using npm:

npm install @girder/oauth-client

Instantiate an OauthClient with your application-specific configuration:

import OauthClient from '@girder/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();
let { authHeaders } = client;
```

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/girder/girder-oauth-client.git
yarn install
yarn build
cd example
yarn install
yarn serve
# Visit http://localhost:1234/

Development

To develop the library using the example app:

# From the root of the repository
yarn link
yarn install
yarn watch

In another terminal:

# From the root of the repository
cd example
yarn link '@girder/oauth-client'
yarn install
yarn serve