Admin Portal

A first-class, out-of-the-box Single Sign-On and Directory Sync onboarding and management experience for enterprise IT admins.

Introduction

The Admin Portal provides an out-of-the-box UI for IT admins to configure SSO and Directory Sync Connections. Designed to remove friction, custom walk-through documentation for each Identity Provider means that enterprise admins can onboard their orgs without high-touch support from your team. Easy to integrate and fully maintained and hosted by WorkOS, the Admin Portal makes the SSO and Directory Sync setup process simple, fast, and secure.

Workflow Options

There are two main workflows for initiating an Admin Portal session for IT admins. You can either share a link to Admin Portal from the WorkOS dashboard, or you can seamlessly integrate Admin Portal into your application through WorkOS SDKs or APIs.

If you intend to share a link to Admin Portal with IT admins, we recommend creating and sharing the link from the WorkOS Dashboard. Portal Links generated programmatically are only valid for 5 minutes and are not intended to be shared directly. However, links shared from the Dashboard last for up to 30 days.

Click one of the guides below for a walkthrough.

A

Share a link from the WorkOS Dashboard

B

Integrate with your app

If you’re interested in custom-labeling the Admin Portal, please reach out to WorkOS support.

Before getting started

To get the most out of these guides, you’ll need:

API Object Definitions

Object

Definition

Connection

A Connection represents the method by which an Enterprise’s users sign in to your application.

Organization

An Organization describes an Enterprise whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.

Portal Link

A Portal Link is a temporary link to initiate an Admin Portal session.

A

Setup Link from WorkOS Dashboard

The Admin Portal Setup Link gives your customer access to a guided configuration experience through our Admin Portal. It instructs them how to configure their Identity or Directory Provider. If successfully configured, no other action is required and you'll see an Active connection appear under the Organization.

First decide whether your customer will be configuring an Identity Provider, a Directory Provider OR both. Once you generate a link, the customer will have access for 30 days or until configured.

You'll need a WorkOS Dashboard account to create an organization that will represent the enterprise you are onboarding.

Create Organization

Sign in to your WorkOS Dashboard account and create a new Organization.

Click the button to generate a new Setup Link. Only one link can be active at a time for setting up SSO and the same for Directory Sync. After creating the initial link, you can click the button to regenerate the link to deactivate the existing link and create a new one.

You can share the link over email, Slack or direct message. We also recommend including details on what the link does and how long the link is active.

B

Integrate with your app

In this guide, we'll walk you through the full end-to-end integration of the Admin Portal into your application.

Sign in to your WorkOS Dashboard account to see code examples pre-filled with your test API keys and resource IDs.

Before integrating, you must first configure your app’s default redirect link in your Production Project. The default redirect link is where your Admin Portal users will be redirected once their session is complete, unless otherwise specified when generating an Admin Portal link. You can configure your redirect link in the Dashboard.

The redirect link must use HTTPS.

Choose and install a 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.

  • Node.js

    Node.js

  • Ruby

    Ruby

  • Go

    Go

  • Python

    Python

  • PHP

    PHP

  • Laravel

    Laravel

  • .NET

    .NET

  • Java

    Java

Request an SDK

Don't see an SDK you need? Contact us to request an SDK!


Admin Portal Example Application

Node.js Example Application

Command Line

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.

Environment Variables

WORKOS_API_KEY='
sk_example_123456789
'
WORKOS_CLIENT_ID='
client_123456789
'

Create a new Organization

Each Admin Portal session is scoped to a specific Organization resource, meaning a session is only capable of managing a Connection that belongs to its associated Organization. Organizations may only have one Connection.

For every Enterprise in your application that would like access to the Admin Portal, you must create an Organization and maintain a reference to its ID.

Create an Organization when onboarding a new Enterprise.

Create an Organization

1const express = require('express');
2const { WorkOS } = require('@workos-inc/node');
3
4const app = express();
5
6const workos = new WorkOS(process.env.WORKOS_API_KEY);
7
8app.post('/provision-enterprise', async (_req, res) => {
9 const organizationName = // ... The name of the Enterprise to provision
10 const organizationDomains = // ... The list of domains the Enterprise uses
11
12 const organization = await workos.organizations.createOrganization({
13 name: organizationName,
14 domains: organizationDomains,
15 });
16
17 // You should persist `organization.id` since it will be needed
18 // to generate a Portal Link.
19
20 // Provision additional Enterprise-tier resources.
21});

Redirect an IT admin to the Admin Portal

A Portal Link is your enterprise user’s gateway to accessing their Admin Portal. Each Portal Link is generated using an Organization resource ID. Only resources belonging to the specified Organization can be managed during a Portal Session.

In the API call to generate an Admin Portal Link, you will pass an intent with possible values of sso for an Admin Portal session to create an SSO connection, and dsync for an Admin Portal session to create a Directory Sync connection.

For security reasons, Portal Links expire 5 minutes after they’re created, so we recommend redirecting users immediately (i.e. don’t email the user Portal Links).

The endpoint that redirects a user to the Admin Portal should be guarded by auth in your application and only available to IT admins.

Redirect to Admin Portal

1const express = require('express');
2const { WorkOS } = require('@workos-inc/node');
3
4const app = express();
5
6const workos = new WorkOS(process.env.WORKOS_API_KEY);
7
8app.get('/admin-portal', async (_req, res) => {
9 const organizationID = // ... The ID of the organization to start an Admin Portal session for
10
11 const { link } = await workos.portal.generateLink({
12 organization: organizationID,
13 intent: "sso",
14 returnUrl: "https://www.example.com" //optional
15 });
16
17 res.redirect(link);
18});

An optional return_url parameter can be used to describe exactly where a user should be sent when they are finished in the Admin Portal. If one is not provided, the default redirect link configured in the Admin Portal Dashboard is used.

C

Using Admin Portal

In this guide, we'll review the features of Admin Portal from an IT manager's perspective.

Managing SSO Connections

On the Admin Portal SSO screen, you can view the identity provider details and connection status, metadata configuration details, and a list of recent connection events. You may test your SSO connection from the Admin Portal by using the Test Single Sign-On button.

You may also edit your metadata configuration from the Admin Portal.

The Recent Events section displays a list of recent connection events by timestamp, and can be sorted by state.

Click on an event in the list to see event details, such as the request made to the IdP, and the response.

If you wish to reset your SSO connection and set it up from scratch, select Reset Connection and follow the prompts.

Managing Directories

On the Admin Portal DSync screen, you can view the directory provider details and connection status, user and group counts, last sync time, and a full user list. Hover over the groups column for a particular user to see the list of groups they are in.

Get real-time updates with incoming webhooks

Subscribe your app to changes in Connections by registering incoming webhooks to receive Connection events.

There is currently no rate limiting on event deliveries.

Event Types

Build a webhook URL

Webhooks should use HTTPS and expect to receive POST requests with the following headers:

Key
Value
Content-Type
application/json
WorkOS-Signature
t=
${issued_timestamp}
, v1=
${signature_hash}

NOTE: WorkOS sends the header asWorkOS-Signature, but many web servers will normalize all HTTP request headers to their lowercase variants. In this case, you'll extract the workos-signature header.

See example approaches for implementing a webhook endpoint below.

Webhook endpoint

1const express = require('express')
2
3const app = express();
4
5app.use(express.json());
6
7app.post('/webhook', (req, res) => {
8 const payload = req.body;
9 const sigHeader = req.headers['workos-signature'];
10
11 // Verify the signature and process the event
12
13 res.status(200);
14});

Register the webhook

Set and save the webhook URL in the WorkOS Dashboard, so WorkOS knows where to deliver events.

The Webhook Secret is used to verify webhook requests from WorkOS. Be sure to keep the value secure.

Receive events

In order to avoid unnecessary retry requests hitting your webhook handler, we recommend using two concurrent processes for handling events: one for receiving the event, and the other for processing it.

Process A: Respond with HTTP 200 OK

On receiving an event, you should respond with an HTTP 200 OK to signal to WorkOS that the event was successfully delivered. Otherwise, WorkOS will consider the event delivery a failure and retry up to 12 times, with exponential backoff over 3 days.

Process B: Process the request

Before processing the request payload, verify the request was sent by WorkOS and not an unknown party.

WorkOS includes a unique signature in each webhook request that it sends, allowing you to verify the authenticity of the request. In order to verify this signature, you must obtain the secret that is generated for you when you set up your webhook endpoint in the WorkOS dashboard. Ensure that this secret is stored securely on your webhook endpoint server as an environment variable.

The WorkOS SDKs have methods for validating the timestamp and signature of a webhook. Examples using these methods are included below. The parameters are the payload (raw request body), the WorkOS-Signature header, and the Webhook Secret. There is an optional parameter, tolerance, that sets the time validation for the webhook in seconds. The SDK methods have default values for tolerance, usually 3-5 minutes.

Webhook validation

1import WorkOS from '@workos-inc/node';
2
3const workos = new WorkOS(process.env.WORKOS_API_KEY);
4
5const webhook = workos.webhooks.constructEvent({
6 payload: payload,
7 sigHeader: sigHeader,
8 secret: process.env.WEBHOOK_SECRET,
9});

If implementing webhook validation yourself, you'll need to use the following steps:

First, extract the timestamp and signature from the header. There are two values to parse from the WorkOS-Signature, delimited by a , character.

  1. issued_timestamp: The number of milliseconds since the epoch time at which the event was issued, prefixed by t=.
  2. signature_hash: The HMAC SHA256 hashed signature for the request, prefixed by v1=.

To avoid replay attacks, we suggest validating that the issued_timestamp does not differ too much from the current time.

Next, construct the expected signature. The expected signature is computed from the concatenation of:

  1. issued_timestamp
  2. The . character
  3. The request’s body as a utf-8 decoded string

Hash the string using HMAC SHA256, using the Webhook Secret as the key. The expected signature will be the hex digest of the hash. Finally, compare signatures to make sure the webhook request is valid.

Once you’ve determined the event request is validly signed, it’s safe to use the event, i.e. the request body, in your application’s business logic. You do not need to signal to WorkOS whether or not the event was processed successfully.

Go live checklist

Make sure you're ready to go live to production by going through this checklist.

  • Handle edge cases

    You may occasionally receive duplicate webhook events. To prevent duplicate processing of events, we suggest caching received events and implementing logic to skip processing seen events.

    Since webhook events may be delivered out of order, i.e. not in the order in which they were generated, be sure to handle accordingly. The issued_timestamp extracted from the WorkOS-Signature header can be used to determine order.

  • Register a production webhook URL in your Production Project.
  • Set and secure your Production Project's Webhook Secret.
  • Set and secure your Production Project's API key.
  • Ensure that your application can receive redirects and webhooks from WorkOS.

    Depending on your network architecture, you may need to allowlist incoming traffic from api.workos.com.

    WorkOS currently cannot promise that redirect and webhook traffic will originate from a static set of IP addresses.