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

# Single Sign-On (SSO)

> Enterprise identity management and SSO integration

# Single Sign-On (SSO)

Single Sign-On enables your team to access Crew using your organization's identity provider. SSO improves security, simplifies user management, and provides a seamless login experience.

<Note>
  SSO is available on Enterprise plans. Contact [sales@usecrew.ai](mailto:sales@usecrew.ai) to enable.
</Note>

## Supported Providers

### SAML 2.0

| Provider         | Status    |
| ---------------- | --------- |
| Okta             | Supported |
| Azure AD         | Supported |
| Google Workspace | Supported |
| OneLogin         | Supported |
| Ping Identity    | Supported |
| Custom SAML      | Supported |

### OIDC

| Provider | Status    |
| -------- | --------- |
| Okta     | Supported |
| Azure AD | Supported |
| Auth0    | Supported |
| Google   | Supported |

## Setup

### SAML Configuration

<Steps>
  <Step title="Get Crew's SAML Details">
    Navigate to **Settings** → **Security** → **SSO**

    Copy:

    * **ACS URL**: `https://api.usecrew.ai/auth/saml/callback`
    * **Entity ID**: `https://api.usecrew.ai/saml/metadata`
    * **Metadata URL**: `https://api.usecrew.ai/saml/metadata.xml`
  </Step>

  <Step title="Configure Your IdP">
    In your identity provider:

    * Create a new SAML application
    * Enter Crew's ACS URL and Entity ID
    * Configure attribute mappings (see below)
  </Step>

  <Step title="Upload IdP Metadata">
    In Crew:

    * Upload your IdP's metadata XML, or
    * Enter IdP SSO URL and certificate manually
  </Step>

  <Step title="Test Connection">
    Use the **Test SSO** button to verify configuration
  </Step>

  <Step title="Enable for Users">
    Choose enforcement mode and enable SSO
  </Step>
</Steps>

### Required Attributes

| Attribute  | SAML Name                  | Required |
| ---------- | -------------------------- | -------- |
| Email      | `email` or `NameID`        | Yes      |
| First Name | `firstName` or `givenName` | Yes      |
| Last Name  | `lastName` or `surname`    | Yes      |
| Groups     | `groups`                   | Optional |

### Attribute Mapping

Configure in Crew:

```json theme={null}
{
  "attribute_mapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
    "groups": "http://schemas.xmlsoap.org/claims/Group"
  }
}
```

## OIDC Configuration

<Steps>
  <Step title="Create OIDC Application">
    In your identity provider, create an OIDC application
  </Step>

  <Step title="Configure Redirect URI">
    Set redirect URI to: `https://api.usecrew.ai/auth/oidc/callback`
  </Step>

  <Step title="Enter Details in Crew">
    * Client ID
    * Client Secret
    * Issuer URL
    * Scopes (openid, profile, email)
  </Step>

  <Step title="Test and Enable">
    Test the connection and enable for users
  </Step>
</Steps>

## User Provisioning

### Just-in-Time (JIT) Provisioning

Users are automatically created on first SSO login:

```json theme={null}
{
  "jit_provisioning": {
    "enabled": true,
    "default_role": "member",
    "auto_assign_workspace": true
  }
}
```

### SCIM Provisioning

For automated user lifecycle management:

```json theme={null}
{
  "scim": {
    "enabled": true,
    "endpoint": "https://api.usecrew.ai/scim/v2",
    "token": "scim_token_xxxxx"
  }
}
```

SCIM supports:

* User creation
* User updates
* User deactivation
* Group synchronization

### Group Mapping

Map IdP groups to Crew roles:

```json theme={null}
{
  "group_mapping": {
    "crew-admins": "admin",
    "crew-members": "member",
    "crew-viewers": "viewer"
  }
}
```

## Enforcement Modes

### Optional SSO

Users can choose SSO or password:

```json theme={null}
{
  "sso_enforcement": "optional"
}
```

### Required SSO

All users must use SSO:

```json theme={null}
{
  "sso_enforcement": "required"
}
```

Password login is disabled when SSO is required.

### Domain-Based Enforcement

Require SSO for specific email domains:

```json theme={null}
{
  "sso_enforcement": "domain",
  "sso_domains": ["yourcompany.com", "subsidiary.com"]
}
```

## Session Management

### Session Duration

Configure SSO session length:

```json theme={null}
{
  "session": {
    "max_duration_hours": 24,
    "idle_timeout_hours": 4,
    "require_reauth_for_sensitive": true
  }
}
```

### Single Logout (SLO)

Enable single logout to end sessions across all applications:

```json theme={null}
{
  "single_logout": {
    "enabled": true,
    "logout_url": "https://api.usecrew.ai/auth/slo"
  }
}
```

## Security Features

### MFA via IdP

When SSO is enabled, MFA is enforced through your identity provider.

### Session Controls

* Force re-authentication for sensitive actions
* Configurable session timeouts
* Device tracking and management

### IP Restrictions

Combine SSO with IP allowlisting:

```json theme={null}
{
  "access_restrictions": {
    "allowed_ips": ["203.0.113.0/24"],
    "sso_bypass_allowed": false
  }
}
```

## Provider-Specific Guides

### Okta

1. Create new SAML 2.0 application
2. Set Single Sign On URL to Crew's ACS URL
3. Set Audience URI to Crew's Entity ID
4. Configure attribute statements:
   * `email` → user.email
   * `firstName` → user.firstName
   * `lastName` → user.lastName
5. Download metadata XML
6. Upload to Crew

### Azure AD

1. Create Enterprise Application
2. Select SAML single sign-on
3. Configure Basic SAML:
   * Identifier: Crew Entity ID
   * Reply URL: Crew ACS URL
4. Configure Attributes & Claims:
   * Add email, givenname, surname claims
5. Download Federation Metadata XML
6. Upload to Crew

### Google Workspace

1. Go to Admin Console → Apps → SAML Apps
2. Add custom SAML app
3. Configure Service Provider Details:
   * ACS URL: Crew's ACS URL
   * Entity ID: Crew's Entity ID
4. Map attributes:
   * Primary email → email
   * First name → firstName
   * Last name → lastName
5. Download IdP metadata
6. Upload to Crew

## Troubleshooting

### Common Issues

| Issue                   | Cause                | Solution                       |
| ----------------------- | -------------------- | ------------------------------ |
| "Invalid SAML response" | Certificate mismatch | Re-upload IdP certificate      |
| "User not found"        | Email mismatch       | Verify email attribute mapping |
| "Access denied"         | Group not mapped     | Update group mappings          |
| Redirect loop           | Incorrect ACS URL    | Verify ACS URL in IdP          |

### Debug Mode

Enable debug logging for troubleshooting:

```json theme={null}
{
  "sso_debug": {
    "enabled": true,
    "log_assertions": true
  }
}
```

<Warning>
  Disable debug mode after troubleshooting. It may log sensitive data.
</Warning>

### Testing

Use the SSO test tool:

1. Go to **Settings** → **Security** → **SSO**
2. Click **Test SSO Login**
3. Review the test results for errors

## Audit Logging

SSO events are logged:

| Event                  | Description          |
| ---------------------- | -------------------- |
| `sso.login.success`    | Successful SSO login |
| `sso.login.failure`    | Failed SSO attempt   |
| `sso.logout`           | SSO logout           |
| `sso.config.updated`   | SSO settings changed |
| `sso.user.provisioned` | JIT user created     |

## Best Practices

<AccordionGroup>
  <Accordion title="Test before enforcing">
    Test SSO with a few users before requiring it for everyone.
  </Accordion>

  <Accordion title="Keep a break-glass account">
    Maintain one admin account with password login for emergencies.
  </Accordion>

  <Accordion title="Use group mapping">
    Automate role assignment through IdP groups.
  </Accordion>

  <Accordion title="Configure session timeouts">
    Set appropriate session durations based on security requirements.
  </Accordion>

  <Accordion title="Enable SCIM for large teams">
    Automate user lifecycle with SCIM provisioning.
  </Accordion>
</AccordionGroup>

## Next Steps

* [Security Overview](/security/overview) — Security architecture
* [Authentication](/developer/authentication) — API authentication
* [Audit Logs](/enterprise/audit-logs) — Access logging