Single Sign-On

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.

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!

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.

Install the SDK using the command below.

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.

WORKOS_API_KEY='{secretKey}'
WORKOS_PROJECT_ID='{projectID}'

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.

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 projectID = process.env.WORKOS_PROJECT_ID;

app.get('/callback', (_req, res) => {
  const { code } = req.query;

  const profile = await workos.sso.getProfile({
    code,
    projectID,
  });

  // 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.

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 projectID = process.env.WORKOS_PROJECT_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,
    projectID,
  });

  res.redirect(authorizationURL);
});