@juxt/pass
v1.2.1
Published
Giving any web application access to sensitive data like an access token is a security risk and should be avoided as much as possible. This library takes advantage of the [Service Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worke
Downloads
11
Keywords
Readme
Rationale
Giving any web application access to sensitive data like an access token is a security risk and should be avoided as much as possible. This library takes advantage of the Service Workers API to store the access token in a secure environment and to attach it to the requests made to the protected resources.
Installation
npm install @juxt/pass
yarn add @juxt/pass
After installing, you need to run the init
script to generate the worker and redirect files.
npx @juxt/pass init
This script will place in your project public
folder the following files:
oauth-redirect.html
oauth-service-worker.js
if your public
folder is not in the root of your project or if it has a different name, you can specify the path to the folder as a parameter to the init
script.
npx @juxt/pass init ./path-to-public-folder
Usage
The library exposes two functions:
registerOAuth2Worker
registers a worker that attaches the bearer tokens to the user's provided protected resources. This function should be called once, so if used in an SPA, it should be called in the main entry point of the application.authorize
starts the oauth2 flow and, if successful, grants an access token to the client. it takes a single object as a parameter that must have the following shape:
export type Config = {
resource_server: string;
client_id: string;
redirect_uri: string;
authorization_endpoint: string;
token_endpoint: string;
requested_scopes: string[];
};
The following snippet provides a concrete example of how to use this library.
import { registerOAuth2Worker, authorize } from "@juxt/pass";
registerOAuth2Worker();
const resource_server = "https://home.juxt.site";
const authorization_server = "https://auth.home.juxt.site";
const app_server = "https://surveyor.apps.com";
// this callback wraps the `authorize` function and will be invoked when the user clicks for example on a login button
function authorizeCallback() {
authorize({
resource_server: resource_server,
client_id: "surveyor",
authorization_endpoint: `${authorization_server}/oauth/authorize`,
token_endpoint: `${authorization_server}/oauth/token`,
redirect_uri: `${app_server}/oauth-redirect.html`,
requested_scopes: [],
});
}
The authorize
function will await for the oauth2 flow to complete and it will return a promise that resolves to a string message. If the flow is successful, the message will be accessTokenStored
otherwise the promise is rejected with accessTokenError
.
If the authorize function must be invoked multiple times because the application interacts with multiple protected resources, it is crucial to ensure that these requests are not sent concurrently. Developers should await the completion of the authorize function before making subsequent calls with new parameters.
To clear the access token from the worker, the clearToken
function can be used.
const msg = await clearToken(resource_server);
The resource server (string) must be passed as a parameter to the clearToken
function. If the token is cleared successfully, the promise will resolve to accessTokenCleared
otherwise it will be rejected with clearTokenError
.