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

For most engineering teams, the ideal Okta SSO onboarding flow is one where your customer’s IT admin can complete setup without needing a single back-and-forth email with your support or sales team. With WorkOS, this is exactly what the Admin Portal and Portal Links are designed to do.

Below is a practical walkthrough of how to create a WorkOS Admin Portal Link so an IT admin can self-configure Okta SSO for their organization, plus tips to make the experience smooth inside your own product.

---

What the WorkOS Admin Portal and Portal Links do

The WorkOS Admin Portal is a hosted interface specifically built for IT administrators. Instead of you guiding every customer through SSO configuration, you give them a secure link to the Admin Portal and they:

• Configure Okta SSO (and optionally Directory Sync, SCIM, HRIS, etc.)
• Follow step‑by‑step setup guides with detailed screenshots
• Complete onboarding at their own pace, without needing your team’s help

A Portal Link is the secure, programmatically generated URL that grants an IT admin access to this Admin Portal for their organization. You create one link per customer (or per onboarding session) and surface it in your app or via email.

---

Prerequisites before creating an Admin Portal Link

Before you generate a Portal Link, make sure you’ve covered a few basics:

1. WorkOS account and API key

   • Sign up for WorkOS and obtain your API key from the WorkOS Dashboard.
   • Use the appropriate key (test vs. production) depending on your environment.

2. An organization record in WorkOS

   • Each Portal Link is associated with a specific organization.
   • You’ll typically create a WorkOS Organization that maps to your customer’s tenant/account.

3. SSO feature enabled in your WorkOS project

   • Ensure SSO is enabled in the WorkOS Dashboard.
   • Confirm that your Okta SAML or OIDC configuration is supported for your use case.

Once these are in place, you’re ready to generate a Portal Link.

---

Step-by-step: Create a WorkOS Admin Portal Link

The core flow is:

1. Create (or look up) the customer’s WorkOS Organization.
2. Call the WorkOS API to create an Admin Portal Link for that organization.
3. Deliver the link to the customer IT admin and direct them to configure Okta SSO.

1. Create or retrieve the WorkOS Organization

In your backend, you’ll usually:

• Create a WorkOS Organization when a new enterprise customer is added in your system, or
• Reuse an existing Organization if one already exists for that customer.

You’ll end up with an organization_id from WorkOS, which you’ll need to generate the Portal Link.

Example (conceptual flow):

// Pseudo-code: create or fetch organization
organization = workos.organizations.getOrCreate({
  name: "Acme Corp",
  domains: ["acme.com"]
})

// Save organization.id in your database associated with this customer

The exact code will vary by SDK (Node, Python, Ruby, etc.), but the idea is the same: you must have organization.id for the next step.

2. Generate an Admin Portal Link via the WorkOS API

Once you have the organization ID, you can create a Portal Link programmatically. This Portal Link grants secure access to the WorkOS Admin Portal for that specific organization.

Conceptually:

portalLink = workos.portalLinks.create({
  organization: organization.id,
  intent: "sso" // or more comprehensive onboarding, depending on your config
})

// portalLink.url is the Admin Portal Link you’ll send to the IT admin

Notes:

• The API accepts the organization identifier and returns a URL.
• The intent parameter can be used to tailor the experience (e.g., SSO, Directory Sync, or a combination) depending on your integration.
• You can generate multiple Portal Links over time for the same organization (for example, if a new admin needs access).

3. Send the Portal Link to the customer IT admin

Once your backend receives portalLink.url, you can expose it to the customer:

• In-app experience:
  • Place a button like “Configure SSO with Okta” on your settings or security page.
  • On click, your server generates (or retrieves) a Portal Link and redirects the user to portalLink.url.
• Email-based flow:
  • When an enterprise account is created, email the IT contact with a “Set up Okta SSO” link that points to the Portal Link.
• Sales/CS handoff:
  • Your team can generate the link from an internal tool and share it with the IT admin.

From the IT admin’s perspective, they just click your link and land in the Admin Portal, where they’re guided through Okta SSO setup with a polished, branded experience.

---

What the IT admin sees when they open the Portal Link

The WorkOS Admin Portal is built for IT admins and security teams, so they get a familiar enterprise-grade experience:

• Guided Okta SSO configuration
  • Step-by-step instructions tailored for Okta
  • Detailed screenshots and forms to capture required metadata
• Your branding
  • You can customize the look and feel to match your brand.
  • You can host the portal on your custom domain (CNAME) so the experience feels native.
• Unified enterprise features
  • The same portal can configure SSO, Directory Sync, SCIM Provisioning, HRIS integration, and more, all in one place if you’ve enabled those features.

Because the Admin Portal is self-serve, your team doesn’t need to manually walk each customer through Okta configuration. The admin completes the steps at their own pace and you automatically benefit from the resulting configuration via WorkOS.

---

Embedding this flow in your product UX

To make self-serve Okta SSO configuration feel seamless:

1. Add a clear entry point

   • Example: a “Single Sign-On (SSO)” section on your security/settings page with a primary CTA “Set up Okta SSO.”
   • When clicked, your backend:
     • Looks up or creates the WorkOS Organization
     • Creates a Portal Link
     • Redirects the user to the portalLink.url

2. Handle states gracefully

   • If SSO is already configured for the organization, you might:
     • Show status: “Okta SSO is configured”
     • Offer a smaller button: “Manage SSO settings” that still opens the Admin Portal for adjustments.

3. Secure who can access the Admin Portal

   • Only show or email the Portal Link to verified admins on your side (e.g., account owners, IT contacts).
   • Don’t store the Portal Link URL permanently if you don’t need to; you can generate fresh links as needed.

4. Use environments correctly

   • In development and staging, use test API keys and test organizations.
   • In production, switch to live keys and production organizations to keep setups cleanly separated.

---

Why use a WorkOS Admin Portal Link for Okta SSO setup?

Implementing SSO yourself often leads to:

• Complex, one-off configuration per IdP
• Time-consuming support tickets for every enterprise deal
• Fragile internal tools for collecting SAML metadata or certificates

By generating an Admin Portal Link instead:

• IT admins self-serve
  They follow WorkOS’s guided Okta setup with no bespoke documentation on your side.

• Your team stays out of the weeds
  Support and engineering don’t need to coordinate every certificate or redirect URL.

• You expand your enterprise readiness
  Once SSO is working through the portal, it’s straightforward to layer on Directory Sync, SCIM Provisioning, and HRIS integrations using the same Admin Portal.

The Admin Portal effectively becomes your “IT admin’s admin,” letting you offer a polished, enterprise-ready experience out of the box.

---

Summary

To let a customer IT admin self-configure Okta SSO without your help:

1. Create or fetch a WorkOS Organization for the customer and store its organization.id.
2. Use the WorkOS API to create an Admin Portal Link for that organization.
3. Expose the Portal Link in your product or via email so the IT admin can open the WorkOS Admin Portal.
4. Let WorkOS handle the guided Okta SSO setup, branding, and ongoing configuration management.

With this pattern in place, every new enterprise customer can onboard with a secure, self-serve Admin Portal experience, dramatically reducing SSO setup friction for your team.