Passport.js to WorkOS Migration Guide

Michael Hadley

October 25, 2023

Passport.js is an authentication middleware for Node.js. While suitable for addressing initial authentication needs, scaling with enterprise features like SSO and SCIM becomes unsustainably complex. This guide details 8 steps to transition from Passport.js to WorkOS.

‍Scaling Constraints

‍Passport.js is organized around the concept of "strategies," which are modules or functions responsible for handling different authentication methods like local authentication, as well as OAuth and OpenID Connect (OIDC) that are used to support SSO. Typically, Passport.js will function as a viable solution for the first few connections. However, as the demand for enterprise support grows, manually provisioning SSO connections with the customer’s identity providers (IdPs) becomes unsustainable. A common next step is to find a replacement solution with an intuitive UI and a seamless IT admin onboarding flow to off-load the SSO maintenance completely.

"With our in-house solution built on Passport.js, we had to spend 2-4 hours provisioning each SSO connection for enterprise customers. I had no interest in our team becoming SSO/SCIM experts and wanted to find a solution that would allow us to focus on building core products.”
- Jarel Fryer, Engineering Manager, Chromatic

‍Significant Lift to Implement User Provisioning

Implementing SCIM (System for Cross-Domain Identity Management), which is critical for user provisioning and deprovisioning, in Passport.js demands considerable effort. This includes crafting route handlers and middleware functions essential for user operations like creation, retrieval, updating, and deletion. To achieve SCIM compliance, strict adherence to IETF (Internet Engineering Task Force) standards is also necessary, including aspects like error response handling, pagination, attribute mapping, and managing complex data structures.

Alternative: Migrate to WorkOS in 8 steps

This migration guide outlines a clear, technical path for transitioning from Passport.js to WorkOS. It aims to empower organizations to efficiently manage their SSO connections, simplify user provisioning/deprovisioning, and focus on core product development. An imaginary “SuperApp” will be used as an example.

Preparation

Integrate WorkOS SSO

Follow our guide to add a WorkOS SSO callback endpoint. This will be used for both existing and new SSO users.

        
import type { NextApiRequest, NextApiResponse } from 'next';
import WorkOS from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;

export default (_req: NextApiRequest, res: NextApiResponse) => {
  // The user's organization ID
  const organization = 'org_123';

  // The callback URI WorkOS should redirect to after the authentication
  const redirectURI = 'https://dashboard.my-app.com';

  const authorizationUrl = workos.sso.getAuthorizationURL({
    organization,
    redirectURI,
    clientID,
  });

  res.redirect(authorizationUrl);
};

If you'd like to continue using Passport.js alongside WorkOS or migrate connections over time, take a look at our sample application for an example of how to use WorkOS as a passport strategy.

Backfill SSO configuration into WorkOS

To provide WorkOS a copy of existing SSO configuration data in SuperApp, email support@workos.com for specific next steps. We’ll bulk create matching connections in your WorkOS environment.
Required information:
- Customer name – Used to name the Organization containing the SSO connection.
- Customer email domain – The domain of the email addresses of users who are signing in through that SSO connection (e.g. customer.com).
- Entity ID (Issuer) – The identifier given to the IdP when initiating SSO.
- IdP Entity ID (Audience) – The identifier of the IdP.
- SSO URL – The URL where the IdP accepts SAML requests.
- IdP Public Cert – The cert used to verify SAML responses from the IdP.
- Any other non-standard settings that are relevant.

A Note on Attribute Mappings: WorkOS has a flexible attribute mapping system and can adapt to whatever attributes your application is already receiving from your customer's IdPs.

Migration

Backfill WorkOS Resource IDs into SuperApp:
- After WorkOS has bulk-created connections, two fields from each connection will need to be persisted in SuperApp:

Existing SSO Flow

Re-route new SSO customers

When you onboard new SSO customers, they can set up their connection through WorkOS Admin Portal.
These customers won’t go through the legacy passport-saml endpoint, and SAML responses will go directly to WorkOS.

Forward SAML Responses to WorkOS

Since legacy passport-saml IdPs will still send their responses to SuperApp directly, use a 307 redirect response to forward them to WorkOS.
See this example application for a demonstration of how to forward a SAML response to WorkOS.

Set up IdP-Initiated SSO with WorkOS

For customers who set up SSO post-WorkOS, see our docs about implementing IdP-Initiated SSO.
IT admins can be instructed to set a default RelayState with the correct Redirect URI for their customer-specific SuperApp subdomain.

Set up IdP-Initiated SSO for legacy passport-saml connections

These IdPs predate WorkOS, and so won’t have a default RelayState set.
Suggested flow for handling these users:

In the endpoint that forwards legacy SAML responses to WorkOS, set a signed cookie that stores the customer domain for later. E.g. https://customer.superapp.com/connect/saml/callback sets an auth_domain cookie to customer.superapp.com.
Set a default Redirect URI in the WorkOS dashboard to an endpoint that is not customer specific. E.g. https://auth.superapp.com/saml/default.
When WorkOS directs the user to the above endpoint, the auth_domain cookie is read, verified, and the user is redirected to the correct customer domain. code and state should be preserved in the redirect.
Finally, the customer-specific callback exchanges the authorization code and a session can be started, scoped to their customer subdomain.

Cleanup

Remove passport-saml

We recommend using feature flags to incrementally move customers over to the WorkOS-based SSO login flow.
Once all customers are using the WorkOS flow, the passport-saml strategy can be removed entirely.
The endpoint that forwards SAML responses to WorkOS will need to stay, as long as any legacy passport-saml customers still have their IdP configured to use the old direct-to-SuperApp ACS URLs.

Conclusion

As organizations grow, the constraints of Passport.js, especially regarding SSO and SCIM, become increasingly evident. These areas demand substantial maintenance and bespoke development for enterprise-grade support. For improved scalability and resource optimization, consider transitioning to WorkOS for streamlined SSO and SCIM integrations as well as user-friendly IT admin onboarding. Contact support@workos.com for a seamless, zero-downtime migration.

In this article

Link

We’re hiring

Our global team is growing and we’re hiring all types of roles.

View open roles

About us

WorkOS builds developer tools for quickly adding enterprise features to applications.

Learn more