Admin Portal

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.

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.

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

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

• A WorkOS account.

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

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.

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});

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.

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.

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.

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.

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.