WorkOS AuthKit Example Application Setup Guide

✅ Prerequisite Setup

• Create a WorkOS Account
  https://dashboard.workos.com/signup

• Create an Okta Dev Sandbox Account

  💡 You can use any identity provider. If your company has an internal IDP, feel free to use it here to model what customers would do to set up SSO/SCIM.

  • https://developer.okta.com/signup/
  • Ensure you have at least one user in your Okta tenant for testing SSO
    (Avoid using public email domains like Gmail/Yahoo. Use a company domain if possible.)

• Clone the WorkOS React Quickstart App
  https://github.com/zac-workos/react-authkit-walkthrough

  npm i
  npm run dev

  Make sure the app builds and starts properly.

🛠️ Dashboard Setup

• Dashboard Config

  • Add this redirect URI to your WorkOS dashboard:
    http://localhost:5173

  

  • Go to the Authentication page → Click Configure CORS

  • Add http://localhost:5173 to allowed origins and click "Save".

    

  • Navigate to API Keys and copy your Client ID

    

  • Rename .env.local.example to .env.local

  • Paste your Client ID into the .env.local file

    

  • Go to the Organizations tab and create an organization

    

  • Add a domain (use your Okta dev sandbox domain)

  • Make sure to create a user under this domain in Okta (admin role is fine)

• Configure Organization Domain Policy

  

  • Adjust authentication policies for your org/domain as needed
  • Enable SSO once the connection is available
  • Enable/disable additional authentication methods via the Authentication tab

• Set Up Okta (or other IDP) SSO

  • Go to your organization in WorkOS

  • Click Invite Admin

    • Select features (just SSO for this lab)

  • Click Next → Copy Setup Link

    This is what customers would use to configure SSO/SCIM with your app

  • Paste the link in your browser to begin the SSO setup

    

• Brand Authkit

  • Navigate to the Branding tab in the WorkOS Dashboard
  • Customize the login widget (logos, colors, etc.)
  • Optionally enable the split panel and add your own HTML/CSS

    

• Test the Login Flow

  • Test SSO by using an email address from your Okta domain
  • Test other login methods (email/password, social logins, etc.)