Quick Start

Authenticate your first user via the Single Sign-On API.

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. A Connection represents the method by which a group of users (typically in a single organization) sign in to your application.

• Profile. A Profile is an object that represents an authenticated user. The Profile object contains information relevant to a user in the form of normalized and raw attributes.

1. Add SSO to your app

Let's start by building the SSO authentication workflow into your app.

Install the WorkOS SDK of your choice

WorkOS offers native SDKs in several popular programming languages. Install the SDK using the command below.

npm install @workos-inc/node

You can also download the workos-node source code from GitHub.

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.

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

Using Connection ID

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

const express = require('express');
const { WorkOS } = require('@workos-inc/node');
const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;
app.get('/auth', (_req, res) => {
  const connection =  // ... The Connection's ID
  const redirectURI =  // ... The callback URI WorkOS should redirect to post-authentication
  const authorizationURL = workos.sso.getAuthorizationURL({
    clientID: clientID,
    redirectURI: redirectURI,
    connection: connection,
  });
  res.redirect(authorizationURL);
});

Using Organization ID

Use the organization parameter when authenticating a user by their specific organization.

const express = require('express');
const { WorkOS } = require('@workos-inc/node');
const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;
app.get('/auth', (_req, res) => {
  const organization =  // ... The user's organization ID
  const redirectURI =  // ... The callback URI WorkOS should redirect to post-authentication
  const authorizationURL = workos.sso.getAuthorizationURL({
    organization,
    redirectURI,
    clientID,
  });
  res.redirect(authorizationURL);
});

Using provider

If your application isn't designed to pass back the connection ID or organization ID of the user logging in, for example a “Sign in with Google” button instead of a text input field for the user to provide their information, you can use the provider parameter.

const express = require('express');
const { WorkOS } = require('@workos-inc/node');
const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;
app.get('/auth', (_req, res) => {
  const provider =  // ... The provider to authenticate with
  const redirectURI =  // ... The callback URI WorkOS should redirect to post-authentication
  const authorizationURL = workos.sso.getAuthorizationURL({
    provider,
    redirectURI,
    clientID,
  });
  res.redirect(authorizationURL);
});

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.

const express = require('express');
const { WorkOS } = require('@workos-inc/node');
const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientID = process.env.WORKOS_CLIENT_ID;
app.get('/callback', async (req, res) => {
  const { code } = req.query;
  const { profile } = await workos.sso.getProfileAndToken({
    code,
    clientID,
  });
  // Use the information in \`profile\` for further business logic.
  res.redirect('/');
});

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

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

3. Configure an SSO Connection

you’ll need to configure an SSO Connection for every domain, i.e. organization, that wants to authenticate via SSO. Connections can be configured in the WorkOS Dashboard. Let's start by creating one for development in your Sandbox Project—get provider specific instructions by selecting the Identity Provider you’re planning to use from the list below.

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