The scenario: enterprise-sized deals require enterprise-level auth support
Your team has been growing your SaaS offering quickly, and your first big customer is ready to sign a six-figure annual contract, but they’ve got Okta as an identity provider (IdP) and they’ll only finalize the deal if your app will let their team use single sign-on (SSO).
For any developers who have implemented a SAML 2.0 workflow or other federated identity management manually in the past, the thought of adding SSO to a SaaS app might cause you to break into a cold sweat. I can remember spending days struggling to get it set up for a client project years ago — it was not a great experience.
But things have improved significantly in this space, and tools like WorkOS make adding SSO to a Node app a task that you can fit in before lunch. In this tutorial, we’ll add SSO powered by WorkOS, using Okta as an IdP.
Create a WorkOS organization and connect it to Okta as an identity provider
First, register or log in at https://workos.com.
Add a redirect URI
As part of the SSO flow, the user will be redirected to a URI that can exchange a temporary code for an auth token. For security, these redirect URIs need to be explicitly added to WorkOS.
In your WorkOS dashboard, click configuration in the left-hand nav, then add
http://localhost:3000/auth/sso/redirect as a redirect URI for local dev. You’ll need to come back to this page later to add more URIs for your other environments, such as staging and production.
Create an organization in WorkOS
Once logged in, click “Organizations” in the left-hand sidebar, then click the button to create a new one. Give your organization a name and add the domain(s) associated with users in your IdP.
On the organization home page, look for “Single Sign-On” under the Features section. Click “Configure”.
Choose Okta from the dropdown and give the connection a name (I chose “Okta”).
On the next screen you’ll see several URLs and configuration options. Keep this page open, then continue with the next section.
Create an application in Okta
Sign up or register for Okta. We’ll be using Okta as our Identity Provider (IdP), so our users’ data will be stored here, and we’ll use an app integration to allow WorkOS to manage the SSO flow.
In your account, navigate to Applications using the top-left menu.
Create a new app integration and choose SAML 2.0 as the sign-in method. Give the app a name, then click next.
Under SAML settings, add the ACS URL from WorkOS as the Single sign-on URL in Okta.
Next, add the SP Entity ID from WorkOS as the Audience URI in Okta.
Under attribute statements, map the four bits of user data we want for this app:
- id => user.id
- email => user.email
- firstName => user.firstName
- lastName => user.lastName
On the next screen, choose “I’m an Okta customer adding an internal app” and click Finish.
The next screen will be your Okta app settings, and under “SAML 2.0” you’ll see the “Metadata URL” — copy this, then head to your WorkOS organization. Under the URLs you copied before is a section called “Identity Provider Configuration”. Click “Edit Configuration”.
Paste in the metadata URL and save. Your connection will now show active!
Assign users to your app integration
In order to allow your users to log in via WorkOS SSO, you’ll need to assign the app to them in Okta. This is one of the major reasons companies choose SSO: it allows them to manage user access to all apps in a single location.
To do this, go to the Directory in the menu, then choose Groups. Select the Applications tab, then click “Assign applications” and choose the WorkOS SSO app you just created.
Set up your dev environment
Our starting point is a Node.js app built with Fastify, which is very similar to Express. There’s a home page that’s public, and a dashboard that requires the user to be logged in.
Clone the start branch of the repo to get started:
Add environment variables
Make a copy of
.env.EXAMPLE and rename it to
.env. Inside, add the following values.
SESSION_SECRET— a random value (I used a UUID generator to get one) used by the Fastify session plugin
REDIRECT_URI— this is pre-filled for development. If you change this, make sure it matches the value set as a redirect URI in your WorkOS organization
WORKOS_API_KEY— click “API Keys” in the left-hand nav of your WorkOS account and copy the secret key
WORKOS_CLIENT_ID— the client ID is displayed at the top of the API Keys screen in your WorkOS account
WORKOS_ORG_ID— head to your organization in the WorkOS dashboard and the organization ID will be displayed at the top of the org home page
Add a route to handle SSO login
src/app.ts, make the following changes:
@workos-inc/node package and our API key, this code registers a new route at
/auth/sso, which calls the
getAuthorizationUrl method. Using our client ID, organization ID, and redirect URI, this method generates a URL that will ask the user to log into their IdP (in this example, Okta).
Once the user has authenticated with their IdP, they’ll be redirected to the
redirectURI specified here.
Handle calls to the redirect URI
When a user has successfully authenticated with their IdP, they’ll be sent to the redirect URI with a
code that can be exchanged for an auth token.
To handle this exchange, add the redirect URI route in
Save, then navigate to
http://localhost:3000/auth/sso. You’ll be redirected to the Okta login. After signing in, you’ll end up on the app dashboard and your profile data will be logged in the console.
Log in with your Okta credentials and you’ll land on
http://localhost:3000/dashboard. This means the login flow is working, but our app isn’t checking for a logged in user yet or using that to restrict access to private pages.
Store user profile data in a session
To let the app display user data and prevent the user from needing to log in on every page navigation, let’s add the user’s profile data to a session cookie. In this app, we’ll use the
@fastify/session package, but the approach of storing the user data in a cookie will work in just about every framework.
To add support for sessions, bring in the required Fastify plugins in
src/app.ts and register them.
The required plugins allow our app to store data in a session, and we use that to store the user profile in the redirect handler after a user successfully logs in with their IdP.
On the home route (
/), we pass the user object from the session into the template, which will allow the app UI to be updated with logged in user data.
Only show the dashboard to logged in users
To use the SSO auth data to protect the authenticated area, make the following changes to the
/dashboard route in
Finally, to handle logout, all we need to do is destroy the session. Add a new route definition for
src/app.ts to handle logging out:
This will remove the user’s data from the session and send them back to the public home page. They’ll need to log in again to return to the dashboard.
Go land those big contracts!
Believe it or not, that’s it. Single sign on for enterprise customers used to be a nightmare, but the developer experience these days is actually pretty pleasant thanks to WorkOS.
So don’t let adding SAML 2.0 or other SSO solutions to your app be a blocker for your product to land larger customers. Happy building!