Seamless onboarding with the WorkOS Admin Portal

Onboarding customer identity has traditionally been a time-consuming, resource-intensive process — one that only grows more complex with scale. As your company’s user base expands, so too does the challenge of managing identity provider connections quickly and efficiently.

Each new customer brings a unique setup, requiring precise coordination and significant IT resources to establish and maintain secure, compliant IdP configurations. WorkOS equips your customers with the tools they need to configure their own identity solutions, freeing up your team to focus on scaling confidently without sacrificing control or accuracy.

The Admin Portal is designed specifically for ease of customer onboarding. It allows developers to quickly create organizations for new clients and then email an invite or generate a shareable link to enable the client to configure their identity provider themselves. Gone are the days of messaging IT teams back and forth just to exchange information about the client’s identity provider.

‍

Prefect saved over 300 hours of onboarding time with WorkOS using the Admin Portal and here's what they had to say:

What sold WorkOS was the Admin Portal. Our UI gives customers a link; they go to the Admin Portal, complete onboarding steps at their leisure, and never have to talk to us, making the onboarding process a breeze. - Chris Pickett, Staff Engineer‍

‍

Self-Serve Identity Provider Onboarding

From the WorkOS dashboard, you can create a new client organization and share a setup link with their IT admin. We also offer the ability to programmatically generate these links, which we will talk about later in this blog. Through this link, the admin can access their organization’s portal to configure an identity provider, set up directory sync, enable log streams, and verify a custom domain—all without IT support from your team. We have made sure to embed guides for any of the providers in the list so that it’s as easy as possible for IT admins to get their IdP set up and their team access to your application. Is your client not using an IdP from the list? Not an issue: in addition to the list of IdP’s with guides, we also offer the ability to configure custom SAML and OIDC connections. Configuring an Identity Provider used to involve a fair amount of hassle as you would need to have a back and forth about configuration details with the client’s IT admin. With this portal, it’s as easy as sending them a link and letting them configure it themselves.To further assist with SSO onboarding, WorkOS also offers a Test Identity Provider to demonstrate the entire flow for users from start to finish. This allows your IT teams to simulate the entire SAML authentication flow and validate their configuration before ever going live. The Test Identity Provider is invaluable for troubleshooting and testing setups without impacting production environments or spinning up trial accounts with workforce identity providers for the sole purpose of testing. Additionally, x.509 certificate renewal is built directly in the WorkOS Dashboard, ensuring secure and continuous operation without manual intervention. Not only will we generate alerts for certificates expiring in the next 90 days, but we’ll automatically renew the certificate if a SAML metadata url has been provided with the connection.

‍

Configuring Directory Sync with Ease

‍Directory Sync is essential for enterprises, ensuring synchronized user access and enhanced security. With Directory Sync, IT teams configure access once, automatically reflecting updates across connected applications. This means users only have access to resources when approved and lose it immediately upon removal from directory. Similar to IdP onboarding, we offer a list of directory providers to choose from. Any provider on this list will have an embedded guide to help IT admins walk through the configuration of their directory sync. If they are using a directory provider that’s not in this list, they also have the ability to configure custom SCIM and SFTP directory connection. The WorkOS Dashboard also provides built-in tooling that allows IT admins to map roles to groups during the configuration process. This features is essential for enterprise environments, as it allows admins to assign roles based on directory groups and will automatically reflect these roles across synced applications as users get added to or removed from groups.

‍

Set up log streams

On top of managing users, the admin portal also unlocks the ability to configure log streams. Log streams allow WorkOS to integrate seamlessly with Security Incident and Event Management (SIEM) providers like Datadog or Splunk. Recognizing that many clients already have log-streaming services, we’ve made it easy for IT admins to integrate their pre-existing SIEM solution with WorkOS, ensuring all events logged in the dashboard also appear in their preferred service. That’s why, in addition to being able to view audit logs in the dashboard, IT admins can also configure their pre-existing log-streaming service to work with WorkOS. After configuration, every event that shows up in the audit logs will be sent to the SIEM as well.

‍

Configuring custom domains

Lastly, the admin portal gives IT admins the ability to configure a custom domain for their organization. Instead of exchanging DNS records through email, the Admin Portal empowers IT admins to complete domain verification independently. The portal provides specific TXT records and DNS configuration instructions, streamlining the setup for a custom-branded user experience that is immediately available for configuration when you open your sandbox environment for the first time.  We will generate the appropriate TXT record to supply your DNS with and display customized instructions specific to the DNS, if available. Simply provide your domain in the prompt, and we will display the appropriate guide for your use case based on the DNS provider that you used to configure your domain.

‍

A portal with real-world impact

The WorkOS admin portal smooths the onboarding experience, accelerates setup times, and reduces the support demands made by your clients’ IT teams. By enabling clients to self-manage essential configurations - from setting up identity providers to synchronizing directories - your teams can stay focused on high-priority initiatives and be confident that user management is handled seamlessly in the background.

Case study: Saving time with the WorkOS admin portal

Prefect, a workflow orchestration tool, needed a fast solution for SSO and user provisioning (SCIM) as their enterprise customer base grew. After evaluating options like Auth0 and FusionAuth, they chose WorkOS for its solid documentation and the self-serve Admin Portal.

Using the WorkOS Admin Portal, Prefect’s clients could set up SSO themselves, significantly reducing the time and effort for Prefect’s engineering team. This approach saved over 300 hours by simplifying the setup of 100+ SSO connections. Integrating with WorkOS took less than a week, and ongoing maintenance is minimal — about 1-2 hours per week. This allowed Prefect to provide a seamless onboarding experience for clients while keeping their team focused on core features.

Step-by-step onboarding with the WorkOS Admin Portal via API

In addition to generating admin portal invites via the WorkOS Dashboard, we offer the ability to generate links via api. To get started with generating Admin Portal links programmatically, you need to use the Single Sign-On or the Directory Sync APIs. Then follow these steps: 

1. Creating an organization via the API

An Admin Portal session is scoped to an organization, so the first step is to create one. You’ll need to provide a name and the list of domains that will allow you to log in.

Once an organization is created, you need to persist the returned organization ID since you’ll need to reference it when starting an Admin Portal session for that specific customer.

2. Generating an Admin Portal link via the API

 You have two options for sharing a link to the Admin Portal. They are:

• Share a link from the WorkOS dashboard

Follow these steps:

1. In the WorkOS Dashboard, find the “Invite Admin” button and click it.
2. Select the features you want to include in the setup — SSO, Directory Sync, or both.
3. Click “Next,” then either enter the IT admin's email to automatically send them the setup link or click “Copy setup link” to share it manually through email, Slack, or any other communication platform.

If you share the link manually, be sure to include a brief note explaining the link’s purpose and that it will be active for 30 days or until the setup is complete.

• Generate an Admin Portal link via the API

Use this method if you want to integrate the Admin Portal directly into your application. For example, you can add a button in your app that generates and opens the Admin Portal link automatically. 

To generate the link, you’ll need to provide the organization_id of the organization you want to associate with during the Admin Portal session.

Here’s an example showing how:

curl -X POST "https://api.workos.com/portal/generate_link" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "organization": "organization_id",
  "intent": "sso" // or "dsync" for Directory Sync
}'

Specify the intent field based on what you want the organization to configure. Use SSO for Single Sign-On setup or dsync  for Directory Sync setup. You can also include a return_url parameter if you want to specify where users should be redirected after completing the setup. If you don’t specify a return_url, the default one configured in the WorkOS dashboard will be used. For security reasons, generating a portal link through the API immediately starts a session that expires after 5 minutes. So, it’s recommended that users be redirected immediately (i.e., don’t email the portal links generated by the API). Suppose the session expires before completing the setup of an IdP/directory. In that case, a new link gets generated by the API, and the enterprise customer can go through the setup process again. Feel free to take a look at the example applications to learn more.

‍

3. Validating the configuration

There’s a validation step at the end where the enterprise customer can test if the connection works. If there are any issues during the setup, debugging steps will be displayed. If they would like to configure a different IdP/directory, they can reset the connection and go through the setup process again.

Best practices for enterprise onboarding

Here are some key practices to keep in mind:

Automation over manual setup: Automation enables you to handle a larger number of enterprise clients without compromising the quality of onboarding. Customizable user journeys: Allow enterprise clients to tailor onboarding experiences based on their specific IT infrastructure, existing systems, and security requirements. Offer a variety of onboarding options, such as self-service portals, guided walkthroughs, or dedicated onboarding teams. Clear documentation and guides: Providing detailed, easy-to-follow documentation helps IT admins understand how to set up integrations without needing constant support. Self-service portals: Offering a self-service portal like the WorkOS Admin Portal allows IT admins to handle configurations directly, making it easier for clients to set up SSO or Directory Sync at their convenience.

Empowering IT Teams

With the WorkOS Admin Portal, powerful user management tools are placed directly into the hands of IT teams. By offering an intuitive, self-service interface, the portal cuts down significantly on setup time by offering an intuitive, self-serve interface for everything from configuring identity providers to domain verification. For companies focused on growth and operational efficiency, the Admin Portal undercuts the typical friction experienced during onboarding by allowing IT admins to configure these features themselves. Want to save your team some time and money? Sign up today and start making authorization checks with WorkOS.