Passport.js: The Generic OAuth2 Strategy

WHY IT EXISTS To provide a standardized, reusable foundation for implementing the OAuth 2.0 authentication flow in Node.js applications. Instead of every developer re-implementing the redirect-and-token-exchange dance from scratch, this package provides the core logic that can be extended for any OAuth 2.0 compliant service.

THE MENTAL MODEL Think of passport-oauth2 as a generic car chassis. It has the engine, wheels, and steering, but no body panels or interior. You can build any car on top of it, but you must supply all the specific parts yourself. Provider-specific strategies like passport-google-oauth20 are fully assembled cars, ready to drive off the lot. You only use the chassis when you're building a custom vehicle.

HOW IT WORKS You instantiate OAuth2Strategy with an options object and a verify callback. The options must include the provider's authorizationURL, tokenURL, and your app's clientID and clientSecret. When a user tries to log in, Passport redirects them to the authorizationURL. After they approve, the provider redirects back to your app with an authorization code. Passport then uses this code to request an access token from the tokenURL. Finally, your verify callback receives the token and profile to find or create a user in your database.

WHEN TO USE IT Use this strategy when you are authenticating against an OAuth 2.0 provider that does not have a dedicated, pre-existing Passport strategy. This is common for internal enterprise services, new SaaS platforms, or any custom-built authentication system that follows the OAuth 2.0 standard. It's a tool for building, not for direct consumption.

WHEN NOT TO USE IT Do not use passport-oauth2 directly if a provider-specific strategy exists. For example, for Google, use passport-google-oauth20; for GitHub, use passport-github2. These dedicated packages handle provider-specific endpoint URLs, scopes, and profile data normalization, which saves you configuration and prevents subtle bugs. Using the generic strategy here is reinventing the wheel.

ONE CANONICAL EXAMPLE To connect to a fictional service, you configure the strategy by providing all the necessary URLs and credentials: passport.use(new OAuth2Strategy({ authorizationURL: 'https://auth.example.com/oauth2/authorize', tokenURL: 'https://auth.example.com/oauth2/token', clientID: 'YOUR_CLIENT_ID', clientSecret: 'YOUR_CLIENT_SECRET', callbackURL: "http://localhost:3000/auth/example/callback" }, function(accessToken, refreshToken, profile, cb) { // Logic to find or create a user in your database. return cb(null, user); }));