passport-oauth2

The passport-oauth2 module provides generic OAuth 2.0 support.

• Use provider-specific strategies (e.g., passport-google-oauth2) when available. These strategies reduce configuration overhead and handle provider-specific quirks automatically.
• Use passport-oauth2 when you need to implement authentication against an OAuth 2.0 provider that does not have a dedicated Passport strategy.
• Sub-classing: If you are building a new provider-specific strategy, you are encouraged to sub-class this OAuth2Strategy.

Install the passport-oauth2 module using npm to add general-purpose OAuth 2.0 authentication support to your Passport-enabled Node.js application.

$ npm install passport-oauth2

Use passport.authenticate('oauth2') as middleware in your routes to handle the OAuth 2.0 flow. This typically involves two routes: one to initiate the authentication process and a callback route to handle the response from the provider.

When defining the callback route, you can provide options like failureRedirect to specify where the user should be sent if authentication fails.

// Route to initiate authentication
app.get('/auth/example',
  passport.authenticate('oauth2'));

// Callback route after provider redirect
app.get('/auth/example/callback',
  passport.authenticate('oauth2', { failureRedirect: '/login' }),
  function(req, res) {
    // Successful authentication, redirect home.
    res.redirect('/');
  });

When using the state option in OAuth2Strategy, passport-oauth2 requires a state store to generate and verify CSRF tokens. SessionStore is the built-in implementation that stores these tokens in req.session.

Requirements:

• You must have session support enabled in your application (e.g., using express-session middleware).
• You must provide a key in the options to specify where the state should be stored in the session object.

Error Handling: If req.session is missing, the store will throw an error: OAuth 2.0 authentication requires session support when using state. Did you forget to use express-session middleware?

const SessionStore = require('passport-oauth2/lib/state/store');

// When configuring your strategy:
const options = {
  // ... other options
  stateStore: new SessionStore({ key: 'oauth2_state' })
};

The SessionStore constructor accepts an options object to define how state is persisted in the user's session.

If key is not provided, a TypeError is thrown: Session-based state store requires a session key.

const store = new SessionStore({ key: 'my_custom_state_key' });

When using the state option in OAuth2Strategy, you can provide a SessionStore to manage the CSRF protection state. The SessionStore generates a random state string, stores it in the user's session, and verifies it upon the user's return from the service provider.

Requirements:

• You must have session middleware (like express-session) configured in your application.
• You must provide a key in the options object to specify where the state should be stored within req.session.

const SessionStore = require('passport-oauth2/lib/state/session');

// When initializing your strategy:
const options = {
  key: 'oauth2_state' // The key used in req.session
};

const store = new SessionStore(options);

When an error is received from an OAuth 2.0 token endpoint, passport-oauth2 may throw or return a TokenError. This error follows the structure defined in RFC 6749, section 5.2.

When catching this error, you can inspect the following properties to determine the cause of the failure:

• message: A human-readable description of the error.
• code: An OAuth 2.0 error code (e.g., invalid_request, invalid_client). Defaults to 'invalid_request' if not provided.
• uri: A URI explaining the error details.
• status: The HTTP status code associated with the error. Defaults to 500 if not provided.

If you encounter an error stating OAuth 2.0 authentication requires session support when using state. Did you forget to use express-session middleware?, it means the PKCESessionStore is attempting to access req.session but it is undefined.

To resolve this, ensure that you have session middleware (such as express-session) configured and applied to your application before the Passport middleware is invoked.

If you are using SessionStore and encounter errors, ensure that your application is correctly using session middleware. The SessionStore relies on req.session being present to function.

Common Error Message: OAuth 2.0 authentication requires session support when using state. Did you forget to use express-session middleware?

The passport-oauth2 module exports the Strategy class as its primary export, and also provides named exports for specific error types used during the OAuth 2.0 flow. You can require the module directly to get the Strategy or use named properties to access the error classes for error handling.

const OAuth2Strategy = require('passport-oauth2').Strategy;
const { 
  AuthorizationError, 
  TokenError, 
  InternalOAuthError 
} = require('passport-oauth2');