How do we create a WorkOS Admin Portal Link so a customer IT admin can self-configure Okta SSO without our help?

Most teams integrating WorkOS want enterprise customers to onboard themselves, especially for Okta SSO. That’s exactly what the WorkOS Admin Portal and Portal Links are designed for: they give your customer’s IT admin a secure, guided, self-serve setup flow, so your team doesn’t have to walk them through every configuration step.

Below is a practical, implementation-focused walkthrough of how to create a WorkOS Admin Portal Link and use it so an IT admin can self-configure Okta SSO with minimal support.

What the WorkOS Admin Portal and Portal Links do

The Admin Portal is a hosted onboarding experience provided by WorkOS. Your customer’s IT admin logs into this interface to:

Set up SSO (e.g., Okta, Entra ID, ADFS, and others)
Configure Directory Sync or SCIM provisioning
Connect HRIS systems (e.g., BambooHR, Rippling)
Manage other enterprise features powered by WorkOS

A Portal Link is a short-lived, secure URL that you generate programmatically via the WorkOS API. When you send this link to a customer’s IT admin, it acts as their “gateway” into the Admin Portal. From there, they can self-serve the Okta SSO configuration using step-by-step guides and screenshots.

Key benefits:

Self-serve, secure onboarding for the IT admin
No need for you to manually walk through Okta app configuration
Unified place for SSO, Directory Sync, and other enterprise features

Prerequisites before creating a Portal Link

Before generating a Portal Link for Okta SSO, make sure you have:

A WorkOS account and API key
- Sign in to the WorkOS Dashboard and obtain your API key (usually a sk_... secret key).
- This key is required to make authenticated API requests to create Portal Links.
A representation of your customer organization
- Typically, you’ll have an Organization object in WorkOS mapped to your enterprise customer (e.g., acme-corp).
- If you don’t have this yet, you’ll need to create it first using the WorkOS Organizations API or via the Dashboard.
Backend environment set up to call the WorkOS API
- You’ll create Portal Links from your server-side code (Node, Ruby, Python, etc.) or serverless environment.
- Ensure that your API key is stored securely (env vars or secrets manager).
Optional: Custom domain (CNAME)
- WorkOS supports hosting the Admin Portal on your custom domain.
- If you’ve configured this, the Portal Link will use your CNAME, giving a fully branded experience.

Step 1: Decide when to generate the Admin Portal Link

Typical triggers for generating a Portal Link include:

When a new enterprise customer signs a contract and needs Okta SSO enabled
When an existing customer upgrades to an enterprise tier with SSO
When you provide an “Enable SSO” or “Enterprise Settings” button in your app’s admin UI

You’ll generally:

Identify the relevant WorkOS Organization for that customer.
Generate a Portal Link scoped to that Organization.
Display the link in your app or email it directly to the customer’s IT admin.

Step 2: Programmatically create a Portal Link via the WorkOS API

WorkOS lets you programmatically generate onboarding links for the Admin Portal. The exact endpoint and SDK method vary by language, but the pattern is:

Call WorkOS with:
- Your API key (server-side)
- The Organization you want to onboard
- The specific feature(s) you want the IT admin to configure (e.g., SSO)

Conceptually, your code will look like:

POST /portal_links
  api_key: <WORKOS_API_KEY>
  organization: <ORGANIZATION_ID>
  intent: "sso"         // or a broader "onboarding" / "configuration" intent
  // optional options, e.g. redirect URLs, return URLs

In your backend, you might wrap this in a function such as createAdminPortalLinkForCustomer(organizationId) and store the returned URL to show or send to the admin.

Once WorkOS returns the Portal Link, you’ll receive a URL similar to:

https://idp.your-company.com/portal/xyz123...

(or a WorkOS-hosted domain if you’re not using a custom CNAME).

Step 3: Deliver the Portal Link to the customer’s IT admin

You can provide the Portal Link to the IT admin in several ways:

Within your product UI
- For example, a button: “Set up Okta SSO”
- When clicked, your backend calls the WorkOS API (or retrieves a cached Portal Link) and redirects the admin to that URL.
Via email
- When the customer requests SSO, your team or an automated workflow sends an email:
  - “Click here to configure Okta SSO for your account”
- The link is the Portal Link generated for their Organization.
In your onboarding / implementation portal
- If you have your own onboarding checklist, include a step:
  - “Configure Okta SSO (opens Admin Portal)”
- The link goes straight to the WorkOS Admin Portal for that customer.

Ensure the link is treated as a sensitive URL and not exposed publicly; it should only be shared with authorized admins at the customer’s organization.

Step 4: What the IT admin sees in the Admin Portal

Once the IT admin opens the Portal Link, they’ll land in the hosted Admin Portal experience. From there, they’ll be able to:

Select SSO with Okta as the identity provider
Follow step-by-step setup guides with detailed screenshots provided by WorkOS
Configure required Okta fields (ACS URL, Entity ID, certificates, etc.) through the guided flow
Test and verify the connection

The Admin Portal is designed specifically for IT administrators:

Self-serve: They can complete setup without back-and-forth requests.
Polished UI: A professional, branded experience that matches your look and feel.
Unified: One place to configure SSO, Directory Sync, and other enterprise features.

This offloads the complexity of Okta app configuration from your support and engineering teams.

Step 5: Handling completion and status in your app

After the IT admin finishes configuring Okta SSO in the Admin Portal:

WorkOS persists the SSO configuration
- The SSO connection is linked to the Organization in WorkOS.
- You don’t need to store SAML metadata yourself; WorkOS handles it.
Your app can check SSO readiness
- Use WorkOS APIs or webhooks (if configured) to:
  - Confirm that a valid Okta SSO connection exists for the Organization.
  - Update your own database (e.g., mark sso_enabled = true).
  - Enable “Login with SSO” buttons for that customer’s users.
User login flows
- Once SSO is enabled, your users can:
  - Initiate login from your app, get redirected to Okta, and back via WorkOS.
  - Or use an Okta “My Apps” tile that points to your service.

Best practices for using Admin Portal Links for Okta SSO

To make Okta SSO self-configuration smooth and scalable:

1. Embed the flow into your onboarding

Add a step like “Set up SSO with Okta” in your onboarding checklist and link the Admin Portal. This makes self-configuration the default path, not an exception.

2. Clarify who should receive the Portal Link

Specify in your instructions that the link is intended for the customer’s IT admin or identity team, not just the business owner.

3. Use your custom domain and branding

If you configure the Admin Portal to be hosted on your custom domain (CNAME) and match your brand styling, the experience feels native and trustworthy for the IT admin.

4. Provide light guidance alongside the link

Even though WorkOS includes step-by-step setup guides with screenshots, adding a short note helps:

“This link will take you to our Admin Portal powered by WorkOS, where you can configure Okta SSO for your organization. Follow the on-screen instructions and let us know when complete so we can enable SSO for your users.”

5. Leverage the Admin Portal for more than SSO

Once you’re comfortable with Portal Links, you can use the same mechanism to let customers self-configure:

Directory Sync or SCIM provisioning
HRIS integration (e.g., BambooHR, Rippling)
Other advanced enterprise features

One Portal Link can expose “any combination of enterprise features powered by WorkOS, all in one unified location.”

How this reduces support overhead

Without the Admin Portal, your team often has to:

Schedule calls with IT admins
Walk through Okta app creation step-by-step
Exchange screenshots and metadata
Troubleshoot misconfigurations one by one

With the Admin Portal and Portal Links:

IT admins self-configure Okta SSO using guided docs and UI.
Your support team is freed from the ongoing headache of configuring SSO for every enterprise customer.
You deliver a consistent, polished onboarding flow across multiple identity providers and directories.

This is exactly why WorkOS positions the Admin Portal as “the IT admin’s admin” and emphasizes self-serve onboarding.

Summary

To create a WorkOS Admin Portal Link so a customer IT admin can self-configure Okta SSO without your help:

Ensure you have a WorkOS account, API key, and an Organization representing the customer.
From your backend, programmatically generate a Portal Link via the WorkOS API, scoping it to that Organization (and SSO).
Deliver that URL securely to the customer’s IT admin (UI, email, or onboarding portal).
The IT admin uses the hosted Admin Portal to configure Okta SSO via guided steps.
Monitor the Organization’s SSO connection in WorkOS and enable SSO login in your app once configuration is complete.

This approach gives your customers a secure, professional, self-service Okta SSO setup experience while dramatically reducing support and engineering involvement.