passport-facebook

passport-facebook plugs into Passport, the modular authentication middleware for Node.js, to let applications authenticate users through Facebook’s OAuth 2.0 login flow. It handles the redirect to Facebook’s authorization dialog, the token exchange, and the retrieval and normalization of the user’s profile data, so an Express (or other Connect-style) app only needs to supply an app ID, app secret, and a callback URL.

The strategy extends passport-oauth2, overriding Facebook-specific behavior: non-standard error response formats, an enableProof option for appsecret_proof-based API security, configurable Graph API versions, and profile field selection. It has been a de facto standard for adding “Login with Facebook” to Node applications for well over a decade.

What You Get

• A drop-in Passport Strategy class configured with just clientID, clientSecret, and callbackURL
• Automatic handling of Facebook’s non-standard OAuth 2.0 error responses via dedicated FacebookAuthorizationError, FacebookTokenError, and FacebookGraphAPIError error types
• A normalized user profile (id, displayName, name, gender, emails, photos) parsed from Facebook’s Graph API response
• Support for enableProof to sign Graph API requests with an appsecret_proof HMAC, satisfying Facebook’s stricter server-side API security setting
• Configurable graphAPIVersion and profileFields so requests target the exact Graph API version and fields an app needs

Common Use Cases

• Adding a “Log in with Facebook” button to an Express or Connect-based web application
• Federated login flows where a Facebook account is linked to a local user record on first sign-in
• Server-rendered apps that need Facebook identity without hand-rolling OAuth 2.0 redirects and token exchange
• Multi-provider auth setups where Facebook is one of several Passport strategies (Google, GitHub, etc.) behind a shared session

Under The Hood

Architecture passport-facebook is a small, single-purpose extension of passport-oauth2: lib/strategy.js defines a Strategy constructor that calls into OAuth2Strategy via util.inherits, pre-filling Facebook’s authorization and token URLs and overriding authenticate, authorizationParams, userProfile, and parseErrorResponse to account for Facebook’s quirks. lib/profile.js is a pure function that maps a raw Graph API JSON payload onto Passport’s normalized profile shape, and lib/errors/ defines three small Error subclasses used to surface Facebook’s non-standard authorization and token error payloads distinctly from generic OAuth errors. Data flows linearly: constructor options configure endpoints, the inherited OAuth2Strategy performs the redirect and code exchange, userProfile fetches and hands off Graph API JSON to Profile.parse, and the result reaches the application’s verify callback. Because the strategy reaches directly into this._oauth2 and calls OAuth2Strategy.prototype methods, any change to passport-oauth2’s constructor or internals would break it directly — the coupling is close and intentional.

Tech Stack The only runtime dependency is passport-oauth2 (pinned to the 1.x.x range), and the module is plain CommonJS with no build step, no TypeScript, and an engines floor of Node >= 0.4.0 reflecting its 2011 origins. Development tooling is correspondingly old-school: mocha 2.x and chai 2.x for tests, chai-passport-strategy for strategy-specific assertions, and a Makefile (via make-node) driving make test/make check rather than npm scripts directly.

Code Quality The test/ directory has four suites (strategy.test.js, strategy.profile.test.js, profile.test.js, package.test.js) written in mocha’s BDD describe/it style, using chai-passport-strategy to simulate authenticate/redirect flows against fixture Graph API responses (test/fixtures/picture.json, picture-2012-10.json). Historic Travis CI configuration ran the suite across a wide matrix of Node versions with istanbul coverage and Coveralls reporting. Error handling is explicit — Facebook’s malformed OAuth error responses are caught and re-thrown as typed errors rather than swallowed. There is no TypeScript and no modern linter (only a .jshintrc), consistent with the module’s age, but naming and structure are consistent throughout.

What Makes It Unique The library’s value is narrow and well-executed: it correctly implements the specific ways Facebook’s OAuth 2.0 implementation deviates from the spec (error payload shape, appsecret_proof requirements, Graph API versioning) so consuming applications don’t have to. It doesn’t attempt to be a general OAuth client — it is a thin, well-scoped adapter over passport-oauth2 for one provider, which is exactly the shape the wider Passport ecosystem expects from its strategy packages.