Single Sign-On
Add Single Sign-On (SSO) for all Identity Providers to your app with a single integration.
Introduction
Single Sign-On (SSO) is the most frequently asked for requirement by enterprise organizations looking to adopt new SaaS applications. SSO enables authentication via an organization’s Identity Provider (IdP), such as G Suite or Okta, as opposed to users or IT admins managing hundreds, if not thousands, of usernames and passwords. Facilitate greater security, easier account management, and accelerated application onboarding and adoption by adding SSO to your app.
The WorkOS SSO API is modeled to meet the OAuth 2.0 framework specification, abstracting away the underlying authentication handshakes between different IdPs. Check out the sequence of events below.
The WorkOS SSO API is authentication middleware and intentionally does not handle user database management for your application. This is by design, to minimize vendor lock-in for Developers.
Authentication Flow Diagram
Our SSO API is compatible with any Identity Provider and supports both the SAML and OpenID Connect protocols.

Don't see an Identity Provider you need? Contact us to request an Identity Provider!
What you’ll build
In this guide, we’ll take you from learning about Single Sign-On and POC-ing all the way through to authenticating your first user via the WorkOS SSO API.
Sign in to your Developer Dashboard account to see code examples pre-filled with your API keys and resource IDs.
This guide will show you how to:
Before getting started
To get the most out of this guide, you’ll need:
- A Developer Dashboard account.
- An IdP account from an Identity Provider that WorkOS supports. Reach out if you need help setting up an IdP instance for development.
API Object Definitions
1. Install the WorkOS SDK of your choice
WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.
Node.js
Ruby
Go
Python
PHP
Laravel
.NET
Don't see an SDK you need? Contact us to request an SDK!
Install the SDK using the command below.
Install the WorkOS SDK
npm install @workos-inc/node
2. Set environment variables
As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The Project ID should also be set dynamically based on the release environment.
Environment Variables
WORKOS_API_KEY='{secretKey}'
WORKOS_CLIENT_ID='{clientID}'
3. Add a callback endpoint
Let’s first add the redirect endpoint which will handle the callback from WorkOS after a user has authenticated with their IdP. This endpoint should exchange the authorization code (valid for 10 minutes) returned by WorkOS with the authenticated user’s Profile.
The redirect URI must use HTTPS.
Callback Endpoint
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
const express = require('express'); const WorkOS = require('@workos-inc/node'); const app = express(); const workos = new WorkOS(process.env.WORKOS_API_KEY); const clientID = process.env.WORKOS_CLIENT_ID; app.get('/callback', async (req, res) => { const { code } = req.query; const profile = await workos.sso.getProfile({ code, clientID, }); // Use the information in `profile` for further business logic. res.redirect('/'); });
4. Add an endpoint to initiate SSO
The endpoint to initiate SSO via the WorkOS API is responsible for simply handing off the rest of the authentication workflow to WorkOS. There are a couple configuration options shown below.
You can use the optional state
parameter to encode arbitrary information to help restore application state between redirects.
If you’re interested in custom-labeling the IdP sign-in screens, reach out to WorkOS support.
Use the domain
parameter when authenticating a user by their domain.
Authentication Endpoint
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
const express = require('express'); const WorkOS = require('@workos-inc/node'); const app = express(); const workos = new WorkOS(process.env.WORKOS_API_KEY); const clientID = process.env.WORKOS_CLIENT_ID; app.get('/auth', (_req, res) => { const domain = // ... The user's domain const redirectURI = // ... The URI WorkOS should callback to post-authentication const authorizationURL = workos.sso.getAuthorizationURL({ domain, redirectURI, clientID, }); res.redirect(authorizationURL); });
WorkOS will redirect to your Redirect URI if there is an issue generating an authorization URL. Read our API Reference for more details.
2
You should set a redirect URI (i.e. the callback endpoint from Add a callback endpoint) via the Developer Dashboard - be sure not to include wildcard subdomains or query parameters.

Multi-tenant apps will typically have a single redirect URI specified. You can set multiple redirect URIs for single tenant apps - just be sure to specify which redirect_uri
to use in the WorkOS client call to fetch the authorization URL.
In the IdP-initiated authentication flow, the default redirect URI is used.
3
An SSO Connection must be created for every domain, i.e. organization, that wants to authenticate via SSO. Connections can be created in the Connections Dashboard. Let’s create one for development in your Sandbox Project - get provider specific instructions by selecting which Identity Provider you want to connect to.
Add the WorkOS Admin Portal to your app to enable your users to create and configure SSO Connections themselves.
- AD FS SAML
- Azure SAML
- Generic SAML
- Google OAuth
- Google SAML
- Okta SAML
- OneLogin SAML
- PingFederate SAML
- PingOne SAML
- VMWare SAML
Connect to a Microsoft Active Directory Federation Services (AD FS) SAML server by reading through our integration guide below. It provides end-to-end instructions for creating your Connection in the WorkOS Developer Dashboard.
Our guide to creating a new Connection with AD FS SAML.
Once your Connection is successfully created and linked
, it’s ready to start being used to authenticate users!
Make sure you're ready to go live to production by going through this checklist.
Depending on your network architecture, you may need to allowlist incoming redirect traffic from api.workos.com
WorkOS currently cannot promise that redirect traffic will originate from a static set of IP addresses.
Here are some suggestions for taking your app to the next level in enterprise readiness.
- Integrate the WorkOS Admin Portal to enable your users to onboard and set up SSO themselves.
- If you're interested in getting listed in IdP app marketplaces such as the Okta Integration Network or the Azure AD Marketplace, reach out to us, we're happy to help!
- Integrate the WorkOS Directory Sync API for automatic user updating, provisioning, and deprovisioning.
How should an application handle the first time a user authenticates using WorkOS?
If a user is authenticating to your application for the first time via SSO and doesn't have an account, you can implement just-in-time provisioning to create a user when authentication is complete.
You can also leverage Directory Sync to pre-provision users with API endpoints or webhooks. In this case, the user will already be created in your application when they authenticate for the first time.
Can we add SSO authentication for a current user in an application?
If a user is authenticating to your application via SSO, but already has an account (with username/password for example), you can "upgrade" them to SSO. Usually the emails are the same for both methods of authentication, so you can match on email address. Once SSO via WorkOS is enabled, you can restrict users to sign-in with only SSO.
How does WorkOS manage user attributes from an identity provider?
WorkOS normalizes user attributes so you can expect known values such as id
, email
,firstName
, andlastName
. You will still recieve all of the attributes sent by your identity provider in the raw_attributes
object.
Is the user attribute mapping configurable in WorkOS?
Yes. For example, let's say the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
attribute contains the user email
rather than the surname
as the attribute name suggests. In these edge cases, WorkOS will identify any attributes that are misconfigured and recommend correct mapping in the Attribute Mapper
section of the Connection info
page.
What does "There are 0 profiles awaiting reconciliation" refer to?
This refers to the number of user profiles that have inconsistent attribute mappings, and that need to be updated in order to successfully authenticate.
For IdP-initiated SSO, what should the RelayState be?
We currently don't support theRelayState
parameter for IdP-initiated SSO, so this should be left blank.
When submitting an integration to the Okta Integration Network (OIN), how should the questions regarding SAML integration be answered when using WorkOS SSO?
- Q: Do you support SAML JIT provisioning? A: No
- Q: Do you support receiving SAML user/group attribute statements? A: Yes
- Q: Can one tenant connect to multiple identity providers? A: No
- Q: What type of sign in flows are supported? A: IdP and SP initiated
- Q: Force authentication? A: No
- Q: Do you support SP initiated logout? A: No
- Q: Do you require a default relay state? A: No
- Q: Is your application capable of requesting other SSO URLS? A: No
- Q: What is the unique SAML identifier for authentication? A: NameID
- Q: Does your ACS URL vary per tenant? A: Yes