Single Sign-On

Add Single Sign-On to your application using the WorkOS SSO API.

What you’ll build

In this guide, you’ll add Single Sign-On to your application using the standalone WorkOS SSO API. By the end, you’ll have a working SSO integration that you can test with the built-in Test Identity Provider.

For a complete authentication platform that includes SSO, see AuthKit. To understand how SSO works, see How Single Sign-On Works.

Before getting started

Make sure you have:

A WorkOS account
A local app to integrate SSO with

Reference these example apps as you follow this guide.

1. Add SSO to your app

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 secrets

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app’s configuration.

Environment variables

 WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

The code examples use your staging API keys when signed in

Add an endpoint to initiate SSO

Create an endpoint that hands off the authentication workflow to WorkOS. There are a couple of configuration options shown below.

Use the optional state parameter to encode arbitrary information to help restore application state between redirects.

Use the organization parameter when authenticating a user by their specific organization. This is the preferred parameter for SAML and OIDC connections.

The example below uses the Test Organization available in your staging environment, which uses a mock identity provider. It allows testing your SSO integration without setting up an account with a real identity provider.

 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) => {
  // Use the Test Organization ID to get started. Replace it with
  // the user’s real organization ID when you finish the integration.
  const organization = 'org_test_idp';

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

  const authorizationUrl = workos.sso.getAuthorizationUrl({
    organization,
    redirectUri,
    clientId,
  });

  res.redirect(authorizationUrl);
};

Use the connection parameter for SAML or OIDC connections 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);
};

Use the provider parameter for OAuth connections configured at the environment level.

The supported provider values are GoogleOAuth, MicrosoftOAuth, GitHubOAuth, and AppleOAuth.

 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) => {
  // The provider to authenticate with
  const provider = 'GoogleOAuth';

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

  const authorizationUrl = workos.sso.getAuthorizationUrl({
    provider,
    redirectUri,
    clientId,
  });

  res.redirect(authorizationUrl);
};

If there is an issue generating an authorization URL, WorkOS returns the redirect URI as-is. See the API Reference for more details.

Add a callback endpoint

Add a redirect endpoint to handle the callback from WorkOS after a user has authenticated with their identity provider. This endpoint exchanges the authorization code returned by WorkOS for the authenticated user’s profile. The authorization code is valid for 10 minutes.

 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 Test Organization ID to get started. Replace it with
  // the user’s real organization ID when you finish the integration.
  const organization = 'org_test_idp';

  // Validate that this profile belongs to the organization used for authentication
  if (profile.organizationId !== organization) {
    return res.status(401).send({
      message: 'Unauthorized',
    });
  }

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

  res.redirect('/');
};

Always validate the returned profile’s organization ID. Validating by email domain is unsafe, as organizations may allow email addresses from outside their corporate domain (e.g. for guest users).

2. Configure a redirect URI

Go to the Redirects page in the dashboard and configure the allowed redirect URIs. Use the callback endpoint from the previous section.

Multi-tenant apps typically have a single redirect URI. For single-tenant apps, set multiple redirect URIs and specify which one to use in the WorkOS client call to fetch the authorization URL.

For more on wildcard characters in redirect URIs, see the Redirect URIs guide.

Identity provider-initiated SSO

By default, the default redirect URI configured in the WorkOS dashboard is used for all identity provider-initiated SSO sessions, since the WorkOS client is not used to initiate the authentication flow.

Customers can specify a separate redirect URI for their IdP-initiated sessions as a RelayState parameter in the SAML settings on their side.

Learn more about configuring IdP-initiated SSO in the Login Flows guide.

3. Test end-to-end

The Test Organization in your staging environment uses a mock identity provider, allowing you to test the integration end-to-end without a real IdP.

Go to the Test SSO page in the WorkOS Dashboard to test common login flows. See the Test SSO guide for more detail.

Test SSOLearn how to test your Single Sign-On integration end-to-end.

Up next