WorkOS Integrations

Step 1: Identify the Provider

Ask the user which identity provider they need to integrate. Then find it in the table below.

Provider Lookup

Step 2: Set Up the Connection

WebFetch the provider-specific doc URL from the table above, then follow the protocol for the connection type.

SAML SSO Setup

1. In WorkOS Dashboard, navigate to Organizations > [Org] > Authentication
2. Click Add Connection and select SAML
3. Copy these values from the connection detail page:
   • ACS URL (Assertion Consumer Service) — paste into IdP’s SSO config
   • SP Entity ID — paste into IdP’s audience/entity field
4. In the IdP admin console, create a new SAML application: a. Set the ACS URL and SP Entity ID from step 3 b. Configure attribute mapping: id → NameID, email → email, firstName → first name, lastName → last name c. Download or copy the IdP Metadata URL (or download the metadata XML file)
5. Back in WorkOS Dashboard, upload the IdP metadata (URL or XML file)
6. Connection state transitions: Draft → Validating → Active
   • If it stays in Draft, see Troubleshooting below

SCIM Directory Sync Setup

1. In WorkOS Dashboard, navigate to Organizations > [Org] > Directory Sync
2. Click Add Directory and select the provider
3. Copy these values from the directory detail page:
   • SCIM Endpoint URL (e.g., https://api.workos.com/directories/<DIR_ID>/scim/v2)
   • SCIM Bearer Token — treat as a secret, never log or commit
4. In the IdP admin console, configure SCIM provisioning: a. Set the SCIM Base URL to the endpoint from step 3 b. Set Authentication to Bearer Token and paste the token c. Enable provisioning actions: Create Users, Update User Attributes, Deactivate Users d. Map user attributes: userName → email, name.givenName → first name, name.familyName → last name
5. Run a test push/sync from the IdP to verify users appear in WorkOS
6. Directory state transitions: Inactive → Validating → Linked

OAuth Social Login Setup

1. In the OAuth provider’s developer console, create a new OAuth application
2. Set the Redirect URI to the value from WorkOS Dashboard:
   • Format: https://auth.workos.com/sso/oauth/callback/<CONNECTION_ID>
3. Copy the Client ID and Client Secret from the provider
4. In WorkOS Dashboard, navigate to Authentication > Social Login
5. Select the provider and paste the Client ID and Client Secret
6. Configure scopes (typically: openid, profile, email)
7. Test by initiating a login flow through your application

Step 3: Verify the Integration

# Check connection status via WorkOS API
curl -s -H "Authorization: Bearer $WORKOS_API_KEY" \
  https://api.workos.com/connections | jq '.data[] | {id, name, state}'

# Verify SSO connection is active
curl -s -H "Authorization: Bearer $WORKOS_API_KEY" \
  https://api.workos.com/connections | jq '.data[] | select(.state == "active") | .name'

# Check directory sync connections
curl -s -H "Authorization: Bearer $WORKOS_API_KEY" \
  https://api.workos.com/directories | jq '.data[] | {id, name, state}'

Checklist:

• Connection appears in WorkOS Dashboard with “Active” (SSO) or “Linked” (directory) state
• Test SSO login succeeds with a test user
• User profile attributes map correctly (email, first name, last name, groups)
• (If SCIM) Directory sync shows users from provider
• (If OAuth) Social login redirects correctly and returns user profile

Integration Type Decision Tree

What type of integration?
  |
  +-- SSO (user login)
  |     |
  |     +-- Provider supports SAML? → Use SAML connection (preferred for enterprise)
  |     +-- Provider supports OIDC only? → Use OIDC connection
  |     +-- Provider supports both? → Prefer SAML (wider enterprise support, more attributes)
  |
  +-- Directory Sync (user provisioning)
  |     |
  |     +-- Provider supports SCIM? → Use SCIM connection
  |     +-- No SCIM but has API? → Check if WorkOS has a native directory for this provider
  |     +-- No directory support? → Consider SFTP-based import or manual sync
  |
  +-- OAuth (social login)
        |
        +-- Find provider in OAuth section of table above
        +-- Follow OAuth setup steps in Step 2

Troubleshooting Decision Tree

Connection not working?
  |
  +-- Connection stuck in "Draft"
  |     |
  |     +-- Did you upload IdP metadata? → Upload XML or enter metadata URL in Dashboard
  |     +-- Metadata uploaded but still Draft? → Check metadata is valid XML, not HTML login page
  |     +-- Using metadata URL? → Verify URL is publicly reachable (not behind firewall)
  |
  +-- Connection stuck in "Validating"
  |     |
  |     +-- IdP metadata certificate expired? → Upload new cert or fresh metadata
  |     +-- ACS URL contains typo? → Re-copy from Dashboard, paste exactly
  |     +-- SP Entity ID mismatch? → Ensure IdP audience matches WorkOS SP Entity ID exactly
  |
  +-- SAML assertion errors
  |     |
  |     +-- "Recipient mismatch" → ACS URL in IdP config does not match WorkOS; re-copy it
  |     +-- "Audience mismatch" → SP Entity ID in IdP does not match; re-copy it
  |     +-- "Signature invalid" → IdP metadata/certificate is stale; re-upload current metadata
  |     +-- "Response expired" → Clock skew between IdP and SP; verify NTP sync on IdP server
  |     +-- "NameID missing" → IdP not sending NameID; add NameID mapping in IdP attribute config
  |
  +-- SCIM sync failing
  |     |
  |     +-- 401 Unauthorized → Bearer token is wrong or expired; regenerate in Dashboard
  |     +-- 404 Not Found → SCIM endpoint URL is wrong; re-copy from Dashboard
  |     +-- Users sync but no attributes → Check attribute mapping in IdP; must map userName, name.*
  |     +-- Users created but not updated → Ensure "Update User Attributes" is enabled in IdP provisioning
  |     +-- Deactivated users still active → Enable "Deactivate Users" in IdP provisioning settings
  |
  +-- OAuth redirect errors
  |     |
  |     +-- "redirect_uri_mismatch" → Redirect URI in provider console doesn't match WorkOS; copy exact URI
  |     +-- "invalid_client" → Client ID or Secret is wrong; re-copy from provider console
  |     +-- "access_denied" → User denied consent, or OAuth app not approved; check provider app status
  |     +-- Scopes error → Remove unsupported scopes; start with openid, profile, email
  |
  +-- "Organization not found"
        |
        +-- No org exists → Create organization in Dashboard first
        +-- Org exists but connection not linked → Link connection to organization in Dashboard
        +-- Domain not verified → Verify domain under Organizations > Domains (required for SSO)

Error Recovery Reference

Related Skills

• workos-sso: General SSO implementation and configuration
• workos-directory-sync: Directory Sync setup and management
• workos-domain-verification: Domain verification required for SSO
• workos-admin-portal: Let customers configure their own connections