This example demonstrates a migration path from a custom SSO implementation running on passport-saml
to a SSO implementation to WorkOS.
git clone https://github.com/workos/passport-saml-migration-example.git
cd passport-saml-migration-example
npm i
Using ngrok
, we prepare a tunnel to port 3000 on our local machine, and obtain the forwarding URL.
ngrok http 3000
Make note of the Forwarding URL, which will look something like https://7736-2001-871-216-2b68-69bd-a3bb-d4d6-af3f.ngrok-free.app
. This will be used in the next step.
Copy the .env.example
to .env
, and edit it with your specific env variables
cp .env.example .env
Guidence for common identity providers can be found from the WorkOS SSO Quickstart.
However, we wish to configure the IDP in its "pre-migration" state, therefore we will deviate from the standard WorkOS instructions, omiting WorkOS, and configure the IDP to point directly to our passport-saml
example.
Create an APP in your IDP of choice, setting the following:
- Entity ID - Sometimes called the "Issuer", this effectively a name of your app. Set it to be the public URL of the example app, i.e.
https://7736-2001-871-216-2b68-69bd-a3bb-d4d6-af3f.ngrok-free.app
. Set the value of theEXAMPLE_ISSUER
env variable to the same. - ACS URL - Sometimes called the "SSO URL", this is the URL generated by the IDP for initiating SSO. Set the
EXAMPLE_SSO_URL
env var to this value. - Public Certificate - Copy the x509 public certificate provided by the IDP, and use it for the
EXAMPLE_IDP_PUBLIC_CERT
env variable.
We will configure the WorkOS side of things, which will be our "post-migration" state.
WORKOS_CLIENT_ID
andWORKOS_API_KEY
are obtained from the WorkOS dashboard, on the "API Keys" page.- In the WorkOS Dashboard, visit the Configuration page and add a new "Sign in callback". Its value will be your tunnel host combined with a
/workos/callback
path; i.e. ``https://7736-2001-871-216-2b68-69bd-a3bb-d4d6-af3f.ngrok-free.app/workos/callback`. Set theWORKOS_CALLBACK_URL
- In the WorkOS dashboard, create an organization representing one of your customers.
- Copy the Organization ID to the
EXAMPLE_WORKOS_ORGANIZATION_ID
env var - Under the "Single Sign On" feature, create a new connection matching the IDP you selected.
- Copy the ACS URL to the
EXAMPLE_WORKOS_CONNECTION_ACS_URL
env var
npm run dev
And visit your app via the ngrok tunnel.
In this example, the switch between signing in via passport-saml
and via WorkOS is controlled by a user input. In a real-world scenario, this should be determined by your app, such as by a feature flag.
First, sign in using only passport-saml. You should be presented with a login flow on the IDP, and returned to the example app, showing your email address.
Log out, and log in again, selecting "WorkOS SSO" as the method. You should again be logged in, but this time via WorkOS. You can view the authenticated sessions in the Sessions tab of the connection page in the WorkOS dashboard.