Passport-Hubspot-postilize Authentication Strategy

1.0.1 · active · verified Wed Apr 22

This package provides a Passport.js strategy for authenticating users against HubSpot using the OAuth 2.0 protocol. It enables Node.js applications, particularly those built with Connect-style middleware like Express, to integrate HubSpot login functionality. The current stable version is 1.0.1. The "postilize" suffix in the name suggests it might be a specialized or modified fork of a more general `passport-hubspot` library, potentially indicating a focused scope or a specific set of customizations. This strategy allows developers to configure authentication using HubSpot client ID, client secret, and a callback URL. It integrates with Passport's `passport.authenticate()` middleware to manage the OAuth flow, returning user profile data that includes `hub_id`, `hub_domain`, and `user_id`. While the exact release cadence isn't specified, its specialized nature might mean updates are less frequent than a foundational library.

Common errors

```
Error: Unknown authentication strategy "google"
```
cause The authentication strategy name passed to `passport.authenticate()` is `'google'` when it should be `'hubspot'` for this package.

fix Change `passport.authenticate('google', ...)` to `passport.authenticate('hubspot', ...)` in your route definitions.
```
OAuthCallbackError: Redirect URL mismatch
```
cause The `callbackURL` configured in the HubSpot API application settings does not exactly match the `callbackURL` provided in the `HubSpotStrategy` options.

fix Verify that the `callbackURL` property in your `HubSpotStrategy` configuration matches byte-for-byte (including http/https, domain, port, and path) with the 'Redirect URL' or 'Callback URL' configured in your HubSpot developer application settings.

Warnings

gotcha The example code provided in the original `README` for `/auth/hubspot` route middleware incorrectly uses `'google'` instead of `'hubspot'` as the strategy name. This is a common copy-paste error that can lead to an 'Unknown authentication strategy' error.
Fix: Ensure that `passport.authenticate()` explicitly specifies `'hubspot'` for HubSpot authentication, e.g., `passport.authenticate('hubspot', ...)`.
gotcha The package name `passport-hubspot-postilize` suggests it might be a specialized fork or modified version of a more generic `passport-hubspot` package. Users should verify if this specific variant meets their requirements or if a different, potentially more actively maintained `passport-hubspot` library is more suitable.
Fix: Review the package's GitHub repository or npm page for details on its specific modifications or purpose. Compare its features and maintenance status with other available HubSpot Passport strategies if specific customizations are not needed.

Install

npm install passport-hubspot-postilize npm
yarn add passport-hubspot-postilize yarn
pnpm add passport-hubspot-postilize pnpm

Imports

HubSpotStrategy

wrong:

import HubSpotStrategy from 'passport-hubspot-postilize'

correct:

import { Strategy as HubSpotStrategy } from 'passport-hubspot-postilize';
// Or for CommonJS:
const HubSpotStrategy = require('passport-hubspot-postilize').Strategy;

The strategy class is typically a named export, though the `require` example directly assigns the main export which itself *is* the Strategy constructor.

passport
wrong:
```
const passport = require('passport-hubspot-postilize');
```
correct:
```
import passport from 'passport';
```
Passport itself must be imported separately, as this package only provides the strategy, not the core Passport library.

Quickstart

This quickstart demonstrates how to set up HubSpot OAuth 2.0 authentication in an Express application using Passport.js, configuring the strategy and defining routes for initiating the login and handling the callback.

import express from 'express';
import passport from 'passport';
import { Strategy as HubSpotStrategy } from 'passport-hubspot-postilize';

const app = express();

// Dummy values for example, replace with actual environment variables
const HUBSPOT_CLIENT_ID = process.env.HUBSPOT_CLIENT_ID ?? 'YOUR_HUBSPOT_CLIENT_ID';
const HUBSPOT_CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET ?? 'YOUR_HUBSPOT_CLIENT_SECRET';
const CALLBACK_URL = process.env.HUBSPOT_CALLBACK_URL ?? 'http://localhost:3000/auth/hubspot/callback';

app.use(passport.initialize());

passport.use(new HubSpotStrategy({
    clientID:     HUBSPOT_CLIENT_ID,
    clientSecret: HUBSPOT_CLIENT_SECRET,
    callbackURL:  CALLBACK_URL,
    passReqToCallback: true
  },
  function(request, accessToken, refreshToken, profile, done) {
    // In a real application, you would find or create a user in your database
    // based on the profile information. For this example, we just return the profile.
    // console.log('HubSpot Profile:', profile);
    return done(null, profile);
  }
));

// Configure Passport to serialize and deserialize users (required for session support)
passport.serializeUser((user, done) => done(null, user));
passport.deserializeUser((obj, done) => done(null, obj));

app.get('/auth/hubspot',
  passport.authenticate('hubspot', { scope: 'contacts content' })
);

app.get( '/auth/hubspot/callback',
  passport.authenticate( 'hubspot', {
    successRedirect: '/auth/hubspot/success',
    failureRedirect: '/auth/hubspot/failure'
}));

app.get('/auth/hubspot/success', (req, res) => {
  res.send('HubSpot authentication successful!');
});

app.get('/auth/hubspot/failure', (req, res) => {
  res.send('HubSpot authentication failed!');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Initiate auth by visiting http://localhost:3000/auth/hubspot');
});

view raw JSON →