Skip to main content
SSO events track administrative actions related to single sign-on configuration for organizations. These events record when administrators view SSO settings, create management portal URLs, and delete SSO connections.
All SSO events include the standard actor, targets, context, and metadata fields. The schemas below show event-specific fields.

​
sso.view_settings

Records when a user views the organization’s SSO and directory sync settings page.

​
Triggered When

User navigates to the SSO settings page to view current SSO connections and directory sync configurations.

​
Event Schema

​
action
string
required
sso.view_settings
​
targets
array
required
​
metadata.source
string
required
Page route (e.g., /organizations/[orgId]/sso)

​
Example Event

{
  "action": "sso.view_settings",
  "occurredAt": "2025-01-15T10:30:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/sso"
  }
}

​
sso.create_management_portal_url

Records when an administrator generates a portal URL to access the WorkOS SSO management interface.

​
Triggered When

Admin requests access to configure or manage SSO connections through the WorkOS self-service portal. This occurs when clicking the “Manage SSO” or “Setup SSO” button in the SSO settings page.

​
Event Schema

​
action
string
required
sso.create_management_portal_url
​
targets
array
required
​
metadata.source
string
required
Page route where portal URL was generated (e.g., /organizations/[orgId]/sso)

​
Example Event

{
  "action": "sso.create_management_portal_url",
  "occurredAt": "2025-01-15T11:15:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "organization",
      "id": "org_01JGXYZ456",
      "name": "Acme Corp",
      "metadata": {
        "name": "Acme Corp"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/sso"
  }
}
Generated portal URLs redirect users to the WorkOS SSO configuration interface and are temporary. They expire after use and include return URLs to redirect back to the Centure dashboard.

​
sso.delete_connection

Records when an SSO connection is removed from an organization.

​
Triggered When

Admin deletes an existing SSO connection from the organization’s SSO settings page. This removes the SSO configuration and requires users to authenticate without SSO.

​
Event Schema

​
action
string
required
sso.delete_connection
​
targets
array
required
​
metadata.source
string
required
Page route where connection was deleted (e.g., /organizations/[orgId]/sso)

​
Example Event

{
  "action": "sso.delete_connection",
  "occurredAt": "2025-01-15T14:30:00.000Z",
  "version": 1,
  "actor": {
    "type": "user",
    "id": "user_01JGXYZ123",
    "name": "Alice Johnson",
    "metadata": {
      "first_name": "Alice",
      "last_name": "Johnson",
      "email": "alice@example.com",
      "impersonator_email": "",
      "impersonator_reason": ""
    }
  },
  "targets": [
    {
      "type": "sso_connection",
      "id": "conn_01JGXYZ789",
      "name": "GoogleSAML Connection",
      "metadata": {
        "connection_id": "conn_01JGXYZ789",
        "connection_type": "GoogleSAML",
        "organization_id": "org_01JGXYZ456"
      }
    }
  ],
  "context": {
    "location": "192.0.2.1",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
  },
  "metadata": {
    "source": "/organizations/org_01JGXYZ456/sso"
  }
}

​
Supported Connection Types

The connection_type field supports the following common SSO providers:
  • GoogleSAML - Google SAML-based SSO
  • OktaSAML - Okta SAML-based SSO
  • AzureSAML - Microsoft Azure SAML-based SSO
  • GenericSAML - Generic SAML 2.0 providers
  • GenericOIDC - Generic OpenID Connect providers
These are the most commonly used connection types. WorkOS supports 37 total SSO connection types including Auth0, Okta, OneLogin, and many others. See the WorkOS SSO documentation for the complete list of supported providers.

​
Authorization

SSO events have specific authorization requirements:

​
sso.view_settings

  • Any organization member can view SSO settings
  • Event records when the page is accessed

​
sso.create_management_portal_url

  • Requires admin role in the organization
  • User must be authenticated with active session

​
sso.delete_connection

  • Requires admin role in the organization
  • Uses idempotency keys to prevent duplicate deletions
  • Operation is atomic and validates connection ownership

​
Common Use Cases

Track SSO events to:
  • Monitor SSO configuration changes for compliance
  • Audit which administrators access SSO management tools
  • Track when SSO connections are removed (potential security impact)
  • Verify proper authorization for sensitive SSO operations
  • Investigate SSO access patterns during security reviews

Directory Sync

Automated user provisioning and directory connections

Organizations

Organization settings and domain management

Audit Log Streams

Portal access events for audit logging and SIEM integrations