Single Sign-On

Auth Flow

Learn how to quickly ship universal SSO for your application by using WorkOS

To support SSO for multiple identity providers (IdPs) using WorkOS, configure a redirect URI to send your Enterprise Clients to after authentication, collect information from your Enterprise clients, such as their identity provider and respective X.509 Certificate, integrate the WorkOS package into your server-side application, and verify the status of the new connection in the Dashboard.

4 Step Integration

  1. Designate a redirect_uri within WorkOS.
  2. Create and configure your IdP Connections from your Dashboard or via WorkOS.js.
  3. Initiate authorization.
  4. Verify your application's authorization is up and running perfectly.

After completing these steps, your application will be equipped to perform the following authorization workflow:

Single Sign-On Authorization Flow

Configure a Redirect URI for Your Application

Step 1. Configure WorkOS

For quick, step-by-step instructions for configuring a redirect_uri, see the Redirect URI Guide.

A redirect_uri is an allowlisted callback URI inside of your application that WorkOS redirects the user to after they've authenticated with a given Identity Provider.

The redirect_uri is required, and must be selected as a default. If you don't provide a redirect_uri, your application's users will not be able to log in.

Set a default redirect_uri and add it to your allowlist in your Project's Single Sign-on Configuration tab.

Learn how to designate your redirect_uri with the Redirect URI Guide.

Step 2. Create and Configure Your Identity Provider Connection

Connections describe authentication configurations between you and your Enterprise clients that are necessary to implement Single Sign-on in your application.

You can create and configure a new connection using the WorkOS Dashboard, or allow your Enterprise client to initiate a new connection directly by embedding WorkOS.js.

Configure your first Connection with the SSO Connection Guide.

Step 3. Implement Authorization Workflow

Import the @workos-inc/node package into your server-side application. Then, configure an authorization URL to initiate an OAuth2 workflow, and a callback URL to retrieve the authorized user's profile:

app.js

file_copy
import express from 'express';
import WorkOS from '@workos-inc/node';
const app = express();
const port = 9000;

const client = new WorkOS('{secretKey}');
const domain = '{foo-corp.com}';
const redirectURI = '{redirectURI}';
const projectID = '{projectId}';

app.get('/login', (_req, res) => {
  const url = client.sso.getAuthorizationURL({
    domain,
    redirectURI,
    projectID,
  });

  res.redirect(url);
});

app.get('/callback', async (req, res) => {
  const { code } = req.query;
  const profile = await client.sso.getProfile({
    code,
    projectID,
  });

  res.json(profile).send();
});

app.listen(port, () => console.log(`https://workos.dev/login`));

Note: You can locate your project_id in your Single Sign-on Configuration tab.

Step 4. Verify Your Application's Authorization is Up and Running Perfectly

Your Connection should now be verified in the Dashboard, and you're ready to test your integration.

WorkOS provides test user accounts for an Okta instance belonging to the domain foo-corp.com. You can provision a test user in the Dashboard, and WorkOS will automatically create a Connection for the foo-corp.com domain.

Once you have your test user credentials, navigate to the /login path in the integration above. You'll be asked to log in to Okta with your foo-corp.com user, and will then be redirected back to your redirect_uri.

You should now be able to exchange the token in the code paramater for an authorized user profile for your foo-corp.com test user.

Congratulations! You've successfully authorized your first user with WorkOS SSO! Interested in learning what it takes to set up an SSO Connection with one of our supported IdPs? Check out one of the guides below: