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. The Entity ID will override the auto-generated Entity ID that is usually set when a new WorkOS connection is created to allow the SAML response to be accepted using the existing IdP configuration.
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:
Organization ID – The ID of the organization that was created for each connection should be persisted alongside the matching team in SuperApp. This will be used to initiate WorkOS SSO.
Connection ACS URL – This URL will be the location to forward SAML responses for legacy passport-saml connections.
WorkOS can provide a CSV containing these values upon request
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.
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.
This site uses cookies to improve your experience. Please accept the use of
cookies on this site. You can review our cookie policy
here and our privacy policy
here. If you choose to refuse, functionality of this
site will be limited.
