Single Sign-On

Facilitate greater security, easier account management, and accelerated application onboarding and adoption.

Introduction

Single Sign-On (SSO) is the most frequently asked for requirement by organizations looking to adopt new SaaS applications. SSO enables authentication via an organization’s Identity Provider (IdP).

This service is compatible with any IdP and supports both the SAML and OIDC protocols. It’s modeled to meet the OAuth 2.0 framework specification, abstracting away the underlying authentication handshakes between different IdPs.

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.

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.

Before getting started

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

API object definitions

Connection: The method by which a group of users (typically in a single organization) sign in to your application.
Profile: Represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.

1. Configure an SSO Connection

Let’s start by configuring an SSO Connection for every domain, i.e. organization, that wants to authenticate via SSO. Connections can be configured in the WorkOS Dashboard. You can create one for development in your Sandbox Project.

Get provider-specific instructions by selecting the Identity Provider you’re planning to use:

Okta

Configure a connection to Okta via SAML.

Azure AD

Configure an Azure AD SAML connection.

Google Workspace

Configure a Google Workspace SAML connection.

View all integrations

Choose from dozens of Identity Providers.

Once your Connection is successfully created and active, it’s ready to start being used to authenticate users!

Add the WorkOS Admin Portal to your app to enable your users to create and configure SSO Connections themselves.

2. Add SSO to your app

Let’s build the SSO authentication workflow into your app.

Install the WorkOS SDK

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

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

Environment Variables

cURL

 WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

Add an endpoint to initiate SSO

The endpoint to initiate SSO via the WorkOS API is responsible for 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.

Use the connection parameter when authenticating a user by their Connection ID.

 import type { NextApiRequest, NextApiResponse } from 'next';
import WorkOS from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;

export default (_req: NextApiRequest, res: NextApiResponse) => {
  // A WorkOS Connection ID
  const connection = 'connection_123';

  // The callback URI WorkOS should redirect to after the authentication
  const redirectURI = 'https://dashboard.my-app.com';

  const authorizationUrl = workos.sso.getAuthorizationURL({
    connection,
    clientID,
    redirectURI,
  });

  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.

Add a callback endpoint

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.

 import type { NextApiRequest, NextApiResponse } from 'next';
import WorkOS from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;

export default async (req: NextApiRequest, res: NextApiResponse) => {
  const { code } = req.query;

  const { profile } = await workos.sso.getProfileAndToken({
    code,
    clientID,
  });

  // Use the information in `profile` for further business logic.

  res.redirect('/');
};

3. Configure a redirect URI

You’ll need to set a redirect URI (i.e. the callback endpoint from Add a callback endpoint) via the WorkOS Dashboard – be sure not to include wildcard subdomains or query parameters.

Wildcard characters in Redirect URIs are supported in Staging environments. More information can be found in the Wildcard Redirect URIs documentation.

Multi-tenant apps will typically have a single redirect URI specified. You can set multiple redirect URIs for single tenant apps – you'll need to be sure to specify which redirect_uri to use in the WorkOS client call to fetch the authorization URL.

IdP-initiated SSO

Since you do not use the WorkOS client to start IdP-initiated authentication flows, you will not be able to specify a separate redirect URI for each session. Instead, you can configure the redirect URI to be used for all IdP-initiated sessions via a redirect_uri parameter in the IdP's default RelayState. Without it, users will be automatically redirected to the default redirect URI. Learn more about configuring IdP-initiated SSO in Login Flows.

Example AppsView sample Single Sign-On apps for each SDK

Up next