Passport Sendoso OAuth 2.0 Strategy

Common errors

• Error: Unknown authentication strategy "sendoso"

  cause The Passport strategy has not been correctly registered with `passport.use()` before attempting to use it.
  fix Ensure `passport.use(new SendosoStrategy(...))` is called and the strategy name matches what is used in `passport.authenticate('sendoso', ...)`.

• OAuth2Strategy requires a clientID option

  cause The `clientID` option was not provided or was an empty string in the `SendosoStrategy` configuration.
  fix Provide a valid `clientID` string obtained from your Sendoso application registration to the `SendosoStrategy` options.

• Error: Failed to obtain access token

  cause Commonly caused by an incorrect `clientSecret`, an invalid `callbackURL` (which must exactly match the one registered with Sendoso), or network issues.
  fix Double-check your `clientSecret` and ensure your `callbackURL` in the strategy configuration precisely matches the one registered in your Sendoso application settings.

• TypeError: Cannot read properties of undefined (reading 'authenticate')

  cause The Passport middleware (`passport.initialize()` and `passport.session()`) has not been applied to the Express app, or Passport itself hasn't been imported.
  fix Make sure you have `app.use(passport.initialize());` and `app.use(passport.session());` configured in your Express application middleware chain after session middleware.

Warnings

• gotcha The provided README example for the initial authentication route uses `passport.authenticate('google', ...)` instead of `passport.authenticate('sendoso', ...)`. This is a copy-paste error and should be corrected to `'sendoso'` to use the configured strategy.
  Fix: Change `passport.authenticate('google', ...)` to `passport.authenticate('sendoso', ...)` in your routes.
• gotcha The package name `passport-sendoso-postilize` (with unusual capitalization and the 'postilize' suffix) suggests it might be a specific internal or highly customized version, not a generic, community-maintained 'passport-sendoso' package. This could lead to confusion or specific integration quirks.
  Fix: Verify that this package is the intended and officially supported Sendoso integration for your project. Consider implications if expecting a standard 'passport-sendoso' library.
• gotcha The documentation uses CommonJS `require()` syntax exclusively. While Node.js can often handle mixed modules, explicit ESM (`import`) support or examples are absent, implying it might be primarily tested/designed for CJS environments or require manual configuration for ESM.
  Fix: For ESM projects, ensure your build system correctly transpiles or handles CommonJS modules. If directly importing, use `import { Strategy as SendosoStrategy } from 'passport-sendoso-postilize';`.
• gotcha The example authentication scopes `contacts content` are typical for Google OAuth and are unlikely to be valid for Sendoso's OAuth implementation. Actual Sendoso scopes must be used.
  Fix: Refer to the Sendoso API documentation for the correct OAuth 2.0 scopes required for your application and update `passport.authenticate()` accordingly.

Install

• npm install passport-sendoso-postilize npm
• yarn add passport-sendoso-postilize yarn
• pnpm add passport-sendoso-postilize pnpm

Imports

• Strategy
  wrong:

  import SendosoStrategy from 'passport-sendoso-postilize';

  correct:

  import { Strategy as SendosoStrategy } from 'passport-sendoso-postilize';

  The primary OAuth 2.0 strategy class is typically aliased to 'SendosoStrategy' for clarity in ESM. CommonJS environments use `require('passport-sendoso-postilize').Strategy`.
• passport
  wrong:

  import * as passport from 'passport';

  correct:

  import passport from 'passport';

  The core Passport.js library, usually imported as a default export for direct use with `passport.use()` and `passport.authenticate()`.

Quickstart

Demonstrates how to configure and use the Passport-Sendoso-postilize strategy with Express, including session management, authentication routes, and user serialization/deserialization.

const express = require('express');
const passport = require('passport');
const session = require('express-session'); // Required for Passport sessions
const { Strategy: SendosoStrategy } = require('passport-sendoso-postilize'); // Using destructuring for clarity

const app = express();

// Passport configuration
passport.use(new SendosoStrategy({
    clientID:     process.env.SENDOSO_CLIENT_ID ?? 'YOUR_SENDOSO_CLIENT_ID',
    clientSecret: process.env.SENDOSO_CLIENT_SECRET ?? 'YOUR_SENDOSO_CLIENT_SECRET',
    callbackURL:  "http://localhost:3000/auth/sendoso/callback",
    passReqToCallback: true
  },
  function(request, accessToken, refreshToken, profile, done) {
    // In a real application, you would typically find or create a user in your database
    // based on the profile information returned by Sendoso.
    // The 'profile' object would contain user details provided by Sendoso.
    // For demonstration, we'll return a placeholder user.
    const user = { id: profile?.id || 'sendoso_user_123', name: profile?.displayName || 'Sendoso User' };
    console.log('Sendoso Profile:', profile);
    console.log('Access Token:', accessToken);
    done(null, user); // Call done with null for error and the user object
  }
));

// Passport session setup.
//   To support persistent login sessions, Passport needs to be able to
//   serialize users into and deserialize users out of the session.
//   Typically, this will be as simple as storing the user ID when serializing
//   and finding the user by ID when deserializing.
passport.serializeUser(function(user, done) {
  done(null, user.id);
});

passport.deserializeUser(function(id, done) {
  // In a real application, retrieve user from database by ID
  const user = { id: id, name: 'Deserialized User' }; // Placeholder
  done(null, user);
});

// Middleware for Express
app.use(session({ secret: 'keyboard cat', resave: false, saveUninitialized: false }));
app.use(passport.initialize());
app.use(passport.session());

// Define authentication routes
app.get('/auth/sendoso',
  passport.authenticate('sendoso', { scope: 'profile email' } // Replace 'profile email' with actual Sendoso scopes if available
));

app.get('/auth/sendoso/callback',
  passport.authenticate('sendoso', {
    successRedirect: '/profile', // Redirect to a profile page on success
    failureRedirect: '/login'    // Redirect to login on failure
  })
);

app.get('/profile', (req, res) => {
  if (req.isAuthenticated()) {
    res.send(`<h1>Welcome, ${req.user.name || 'authenticated user'}!</h1><pre>${JSON.stringify(req.user, null, 2)}</pre><p><a href="/logout">Logout</a></p>`);
  } else {
    res.redirect('/login');
  }
});

app.get('/login', (req, res) => {
  res.send('<h1>Login with Sendoso</h1><p><a href="/auth/sendoso">Login with Sendoso</a></p>');
});

app.get('/logout', (req, res, next) => {
  req.logout((err) => {
    if (err) { return next(err); }
    res.redirect('/login');
  });
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Visit http://localhost:3000/login to start the authentication flow.');
});