Registry / auth-security / simple-oauth2

simple-oauth2

JSON →
library1.0.4jsnpmunverified

Simple OAuth2 is a robust Node.js client library that provides a straightforward interface for interacting with OAuth 2.0 authorization servers. It supports various standard grant types including Authorization Code, Resource Owner Password Credentials, and Client Credentials, making it adaptable for diverse application architectures from web services to CLI tools. The package is currently stable at version 5.1.0, which mandates Node.js 14.x or higher, with a development branch (6.x) targeting Node.js 16.x and above. While a strict release cadence is not published, active development and maintenance are evident. Its primary differentiator lies in simplifying complex OAuth2 flows into an easy-to-use, promise-based API specifically for Node.js environments.

npm install simple-oauth2
INSTALL
IMPORT
SIG · SIMPLE-OAUTH2
S
simple-oauth2
auth-securityjavascriptv1.0.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

{ AuthorizationCode, ClientCredentials, ResourceOwnerPassword }
import { AuthorizationCode, ClientCredentials, ResourceOwnerPassword } from 'simple-oauth2';
const { AuthorizationCode } = require('simple-oauth2').create(config);
Since v5.0.0, the package primarily uses named exports for grant types. The `.create()` method from v4.x was removed.
AuthorizationCode (constructor)
const client = new AuthorizationCode(config);
const oauth2 = require('simple-oauth2').create(config);
Instantiate the desired grant type class directly after importing it. The factory function `create()` was removed in v5.x.
AccessToken
const accessToken = await client.getToken(tokenParams);
const token = await client.getToken(tokenParams); // then trying to call token.refresh()
The `getToken` method returns an `AccessToken` instance, which has helper methods like `refresh()` and `revoke()`.

This quickstart demonstrates the Authorization Code grant type, covering redirecting a user for authorization, handling the callback, exchanging the authorization code for an access token, and refreshing an expired token. It uses environment variables for sensitive configuration and basic error handling.

import { AuthorizationCode } from 'simple-oauth2'; import express from 'express'; import 'dotenv/config'; // For process.env const app = express(); const port = process.env.PORT || 3000; // Basic configuration for the OAuth2 client const config = { client: { id: process.env.OAUTH_CLIENT_ID ?? 'YOUR_CLIENT_ID', secret: process.env.OAUTH_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET' }, auth: { tokenHost: process.env.OAUTH_TOKEN_HOST ?? 'https://oauth.example.com', authorizePath: process.env.OAUTH_AUTHORIZE_PATH ?? '/oauth/authorize', tokenPath: process.env.OAUTH_TOKEN_PATH ?? '/oauth/token' } }; const client = new AuthorizationCode(config); const redirect_uri = process.env.OAUTH_REDIRECT_URI ?? `http://localhost:${port}/callback`; const scope = process.env.OAUTH_SCOPE ?? 'read write'; // Step 1: Redirect to the authorization server app.get('/auth', (req, res) => { const authorizationUri = client.authorizeURL({ redirect_uri, scope, state: 'random_state_string' // Should be a securely generated random string }); console.log(`Redirecting to: ${authorizationUri}`); res.redirect(authorizationUri); }); // Step 2: Handle the callback from the authorization server app.get('/callback', async (req, res) => { const { code, state } = req.query; // You should validate the 'state' parameter here to prevent CSRF attacks if (state !== 'random_state_string') { return res.status(403).send('Invalid state parameter'); } const tokenParams = { code: code as string, redirect_uri, scope }; try { const accessToken = await client.getToken(tokenParams); console.log('Successfully retrieved access token:'); console.log(accessToken.token); // Example: Refresh token if expired (or near expiration) if (accessToken.expired()) { console.log('Access token is expired, attempting to refresh...'); const refreshedToken = await accessToken.refresh(); console.log('Refreshed token:', refreshedToken.token); } res.send(`Access Token: ${accessToken.token.access_token}<br/>Refresh Token: ${accessToken.token.refresh_token || 'N/A'}`); } catch (error: any) { console.error('Access Token Error', error.message); res.status(500).send(`Authentication failed: ${error.message}`); } }); app.get('/', (req, res) => { res.send('<a href="/auth">Login with OAuth2</a>'); }); app.listen(port, () => { console.log(`Server running at http://localhost:${port}`); console.log('Visit /auth to initiate the OAuth2 flow.'); });
Debug
Known issues
breakingVersion 5.x introduced significant breaking changes. The primary export switched from a default export (e.g., `require('simple-oauth2').create`) to named exports for each grant type (e.g., `{ AuthorizationCode, ClientCredentials }`). The `create` factory method was removed.
fix
Update import statements and instantiation patterns. Instead of `const oauth2 = require('simple-oauth2').create(config);`, use `const { AuthorizationCode } = require('simple-oauth2'); const client = new AuthorizationCode(config);` or `import { AuthorizationCode } from 'simple-oauth2'; const client = new AuthorizationCode(config);`.
affects: >=5.0.0
breakingThe `tokenHost` configuration option is now strictly required in the client configuration object for `simple-oauth2` v5.x and above.
fix
Ensure your configuration object includes `auth: { tokenHost: 'https://your-oauth-server.com' }`. This was optional or handled differently in earlier versions.
affects: >=5.0.0
breakingThe library now explicitly requires Node.js 14.x or higher for 5.x releases, and Node.js 16.x or higher for the 6.x development branch. Older Node.js versions are no longer supported.
fix
Upgrade your Node.js runtime to at least version 14.x. For future compatibility, consider Node.js 16.x or later.
affects: >=5.0.0
gotchaAlways validate the `state` parameter received in the OAuth2 callback URL against the one you sent. This is crucial for preventing Cross-Site Request Forgery (CSRF) attacks.
fix
Generate a unique, cryptographically secure random string for the `state` parameter when initiating the authorization flow, store it (e.g., in a session), and verify it upon callback before exchanging the code for a token.
affects: *
gotchaAccess tokens have a limited lifetime. It's essential to implement refresh token logic to obtain new access tokens without re-authenticating the user once the current one expires.
fix
Use the `accessToken.expired()` helper and `accessToken.refresh()` method to programmatically refresh tokens. Ensure your configuration allows for refresh tokens if needed.
affects: *
Errors
Common errors & fixes
TypeError: (0 , simple_oauth2__WEBPACK_IMPORTED_MODULE_0__.create) is not a function
Attempting to use the `create` factory method from a v4.x import pattern with v5.x, which removed it.
fix
Change your import to use named exports and instantiate the grant type directly: `import { AuthorizationCode } from 'simple-oauth2'; const client = new AuthorizationCode(config);`
Error: tokenHost is required. Set `auth.tokenHost` in the configuration.
The `tokenHost` property is missing from the `auth` configuration object, which is now mandatory in v5.x.
fix
Add `tokenHost: 'https://your-oauth-server.com'` to the `auth` section of your configuration object.
Access Token Error [OAuth2Error: invalid_client] The client ID provided is not valid.
The `client.id` or `client.secret` in the configuration object is incorrect or the client is not registered with the OAuth2 provider.
fix
Double-check your `client.id` and `client.secret` against your OAuth2 provider's registration details. Ensure they are correctly set in your `config` object or environment variables.
Error refreshing access token: The refresh token provided is invalid or has expired.
The refresh token used to get a new access token is no longer valid, either due to expiration, revocation, or a one-time use policy.
fix
Refresh tokens can be single-use or expire. If a refresh fails, the user needs to re-authenticate through the full OAuth2 flow. Check your OAuth2 provider's policy on refresh token validity.
Upgrade
Version history
1.0.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
6
OpenAI (training)
1
Resources