Single Sign-On

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 Google Workspace 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 acts as authentication middleware and intentionally does not handle user database management for your application. This is by design, to minimize vendor lock-in for Developers.

Our SSO API is compatible with any Identity Provider and supports both the SAML and OpenID Connect protocols.

Request an Identity Provider

Don't see an Identity Provider you need? Contact us to request an Identity Provider!

WorkOS makes use of Cloudflare to ensure security and reliability of all operations. If you are looking to create a list of allowed IP addresses for incoming requests, you can use the IP Ranges listed in the Cloudflare documentation.

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 WorkOS account to see code examples pre-filled with your API keys and resource IDs.

This guide will show you how to:

To get the most out of this guide, you’ll need:

• A WorkOS account.
• An IdP account from an Identity Provider that WorkOS supports. Reach out if you need help setting up an IdP instance for development.

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

Install the SDK using the command below.

npm install @workos-inc/node

As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The SDK is able to read the key automatically if you store it in an environment variable named WORKOS_API_KEY; otherwise, you will need to set it manually. The Client ID should also be set dynamically based on the release environment.

WORKOS_API_KEY='
sk_example_123456789
'
WORKOS_CLIENT_ID='
client_123456789
'

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.

1const express = require('express');
2const { WorkOS } = require('@workos-inc/node');
3
4const app = express();
5
6const workos = new WorkOS(process.env.WORKOS_API_KEY);
7const clientID = process.env.WORKOS_CLIENT_ID;
8
9app.get('/auth', (_req, res) => {
10  const connection =  // ... The Connection's ID
11  const redirectURI =  // ... The callback URI WorkOS should redirect to post-authentication
12
13  const authorizationURL = workos.sso.getAuthorizationURL({
14    clientID: clientID,
15    redirectURI: redirectURI,
16    connection: connection,
17  });
18
19  res.redirect(authorizationURL);
20});

WorkOS will redirect to your Redirect URI if there is an issue generating an authorization URL. Read our API Reference for more details.

Next, let’s add the redirect endpoint which will handle the callback from WorkOS after a user has authenticated with their Identity Provider. 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.

1const express = require('express');
2const { WorkOS } = require('@workos-inc/node');
3
4const app = express();
5
6const workos = new WorkOS(process.env.WORKOS_API_KEY);
7const clientID = process.env.WORKOS_CLIENT_ID;
8
9app.get('/callback', async (req, res) => {
10  const { code } = req.query;
11
12  const { profile } = await workos.sso.getProfileAndToken({
13    code,
14    clientID,
15  });
16
17  // Use the information in `profile` for further business logic.
18
19  res.redirect('/');
20});

IdP-initiated authentication is inherently more exposed to security vulnerabilities since the IdP delivers an SSO response to the Service Provider that the Service Provider had not initiated. There is no way for the application to definitively determine that these unsolicited responses have not been issued or compromised by an attacker, which exposes IdP-initiated SSO to potential CSRF Login and other "man-in-the-middle" attacks. As a result, WorkOS recommends using SP-initiated authentication whenever possible.

The instructions in this guide will allow the Identity Provider to issue IdP-initiated SSO calls to your application's callback endpoint. IdP administrators can configure the RelayState that the IdP will send with these requests. Currently, however, WorkOS does not support processing a RelayState for IdP-initiated authentication flows, so it should be left blank. If a RelayState is received, the request will result in an error. Upon a successful request, the user will be redirected to the default redirect URI in the WorkOS configuration.

We have recently added Beta support for reading the redirect_uri from the RelayState during an IdP-initiated SSO request. This allows an IdP administrator to configure the location where user will be redirected after a successful IdP-initiated authentication request. WorkOS will retrieve the redirect URI from the IdP's RelayState, where it must be configured in the format of a URL parameter: redirect_uri=[uri]. The URI must be one of the Redirect URIs specified in your WorkOS Dashboard, otherwise, the request will result in an error. Any other values in the IdP's RelayState will be ignored and discarded.

RelayState support for IdP-initiated authentication is currently behind a feature flag, please reach out to WorkOS support if you'd like to use it or learn more about it.