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

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

Connection

Represents the method by which users of an organization sign in to your application.

Organization

Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.

Portal Link

A temporary link to initiate an Admin Portal session.

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.

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

Click the “Generate” button, select the features to include and then click “Next” to create a new Setup Link. Only one link can be active at a time. After creating the initial link, you can click the “Revoke” button to deactivate the existing link before creating 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.

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

In order to integrate, you must configure your app's default return URI in the production environment. A button in the Admin Portal will use this value to allow users to return to your app unless otherwise specified when generating the Admin Portal link.

Additionally, you can configure success URIs to redirect users upon successfully setting up Single Sign-On, Directory Sync, or Log Streams.

You can configure these links in the Dashboard.

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

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'

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 customer in your application that would like access to the Admin Portal, you must create an Organization and maintain a reference to its 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 async (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    const organizationName = 'Example Organization';
    const organizationDomains = 'example.com';

    const organization = await workos.organizations.createOrganization({
      name: organizationName,
      domains: organizationDomains,
    });

    // You should persist `organization.id` since it will be needed
    // to generate a Portal Link.

    // Provision additional Enterprise-tier resources.
  }
};

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

import type { NextApiRequest, NextApiResponse } from 'next';
import WorkOS from '@workos-inc/node';

export default async (_req: NextApiRequest, res: NextApiResponse) => {
  // The ID of the organization to start an Admin Portal session for
  const organizationId = 'org_123';

  const { link } = await workos.portal.generateLink({
    organization: organizationId,
    intent: 'sso',
  });

  res.redirect(link);
};

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.

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

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.

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.