Admin Portal

The Admin Portal provides an out-of-the-box UI for IT contacts to verify domains, configure SSO and Directory Sync connections, and more. Designed to remove friction, custom walk-through documentation for each identity provider means that IT contacts can onboard their organizations without high-touch support from your team. Easy to integrate and fully maintained and hosted by WorkOS, the Admin Portal makes Domain Verification, SSO, and Directory Sync setup simple, fast, and secure.

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

If you want to provide IT contacts with a link to the Admin Portal, in an email for example, then you would need to create that link in the WorkOS dashboard.

However, if you are adding a button to open the Admin Portal from within your application, then you would need to use the API.

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

• A WorkOS account

Connection

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

Organization

Describes an organization whose users sign in with an 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 verify a domain, configure their identity or directory provider, and more. If successfully configured, no other action is required and you’ll see verified domains and/or active connections appear under the organization.

First decide whether your customer will be configuring Domain Verification, Single Sign-On, Directory Sync, Log Streams, or all of the above. 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 “Invite IT contact” button, select the features to include and then click “Next.” Enter the email of the IT contact for the organization to automatically send them a setup link, or click “Copy setup link.” Only one link can be active at a time. After creating the initial link, you can click the “Manage” button to revoke the existing link before creating a new one.

If you chose to copy the setup link you can share it 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.

To integrate Admin Portal, configure a logo redirect URL in the production environment. The logo in Admin Portal uses this value to send users to your app unless you specify a return_url when generating the Admin Portal link.

You can also configure success URLs for Single Sign-On, Directory Sync, Log Streams, and Domain Verification setup flows.

Configure these links on the Admin Portal page in the dashboard.

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

npm install @workos-inc/node

yarn add @workos-inc/node

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as WORKOS_API_KEY and WORKOS_CLIENT_ID, and pass them to the SDKs either as environment variables or directly in your app’s configuration based on your preferences.

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 = [
      {
        domain: 'foo-corp.com',
        state: 'pending',
      },
    ];

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

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

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

const express = require('express');
const { WorkOS } = require('@workos-inc/node');

const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);

app.post('/provision-enterprise', async (_req, res) => {
  const organizationName = 'Example Organization';
  const organizationDomains = [
    {
      domain: 'foo-corp.com',
      state: 'pending',
    },
  ];

  const organization = await workos.organizations.createOrganization({
    name: organizationName,
    domainData: 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 the Admin Portal, where they can set up and manage resources scoped to their organization. To generate a Portal link using the API, you must provide the organization ID and specify one of the following intents: sso, dsync, audit_logs, log_streams, domain_verification, or certificate_renewal.

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';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

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.adminPortal.generateLink({
    organization: organizationId,
    intent: 'sso',
  });

  res.redirect(link);
};

const express = require('express');
const { WorkOS } = require('@workos-inc/node');

const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);

app.get('/admin-portal', async (_req, res) => {
  // The ID of the organization to start an Admin Portal session for
  const organizationId = 'org_123';

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

  res.redirect(link);
});

The optional return_url parameter controls where an admin is sent when they click your logo. The optional success_url parameter controls where an admin goes after setup. Values set when generating a Portal link override the defaults configured on the Admin Portal page in the dashboard.

When generating a Portal link via the API, emails can be added as IT contacts for the organization at the same time by passing the optional it_contact_emails parameter. This mirrors the behavior of the “Invite IT contact” flow in the WorkOS dashboard. IT contacts receive future organization notifications, such as alerts for expiring SSO certificates.

curl --request POST \
  --url "https://api.workos.com/portal/generate_link" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d '{
    "organization": "org_01EHZNVPK3SFK441A1RGBFSHRT",
    "intent": "sso",
    "it_contact_emails": ["it-contact@example.com", "it-lead@example.com"]
  }'

Any email that isn’t already an IT contact for the organization will be added; existing IT contacts remain unchanged, so the same call can be made repeatedly with the full list of contacts without creating duplicates. Email matching is case-insensitive.

An organization can have up to 20 IT contacts at a time. A request that would exceed this limit is rejected and no IT contacts from the request are created. Invalid email addresses are rejected without creating any IT contacts.

Adding an email via it_contact_emails does not restrict who can use the Portal link, and it does not send a notification to the IT contact. The Portal link must still be delivered by the calling application – typically by redirecting the current authenticated user immediately.

See the Generate a Portal Link reference for the full request schema.

During Admin Portal setup for SSO and Directory Sync, you can require an IT contact email. That address receives alerts such as certificate expiration warnings and connection errors.

New environments have this setting enabled. Environments created before the feature shipped need to enable it on the Admin Portal page.

When the setting is enabled, Admin Portal setup includes a required step to collect an IT contact email if the organization has no IT contact yet. When it is disabled, the step is skipped.

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

In the Admin Portal Domain Verification flow, you can view instructions on adding a DNS TXT record to prove ownership of your organization’s domain(s).

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 sessions. You may test your SSO connection from the Admin Portal by using the “Test sign-in” button.

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

The Sessions section displays a list of recent sessions by timestamp, and can be sorted by state.

Click on a session in the list to see session 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 Directory Sync screen, you can view the directory provider details and connection status, user and group counts, and last sync time. There is also an option to reset the directory.

You may also view and edit the attribute map from the synced directory by clicking “Edit Attribute Map”.

If you wish to update the groups that are being synced, select “Edit groups sync” and follow the prompts on the next page.

You can also view a complete list of users from all selected groups in your synced directory.