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

# Enterprise SSO

> Configure enterprise SSO for EngageFabric with SAML or OIDC. Set up identity providers like Okta, Azure AD, or Google Workspace.

<Info>
  SSO is available on **Enterprise** plans only. [Contact sales](mailto:sales@engagefabric.com) to upgrade.
</Info>

Single Sign-On (SSO) allows your team members to authenticate using your organization's identity provider (IdP), providing centralized access management and enhanced security.

## Supported Providers

EngageFabric supports two SSO protocols:

<CardGroup cols={2}>
  <Card title="SAML 2.0" icon="shield-halved">
    Industry standard for enterprise SSO. Works with Okta, Azure AD, OneLogin, and more.
  </Card>

  <Card title="OpenID Connect" icon="lock-open">
    Modern OAuth 2.0-based protocol. Works with Google Workspace, Auth0, Keycloak, and more.
  </Card>
</CardGroup>

## Setting Up SAML SSO

### Step 1: Get Your Service Provider Details

First, retrieve your SAML metadata from the API:

```bash theme={null}
curl -X GET https://api.engagefabric.com/api/v1/enterprise/sso/metadata \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response:**

```json theme={null}
{
  "entityId": "https://api.engagefabric.com/api/v1/auth/sso/your-org/metadata",
  "acsUrl": "https://api.engagefabric.com/api/v1/auth/sso/your-org/callback",
  "certificate": "-----BEGIN CERTIFICATE-----\n..."
}
```

### Step 2: Configure Your Identity Provider

Add EngageFabric as a new application in your IdP:

<Tabs>
  <Tab title="Okta">
    1. Go to **Applications > Create App Integration**
    2. Select **SAML 2.0**
    3. Enter the following settings:
       * **Single Sign-On URL**: `{acsUrl from above}`
       * **Audience URI (SP Entity ID)**: `{entityId from above}`
       * **Name ID Format**: EmailAddress
    4. Under **Attribute Statements**, add:
       * `email` → `user.email`
       * `firstName` → `user.firstName`
       * `lastName` → `user.lastName`
    5. Save and copy the **Metadata URL** or download the IdP metadata
  </Tab>

  <Tab title="Azure AD">
    1. Go to **Enterprise Applications > New Application**
    2. Select **Create your own application**
    3. Choose **Integrate any other application (Non-gallery)**
    4. Go to **Single sign-on > SAML**
    5. Enter:
       * **Identifier (Entity ID)**: `{entityId from above}`
       * **Reply URL (ACS URL)**: `{acsUrl from above}`
    6. Download the **Federation Metadata XML**
  </Tab>

  <Tab title="OneLogin">
    1. Go to **Applications > Add App**
    2. Search for "SAML Custom Connector (Advanced)"
    3. Configure:
       * **Audience (EntityID)**: `{entityId from above}`
       * **ACS URL**: `{acsUrl from above}`
    4. Save and download the SAML metadata
  </Tab>
</Tabs>

### Step 3: Configure EngageFabric

Update your SSO configuration with the IdP details:

```bash theme={null}
curl -X PUT https://api.engagefabric.com/api/v1/enterprise/sso \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "SAML",
    "displayName": "Company SSO",
    "samlEntityId": "https://idp.company.com/saml/metadata",
    "samlSsoUrl": "https://idp.company.com/saml/sso",
    "samlCertificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
    "autoProvision": true,
    "defaultRole": "MEMBER",
    "allowedDomains": ["company.com"]
  }'
```

## Setting Up OIDC SSO

### Step 1: Create an OAuth Application

In your identity provider, create a new OAuth/OIDC application:

<Tabs>
  <Tab title="Google Workspace">
    1. Go to [Google Cloud Console](https://console.cloud.google.com)
    2. Navigate to **APIs & Services > Credentials**
    3. Click **Create Credentials > OAuth client ID**
    4. Select **Web application**
    5. Add redirect URI: `https://api.engagefabric.com/api/v1/auth/sso/your-org/callback`
    6. Copy the **Client ID** and **Client Secret**
  </Tab>

  <Tab title="Auth0">
    1. Go to **Applications > Create Application**
    2. Select **Regular Web Applications**
    3. In Settings, add Callback URL: `https://api.engagefabric.com/api/v1/auth/sso/your-org/callback`
    4. Copy the **Domain**, **Client ID**, and **Client Secret**
  </Tab>

  <Tab title="Keycloak">
    1. Create a new Client in your realm
    2. Set **Client Protocol** to `openid-connect`
    3. Set **Access Type** to `confidential`
    4. Add Valid Redirect URI: `https://api.engagefabric.com/api/v1/auth/sso/your-org/callback`
    5. Save and go to **Credentials** tab to copy the secret
  </Tab>
</Tabs>

### Step 2: Configure EngageFabric

```bash theme={null}
curl -X PUT https://api.engagefabric.com/api/v1/enterprise/sso \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "OIDC",
    "displayName": "Company SSO",
    "oidcIssuer": "https://accounts.google.com",
    "oidcClientId": "YOUR_CLIENT_ID",
    "oidcClientSecret": "YOUR_CLIENT_SECRET",
    "oidcScopes": ["openid", "profile", "email"],
    "autoProvision": true,
    "defaultRole": "MEMBER",
    "allowedDomains": ["company.com"]
  }'
```

## Configuration Options

| Field            | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `provider`       | string  | `SAML` or `OIDC`                    |
| `displayName`    | string  | Friendly name shown on login button |
| `autoProvision`  | boolean | Auto-create users on first login    |
| `defaultRole`    | string  | Role for auto-provisioned users     |
| `allowedDomains` | array   | Restrict to specific email domains  |

### SAML-Specific Fields

| Field             | Description                 |
| ----------------- | --------------------------- |
| `samlEntityId`    | IdP Entity ID from metadata |
| `samlSsoUrl`      | IdP SSO endpoint URL        |
| `samlCertificate` | IdP X.509 certificate       |

### OIDC-Specific Fields

| Field              | Description                                              |
| ------------------ | -------------------------------------------------------- |
| `oidcIssuer`       | IdP issuer URL (e.g., `https://accounts.google.com`)     |
| `oidcClientId`     | OAuth client ID                                          |
| `oidcClientSecret` | OAuth client secret                                      |
| `oidcScopes`       | Requested scopes (default: `openid`, `profile`, `email`) |

## Testing Your Configuration

Before enforcing SSO, test that it works correctly:

```bash theme={null}
curl -X POST https://api.engagefabric.com/api/v1/enterprise/sso/test \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response:**

```json theme={null}
{
  "valid": true,
  "loginUrl": "https://idp.company.com/saml/sso?SAMLRequest=..."
}
```

Visit the `loginUrl` in a browser to test the full SSO flow.

## Auto-Provisioning

When `autoProvision` is enabled:

1. New users are automatically created on first SSO login
2. They're assigned the `defaultRole` you specified
3. Their name and email are populated from the IdP
4. They don't need a separate invitation

<Warning>
  Auto-provisioned users count toward your team member limit. Monitor your usage to avoid exceeding plan limits.
</Warning>

## Domain Restrictions

Use `allowedDomains` to restrict which email domains can authenticate:

```json theme={null}
{
  "allowedDomains": ["company.com", "subsidiary.com"]
}
```

Users with email addresses outside these domains will be denied access, even if they successfully authenticate with your IdP.

## Disabling SSO

To disable SSO and revert to password authentication:

```bash theme={null}
curl -X DELETE https://api.engagefabric.com/api/v1/enterprise/sso \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

<Warning>
  Disabling SSO will require all users to set passwords. Ensure users have password recovery options before disabling.
</Warning>

## API Reference

| Method | Endpoint                      | Description                        |
| ------ | ----------------------------- | ---------------------------------- |
| GET    | `/v1/enterprise/sso`          | Get current SSO configuration      |
| PUT    | `/v1/enterprise/sso`          | Create or update SSO configuration |
| DELETE | `/v1/enterprise/sso`          | Disable SSO                        |
| POST   | `/v1/enterprise/sso/test`     | Test SSO configuration             |
| GET    | `/v1/enterprise/sso/metadata` | Get SAML metadata for IdP setup    |

## Troubleshooting

<AccordionGroup>
  <Accordion title="SSO login fails with 'Invalid signature'">
    Ensure you've copied the complete IdP certificate, including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
  </Accordion>

  <Accordion title="Users are not being auto-provisioned">
    Check that:

    * `autoProvision` is set to `true`
    * The user's email domain is in `allowedDomains` (if set)
    * You haven't reached your plan's team member limit
  </Accordion>

  <Accordion title="OIDC fails with 'Invalid redirect URI'">
    Ensure the callback URL in your IdP exactly matches:
    `https://api.engagefabric.com/api/v1/auth/sso/{your-org-slug}/callback`
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Custom Domains" icon="globe" href="/guides/custom-domains">
    Configure custom domains for your API and admin console
  </Card>

  <Card title="Team Management" icon="users" href="/guides/team-management">
    Manage team members and roles
  </Card>
</CardGroup>