> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO Events

> Audit log events for single sign-on configuration and management

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.

<Info>
  All SSO events include the standard [actor, targets, context, and metadata](/logs/audit-events#base-event-schema) fields. The schemas below show event-specific fields.
</Info>

## 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

<ResponseField name="action" type="string" required>
  `sso.view_settings`
</ResponseField>

<ResponseField name="targets" type="array" required>
  <Expandable title="organization target">
    <ResponseField name="type" type="string" required>
      `organization`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Organization's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Organization name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      Organization name (duplicated for consistency)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata.source" type="string" required>
  Page route (e.g., `/organizations/[orgId]/sso`)
</ResponseField>

### Example Event

```json theme={null}
{
  "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

<ResponseField name="action" type="string" required>
  `sso.create_management_portal_url`
</ResponseField>

<ResponseField name="targets" type="array" required>
  <Expandable title="organization target">
    <ResponseField name="type" type="string" required>
      `organization`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      Organization's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Organization name
    </ResponseField>

    <ResponseField name="metadata.name" type="string" required>
      Organization name (duplicated for consistency)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata.source" type="string" required>
  Page route where portal URL was generated (e.g., `/organizations/[orgId]/sso`)
</ResponseField>

### Example Event

```json theme={null}
{
  "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"
  }
}
```

<Note>
  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.
</Note>

***

## 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

<ResponseField name="action" type="string" required>
  `sso.delete_connection`
</ResponseField>

<ResponseField name="targets" type="array" required>
  <Expandable title="sso_connection target">
    <ResponseField name="type" type="string" required>
      `sso_connection`
    </ResponseField>

    <ResponseField name="id" type="string" required>
      SSO connection's unique identifier
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Formatted connection name (e.g., `GoogleSAML Connection`, `OktaSAML Connection`)
    </ResponseField>

    <ResponseField name="metadata.connection_id" type="string" required>
      SSO connection's unique identifier (same as id)
    </ResponseField>

    <ResponseField name="metadata.connection_type" type="string" required>
      Type of SSO connection (e.g., `GoogleSAML`, `OktaSAML`, `AzureSAML`, `GenericSAML`, `GenericOIDC`)
    </ResponseField>

    <ResponseField name="metadata.organization_id" type="string" required>
      Organization's unique identifier
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata.source" type="string" required>
  Page route where connection was deleted (e.g., `/organizations/[orgId]/sso`)
</ResponseField>

### Example Event

```json theme={null}
{
  "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

<Note>
  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](https://workos.com/docs/sso) for the complete list of supported providers.
</Note>

***

## 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

***

## Related Events

<CardGroup cols={2}>
  <Card title="Directory Sync" icon="arrows-rotate" href="/logs/events/directory-sync">
    Automated user provisioning and directory connections
  </Card>

  <Card title="Organizations" icon="building" href="/logs/events/organizations">
    Organization settings and domain management
  </Card>

  <Card title="Audit Log Streams" icon="stream" href="/logs/events/audit-log-streams">
    Portal access events for audit logging and SIEM integrations
  </Card>
</CardGroup>