https://github.com/workos/passport-saml-migration-example
An example Node app with migration code from `passport-saml` to WorkOS
https://github.com/workos/passport-saml-migration-example
Last synced: about 1 year ago
JSON representation
An example Node app with migration code from `passport-saml` to WorkOS
- Host: GitHub
- URL: https://github.com/workos/passport-saml-migration-example
- Owner: workos
- Created: 2023-09-26T01:46:09.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-29T09:36:27.000Z (about 2 years ago)
- Last Synced: 2025-04-02T20:50:18.492Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 182 KB
- Stars: 0
- Watchers: 6
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# `passport-saml` Migration Example
This example demonstrates a migration path from a custom SSO implementation running on `passport-saml` to a SSO implementation to WorkOS.
## Try it
#### 1. Clone the repo and install dependencies
```
git clone https://github.com/workos/passport-saml-migration-example.git
cd passport-saml-migration-example
npm i
```
#### 2. Establish a tunnel
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.
#### 3. Set up a demo IDP, and configure the example app accordingly
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](https://workos.com/docs/sso).
**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 the `EXAMPLE_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.
#### 4. Create a Configure WorkOS settings
We will configure the WorkOS side of things, which will be our "post-migration" state.
- `WORKOS_CLIENT_ID` and `WORKOS_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 the `WORKOS_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
#### 4. Run it
```
npm run dev
```
And visit your app via the ngrok tunnel.
#### 5. Sign in via passport-saml
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.
#### 6. Sign in via WorkOS
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.