WorkOS Integration

Overview

WorkOS provides enterprise-ready authentication features including Single Sign-On (SSO), Directory Sync (SCIM), and Admin Portal capabilities. This integration enables MemberPulse to support enterprise clients with existing identity providers.

---

Prerequisites

Before configuring WorkOS:

1. Create a WorkOS account at workos.com
2. Obtain your API Key and Client ID from the WorkOS Dashboard
3. Configure your redirect URIs in WorkOS

---

Configuration

Environment Variables

Add these to your environment configuration:

WORKOS_API_KEY=sk_live_xxxxxxxxxxxx
WORKOS_CLIENT_ID=client_xxxxxxxxxxxx
WORKOS_REDIRECT_URI=https://app.memberpulse.com/auth/callback/workos
WORKOS_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Acceptance Criteria

Frontend

• Environment Variables workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Environment Variables as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Platform Settings

Navigate to Admin Portal > Platform Settings > Integrations > WorkOS

Setting	Type	Required	Description
API Key	Secret	Yes	WorkOS API key (starts with sk_)
Client ID	Text	Yes	WorkOS Client ID
Redirect URI	URL	Yes	OAuth callback URL
Webhook Secret	Secret	Yes	Webhook signing secret
Default Connection	Select	No	Default SSO connection for login

---

Acceptance Criteria

Frontend

• Platform Settings workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Platform Settings as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Single Sign-On (SSO)

Supported Identity Providers

WorkOS SSO supports 50+ identity providers including:

Acceptance Criteria

Frontend

• Supported Identity Providers workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Supported Identity Providers as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

SSO Login Flow

sequenceDiagram
    participant User
    participant MemberPulse
    participant WorkOS
    participant IdP as Identity Provider

    User->>MemberPulse: Click "Sign in with SSO"
    MemberPulse->>WorkOS: Get Authorization URL
    WorkOS-->>MemberPulse: Return URL
    MemberPulse->>User: Redirect to IdP
    User->>IdP: Authenticate
    IdP->>WorkOS: SAML/OIDC Response
    WorkOS->>MemberPulse: Callback with code
    MemberPulse->>WorkOS: Exchange code for profile
    WorkOS-->>MemberPulse: User profile
    MemberPulse->>User: Create session, redirect to app

Acceptance Criteria

Frontend

• SSO Login Flow workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports SSO Login Flow as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Configuring SSO for an Organization

1. Navigate to Client Portal > Settings > Authentication
2. Click Configure SSO
3. Select identity provider type (SAML 2.0 or OIDC)
4. Enter connection details provided by your IdP:

5. Test the connection
6. Enable SSO for users

Acceptance Criteria

Frontend

• Configuring SSO for an Organization workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Configuring SSO for an Organization as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

SSO User Attributes

Map IdP attributes to MemberPulse user fields:

IdP Attribute	MemberPulse Field	Required
email	Email	Yes
given_name or firstName	First Name	Yes
family_name or lastName	Last Name	Yes
groups	Roles	No
department	Department	No
job_title	Job Title	No

---

Acceptance Criteria

Frontend

• SSO User Attributes workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports SSO User Attributes as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Directory Sync (SCIM)

Automatically provision and deprovision users based on your identity provider's directory.

Supported Directories

• Okta
• Azure AD (Entra ID)
• Google Workspace
• OneLogin
• JumpCloud
• Generic SCIM 2.0

Acceptance Criteria

Frontend

• Supported Directories workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Supported Directories as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

SCIM Capabilities

Operation	Supported	Description
Create User	Yes	New users in IdP are created in MemberPulse
Update User	Yes	Profile changes sync automatically
Deactivate User	Yes	Removed users are deactivated
Delete User	Yes	Optionally hard-delete removed users
Create Group	Yes	IdP groups sync as MemberPulse roles
Update Group	Yes	Group membership changes sync
Delete Group	Yes	Removed groups are deleted

Acceptance Criteria

Frontend

• SCIM Capabilities workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports SCIM Capabilities as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Configuring Directory Sync

1. Navigate to Admin Portal > Platform Settings > Directory Sync
2. Click Add Directory
3. Select your directory provider
4. Copy the SCIM endpoint URL and bearer token
5. Configure SCIM provisioning in your IdP using these credentials

SCIM Endpoint: https://api.workos.com/directories/{directory_id}/scim/v2

Acceptance Criteria

Frontend

• Configuring Directory Sync workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Configuring Directory Sync as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Attribute Mapping

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "user@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "primary": true,
      "value": "user@example.com"
    }
  ],
  "active": true,
  "groups": [
    {
      "value": "group_123",
      "display": "Engineering"
    }
  ]
}

Acceptance Criteria

Frontend

• Attribute Mapping workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Attribute Mapping as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Group to Role Mapping

Map directory groups to MemberPulse roles:

Directory Group	MemberPulse Role
MemberPulse Admins	ROLE_CLIENT_ADMIN
MemberPulse Staff	ROLE_CLIENT_USER
MemberPulse Members	ROLE_MEMBER

---

Acceptance Criteria

Frontend

• Group to Role Mapping workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Group to Role Mapping as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Webhooks

WorkOS sends webhooks for real-time event notifications.

Webhook Events

Event	Description
dsync.user.created	New user provisioned via SCIM
dsync.user.updated	User profile updated
dsync.user.deleted	User deprovisioned
dsync.group.created	New group created
dsync.group.updated	Group membership changed
dsync.group.deleted	Group removed
connection.activated	SSO connection activated
connection.deactivated	SSO connection deactivated

Acceptance Criteria

Frontend

• Webhook Events workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Webhook Events as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Webhook Endpoint

Configure in WorkOS Dashboard:

POST https://api.memberpulse.com/webhooks/workos

Acceptance Criteria

Frontend

• Webhook Endpoint workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Webhook Endpoint as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Webhook Payload Example

{
  "id": "event_01234567890",
  "event": "dsync.user.created",
  "data": {
    "id": "directory_user_01234567890",
    "directory_id": "directory_01234567890",
    "emails": [
      {
        "primary": true,
        "value": "user@example.com"
      }
    ],
    "first_name": "John",
    "last_name": "Doe",
    "state": "active",
    "raw_attributes": {}
  }
}

---

Acceptance Criteria

Frontend

• Webhook Payload Example workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Webhook Payload Example as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Admin Portal

WorkOS Admin Portal allows enterprise clients to self-manage their SSO and Directory Sync configurations.

Generating Admin Portal Link

// Generate a short-lived admin portal link
$link = $workos->portal->generateLink([
    'organization' => 'org_01234567890',
    'intent' => 'sso', // or 'dsync'
    'return_url' => 'https://app.memberpulse.com/settings'
]);

Acceptance Criteria

Frontend

• Generating Admin Portal Link workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Generating Admin Portal Link as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Admin Portal Capabilities

• Configure SSO connections
• Upload IdP metadata/certificates
• Test SSO connections
• Configure directory sync
• View sync logs and errors

---

Acceptance Criteria

Frontend

• Admin Portal Capabilities workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Admin Portal Capabilities as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

API Reference

Authentication Endpoints

GET  /auth/sso                        # Initiate SSO login
GET  /auth/callback/workos            # SSO callback handler
POST /api/auth/sso/connections        # List SSO connections
POST /api/auth/sso/connections/{id}   # Get connection details

Acceptance Criteria

Frontend

• Authentication Endpoints workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Authentication Endpoints as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Directory Sync Endpoints

GET  /api/directories                 # List directories
GET  /api/directories/{id}            # Get directory details
GET  /api/directories/{id}/users      # List directory users
GET  /api/directories/{id}/groups     # List directory groups
POST /api/directories/{id}/sync       # Trigger manual sync

---

Acceptance Criteria

Frontend

• Directory Sync Endpoints workflow is implemented in the UI as described.

Backend / API

• Backend behavior supports Directory Sync Endpoints as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Troubleshooting

---

Security Considerations

• Store API keys in secure environment variables
• Validate webhook signatures before processing
• Use HTTPS for all callback URLs
• Regularly rotate API keys
• Monitor audit logs for suspicious activity

Features

WorkOS Integration

Acceptance Criteria

Frontend

• UI provides configuration controls and status/health indicators for this integration.

Backend / API

• Integration can be connected, configured, and exercised end-to-end (auth + sync/webhooks).

Permissions

• Only ROLE_CLIENT_ADMIN (or equivalent) can configure the integration.

Business Rules

• Data sync respects tenant isolation and mapping rules.

Error Handling

• Auth and sync failures are surfaced with actionable messages and retry behavior.