# SSO

> Single sign-on configuration (Enterprise).

Source: https://docs.graph8.com/settings/sso/

Configure SAML-based single sign-on so your team can log in with their existing identity provider.

## Supported Providers

graph8 supports SAML 2.0 SSO with:

- **Okta**
- **Azure AD (Microsoft Entra ID)**
- **OneLogin**
- **Google Workspace**
- Any SAML 2.0–compliant identity provider

SSO is available on Enterprise plans.

## Setup

### Step 1: Gather graph8 SAML Details

1. Go to **Settings → SSO**
2. Copy the following values to use in your identity provider:
   - **ACS URL** (Assertion Consumer Service)
   - **Entity ID** (SP Entity ID)
   - **Login URL**

### Step 2: Configure Your Identity Provider

In your identity provider (Okta, Azure AD, etc.):

1. Create a new SAML application
2. Paste the ACS URL and Entity ID from graph8
3. Configure attribute mapping:
   - **email** — user's email address (required)
   - **firstName** — user's first name
   - **lastName** — user's last name
4. Download the IdP metadata XML or copy the:
   - **IdP SSO URL**
   - **IdP Entity ID**
   - **X.509 Certificate**

### Step 3: Complete Configuration in graph8

1. Return to **Settings → SSO**
2. Upload the IdP metadata XML, or manually enter:
   - IdP SSO URL
   - IdP Entity ID
   - X.509 Certificate
3. Click **Save**
4. Click **Test Connection** to verify

### Step 4: Enable SSO

Once the test connection succeeds:

1. Toggle SSO to **Enabled**
2. Choose the enforcement mode (see below)
3. Save

## Enforcement

### Optional SSO

Users can log in with either SSO or email/password. This is useful during rollout.

### Required SSO

All organization members must use SSO to log in. Email/password login is disabled.

- Admins can still use email/password as a fallback (to prevent lockout)
- New users are automatically prompted to use SSO on their first login

### Enabling Enforcement

1. Go to **Settings → SSO**
2. Set enforcement to **Required**
3. Notify your team about the change
4. Save

## Troubleshooting

### Common Issues

**"SAML response is invalid"**
- Check that the ACS URL in your IdP matches the one shown in graph8
- Verify the X.509 certificate hasn't expired
- Ensure the clock on your IdP server is synchronized (SAML is time-sensitive)

**"User not found"**
- The email in the SAML assertion must match a user's email in graph8
- Verify the attribute mapping sends the correct email field

**"Certificate error"**
- Re-download the certificate from your IdP
- Upload the new certificate in graph8
- Some IdPs rotate certificates — check your IdP's rotation schedule

### Certificate Expiry

SAML certificates expire periodically (typically every 1–3 years). When your certificate approaches expiry:

1. Generate a new certificate in your IdP
2. Upload the new certificate in **Settings → SSO**
3. Test the connection
4. The old certificate is replaced

## Frequently Asked Questions

### Can I use multiple identity providers?

Currently, one IdP per organization. All users must authenticate through the same provider.

### What happens if SSO goes down?

Admins retain email/password access as a fallback. Contact support for emergency access if all admins are locked out.

### Do new users need to be manually invited?

With SSO enabled, new users can be auto-provisioned on first login. Their role defaults to Member unless configured otherwise.

### Does SSO work with two-factor authentication?

Yes. 2FA from your identity provider is enforced during the SSO login flow. graph8's built-in 2FA is bypassed when SSO is active.

---

> **Tip:**
> Test SSO with a small group before enforcing it organization-wide.