OAuth2 client for browsers and Node.js. Tiny footprint, PKCE support
npm install @badgateway/oauth2-clientThis package contains an OAuth2 client. It aims to be a fully-featured OAuth2
utility library, for Node.js, Browsers and written in Typescript.
This OAuth2 client is only 4KB gzipped, it has 0 dependencies and
relies on modern APIs like fetch() and [Web Crypto][4] which are built-in
since Node 18.
* 16KB minified (5KB gzipped).
* No dependencies.
* authorization_code grant with optional [PKCE][1] support.
* password and client_credentials grant.
* a fetch() wrapper that automatically adds Bearer tokens and refreshes them.
* OAuth2 endpoint discovery via the Server metadata document ([RFC8414][2]).
* OAuth2 Token Introspection ([RFC7662][3]).
* Resource Indicators for OAuth 2.0 ([RFC8707][5]).
* OAuth2 Token Revocation ([RFC7009][6]).
* OAuth 2.0 Multiple Response Type Encoding Practices
``sh`
npm i @badgateway/oauth2-client
To get started, set up the Client class.
`typescript
import { OAuth2Client } from '@badgateway/oauth2-client';
const client = new OAuth2Client({
// The base URI of your OAuth2 server
server: 'https://my-auth-server/',
// OAuth2 client id
clientId: '...',
// OAuth2 client secret. Only required for 'client_credentials', 'password'
// flows. Don't specify this in insecure contexts, such as a browser using
// the authorization_code flow.
clientSecret: '...',
// The following URIs are all optional. If they are not specified, we will
// attempt to discover them using the oauth2 discovery document.
// If your server doesn't have support this, you may need to specify these.
// you may use relative URIs for any of these.
// Token endpoint. Most flows need this.
// If not specified we'll use the information for the discovery document
// first, and otherwise default to /token
tokenEndpoint: '/token',
// Authorization endpoint.
//
// You only need this to generate URLs for authorization_code flows.
// If not specified we'll use the information for the discovery document
// first, and otherwise default to /authorize
authorizationEndpoint: '/authorize',
// OAuth2 Metadata discovery endpoint.
//
// This document is used to determine various server features.
// If not specified, we assume it's on /.well-known/oauth2-authorization-server
discoveryEndpoint: '/.well-known/oauth2-authorization-server',
});
`
Many functions use or return a 'OAuth2Token' type. This type has the following
shape:
`typescript
export type OAuth2Token = {
accessToken: string;
refreshToken: string | null;
/**
* When the Access Token expires.
*
* This is expressed as a unix timestamp in milliseconds.
*/
expiresAt: number | null;
/**
* If the server returned an OpenID Connect ID token, it will be stored here.
*/
idToken?: string;
};
`
`typescript`
const token = await client.clientCredentials();
`typescript`
const newToken = await client.refreshToken(oldToken);
`typescript`
const token = await client.password({
username: '..',
password: '..',
});
The authorization_code flow is the flow for browser-based applications,
and roughly consists of 3 major steps:
1. Redirect the user to an authorization endpoint, where they log in.
2. Authorization endpoint redirects back to app with a 'code' query
parameter.
3. The code is exchanged for a access and refresh token.
This library provides support for these steps, but there's no requirement
to use its functionality as the system is mostly stateless.
`typescript
import { OAuth2Client, generateCodeVerifier } from 'client';
const client = new OAuth2Client({
server: 'https://authserver.example/',
clientId: '...',
// Note, if urls cannot be auto-detected, also specify these:
tokenEndpoint: '/token',
authorizationEndpoint: '/authorize',
});
`
Redirecting the user to the authorization server
`typescript
/**
* This generates a security code that must be passed to the various steps.
* This is used for 'PKCE' which is an advanced security feature.
*
* It doesn't break servers that don't support it, but it makes servers that
* so support it more secure.
*
* It's optional to pass this, but recommended.
*/
const codeVerifier = await generateCodeVerifier();
// In a browser this might work as follows:
document.location = await client.authorizationCode.getAuthorizeUri({
// URL in the app that the user should get redirected to after authenticating
redirectUri: 'https://my-app.example/',
// Optional string that can be sent along to the auth server. This value will
// be sent along with the redirect back to the app verbatim.
state: 'some-string',
codeVerifier,
scope: ['scope1', 'scope2'],
});
`
Handling the redirect back to the app and obtain token
`typescript
const oauth2Token = await client.authorizationCode.getTokenFromCodeRedirect(
document.location,
{
/**
* The redirect URI is not actually used for any redirects, but MUST be the
* same as what you passed earlier to "authorizationCode"
*/
redirectUri: 'https://my-app.example/',
/**
* This is optional, but if it's passed then it also MUST be the same as
* what you passed in the first step.
*
* If set, it will verify that the server sent the exact same state back.
*/
state: 'some-string',
codeVerifier,
}
);
`
When using an OAuth2-protected API, typically you will need to obtain an Access
token, and then add this token to each request using an Authorization: Bearer
header.
Because access tokens have a limited lifetime, and occasionally needs to be
refreshed this is a bunch of potential plumbing.
To make this easier, this library has a 'fetch wrapper'. This is effectively
just like a regular fetch function, except it automatically adds the header
and will automatically refresh tokens when needed.
Usage:
`typescript
import { OAuth2Client, OAuth2Fetch } from '@badgateway/oauth2-client';
const client = new OAuth2Client({
server: 'https://my-auth-server',
clientId: 'my-client-id'
});
const fetchWrapper = new OAuth2Fetch({
client: client,
/**
* You are responsible for implementing this function.
* it's purpose is to supply the 'initial' oauth2 token.
*/
getNewToken: async () => {
// Example
return client.clientCredentials();
// Another example
return client.authorizationCode.getToken({
code: '..',
redirectUri: '..',
});
// You can return null to fail the process. You may want to do this
// when a user needs to be redirected back to the authorization_code
// endpoints.
return null;
},
/**
* Optional. This will be called for any fatal authentication errors.
*/
onError: (err) => {
// err is of type Error
}
});
`
After set up, you can just call fetch on the new object to call your API, andBearer
the library will ensure there's always a header.
`typescript`
const response = fetchWrapper.fetch('https://my-api', {
method: 'POST',
body: 'Hello world'
});
To keep a user logged in between sessions, you may want to avoid full
reauthentication. To do this, you'll need to store authentication token
somewhere.
The fetch wrapper has 2 functions to help with this:
`typescript
const fetchWrapper = new OAuth2Fetch({
client: client,
getNewToken: async () => {
// See above!
},
/**
* This function is called whenever the active token changes. Using this is
* optional, but it may be used to (for example) put the token in off-line
* storage for later usage.
*/
storeToken: (token) => {
document.localStorage.setItem('token-store', JSON.stringify(token));
},
/**
* Also an optional feature. Implement this if you want the wrapper to try a
* stored token before attempting a full re-authentication.
*
* This function may be async. Return null if there was no token.
*/
getStoredToken: () => {
const token = document.localStorage.getItem('token-store');
if (token) return JSON.parse(token);
return null;
}
});
`
It might be preferable to use this library as a more traditional 'middleware'.
The OAuth2Fetch object also exposes a mw function that returns a middleware
for fetch.
`typescript`
const mw = oauth2.mw();
const response = mw(
myRequest,
req => fetch(req)
);
This syntax looks a bit wild if you're not used to building middlewares, but
this effectively allows you to 'decorate' existing request libraries with
functionality from this oauth2 library.
A real example using the Ketting
library:
`typescript
import { Client } from 'ketting';
import { OAuth2Client, OAuth2Fetch } from '@badgateway/oauth2-client';
/**
* Create the oauth2 client
*/
const oauth2Client = new OAuth2Client({
server: 'https://my-auth.example',
clientId: 'foo',
});
/**
* Create the 'fetch helper'
*/
const oauth2Fetch = new OAuth2Fetch({
client: oauth2Client,
});
/**
* Add the middleware to Ketting
*/
const ketting = new Client('http://api-root');
ketting.use(oauth2Fetch.mw());
`
To be able to use it, your authorization server must have support for the
introspection endpoint. It's location will be automatically detected using
the Metadata discovery document.
`typescript
import { OAuth2Client } from '@badgateway/oauth2-client';
const client = new Client({
server: 'https://auth-server.example/',
clientId: '...',
/**
* Some servers require OAuth2 clientId/clientSecret to be passed.
* If they require it, specify it. If not it's fine to omit.
*/
clientSecret: '...',
});
// Get a token
const token = client.clientCredentials();
// Introspect!
console.log(client.introspect(token));
`
and client_secret encodingOAuth2 allows users to encode the client_id and client_secret either in aAuthorization: Basic header or in the POST request body.
Real-world OAuth2 servers may support one or the other, or both. The OAuth2
spec _requires_ that servers support the Authorization header, and don't
recommend using the body.
By default, this library will use the Authorization header. OAuth2 alsoclient_id
requires that clients percent-encode the and client_secret, but:
in practice many popular servers break if you do this. By default this library
will not percent encode any characters except the character.
You can change this behavior using the authenticatioMethod flag:
`typescript`
const client = new OAuth2Client({
server: 'https://auth-server.example/',
clientId: '...',
clientSecret: '...',
authenticationMethod: 'client_secret_post', // encode in POST body
});
The following 3 values are currently supported:
* client_secret_post - Encode in POST bodyclient_secret_basic
* - Encode in Authorization header using the strictclient_secret_basic_interop
standard rules.
* - Encode in Authorization header using less
strict rules. This is the default and more likely to work with popular
servers (at least some Google and Ebay APIs want this).
The current OAuth 2.1 draft switches the recommendation to use
client_secret_post by default instead. When that document stabilizes and getsclient_secret_post
released, this library will also switch to use by default
in a major release.
If your OAuth2 server supports POST, we recommend you use client_secret_post
as this is more likely to work without a hitch.
If you configured the client using the OAuth2 discovery document, and the
server indicates it prefers client_secret_basic` we will also default to the
strict form.
This package works out of the box with modern browsers and Node 18.
For Node 16 and below, use a 2.x version of this package and add
polyfills. The README.md for the 2.x branch of this package contains more information
on the exact steps for older Node versions.
[1]: https://datatracker.ietf.org/doc/html/rfc7636 "Proof Key for Code Exchange by OAuth Public Clients"
[2]: https://datatracker.ietf.org/doc/html/rfc8414 "OAuth 2.0 Authorization Server Metadata"
[3]: https://datatracker.ietf.org/doc/html/rfc7662 "OAuth 2.0 Token Introspection"
[4]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API "Web Crypto API"
[5]: https://datatracker.ietf.org/doc/html/rfc8707 "https://datatracker.ietf.org/doc/html/rfc8707"
[6]: https://datatracker.ietf.org/doc/html/rfc7009 "OAuth 2.0 Token Revocation"