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

# Single sign-on (SSO) and SAML configuration

Single sign-on (SSO) lets your team log into HoopAI using your organization's existing identity provider (IdP) instead of separate passwords. SAML 2.0 is the protocol HoopAI uses to communicate with your IdP.

## Why use SSO

* **One set of credentials** — users log in with their company account
* **Centralized access control** — disable a user in your IdP and they instantly lose HoopAI access
* **Stronger security** — enforce your organization's password policies and MFA at the IdP level
* **Reduced password fatigue** — fewer passwords means fewer reset requests

## Prerequisites

<Warning>
  SSO with SAML is available on the **Enterprise plan** only. Contact your account manager to enable it.
</Warning>

Before you begin, make sure you have:

* An active HoopAI Enterprise subscription
* Admin access to your identity provider (Okta, Azure AD, Google Workspace, OneLogin, or any SAML 2.0-compatible IdP)
* Admin role in HoopAI

## Supported identity providers

| Identity provider             | Status          | Notes                           |
| ----------------------------- | --------------- | ------------------------------- |
| Okta                          | Fully supported | Pre-built integration available |
| Microsoft Azure AD (Entra ID) | Fully supported | Enterprise application template |
| Google Workspace              | Fully supported | Custom SAML app setup           |
| OneLogin                      | Fully supported | Connector available             |
| Custom SAML 2.0               | Supported       | Any IdP that supports SAML 2.0  |

## Step-by-step SAML setup

<Steps>
  ### Locate your HoopAI SAML details

  Navigate to **Settings > Security > SSO / SAML**. You will see three values you need to provide to your IdP:

  | Field                        | Description                                          | Example                                    |
  | ---------------------------- | ---------------------------------------------------- | ------------------------------------------ |
  | **Entity ID** (Audience URI) | Unique identifier for HoopAI as a service provider   | `https://app.hoopai.com/saml/metadata`     |
  | **ACS URL** (Reply URL)      | The endpoint where your IdP sends the SAML assertion | `https://app.hoopai.com/saml/acs`          |
  | **Metadata URL**             | XML document describing HoopAI's SAML configuration  | `https://app.hoopai.com/saml/metadata.xml` |

  Copy these values — you will paste them into your IdP in the next step.

  ### Configure your identity provider

  <Tabs>
    <Tab title="Okta">
      1. In Okta Admin, go to **Applications > Create App Integration**
      2. Select **SAML 2.0** and click **Next**
      3. Set the **App name** to `HoopAI`
      4. Paste the **ACS URL** into the **Single sign-on URL** field
      5. Paste the **Entity ID** into the **Audience URI** field
      6. Set **Name ID format** to `EmailAddress`
      7. Add attribute statements (see attribute mapping below)
      8. Click **Finish**
      9. Copy the **IdP Metadata URL** from the Sign On tab
    </Tab>

    <Tab title="Azure AD">
      1. In Azure Portal, go to **Enterprise Applications > New Application > Create your own**
      2. Name the app `HoopAI` and select **Integrate any other application (Non-gallery)**
      3. Go to **Single sign-on > SAML**
      4. Under **Basic SAML Configuration**, set:
         * **Identifier (Entity ID)**: paste from HoopAI
         * **Reply URL (ACS URL)**: paste from HoopAI
      5. Under **Attributes & Claims**, configure mappings (see below)
      6. Download the **Federation Metadata XML** or copy the **App Federation Metadata URL**
    </Tab>

    <Tab title="Google Workspace">
      1. In Google Admin, go to **Apps > Web and mobile apps > Add app > Add custom SAML app**
      2. Name the app `HoopAI`
      3. Download the **IdP metadata** on the Google IdP details screen
      4. Set **ACS URL** and **Entity ID** using values from HoopAI
      5. Set **Name ID format** to `EMAIL`
      6. Add attribute mappings (see below)
      7. Click **Finish** and turn the app **ON** for the relevant organizational units
    </Tab>

    <Tab title="Custom SAML 2.0">
      1. Create a new SAML application in your IdP
      2. Set the **ACS / Consumer URL** to the value from HoopAI
      3. Set the **Audience / Entity ID** to the value from HoopAI
      4. Configure **Name ID** as the user's email address
      5. Add the attribute statements listed below
      6. Export your IdP's metadata XML or copy the metadata URL
    </Tab>
  </Tabs>

  ### Configure attribute mapping

  Your IdP must send these attributes in the SAML assertion:

  | SAML attribute      | Required    | Maps to     | Expected value                         |
  | ------------------- | ----------- | ----------- | -------------------------------------- |
  | `email` or `NameID` | Yes         | User email  | User's primary email address           |
  | `firstName`         | Recommended | First name  | Given name                             |
  | `lastName`          | Recommended | Last name   | Family name                            |
  | `role`              | Optional    | HoopAI role | `admin`, `user`, or a custom role name |

  <Note>
    If `firstName` and `lastName` are not provided, HoopAI will use the portion before `@` in the email as the display name.
  </Note>

  ### Enter IdP details in HoopAI

  Back in **Settings > Security > SSO / SAML**:

  1. Paste your **IdP Metadata URL** — or upload the metadata XML file
  2. HoopAI will auto-populate the IdP SSO URL, IdP Issuer, and X.509 certificate
  3. Click **Save configuration**

  ### Test the connection

  1. Click **Test SSO connection**
  2. A new window opens and redirects you to your IdP login page
  3. Authenticate with your IdP credentials
  4. If successful, you are redirected back to HoopAI with a "Connection verified" message

  <Warning>
    Do not enforce SSO until you have successfully tested the connection. Enforcing a broken SSO configuration can lock all users out.
  </Warning>

  ### Enforce SSO for all users

  Once testing succeeds:

  1. Toggle **Enforce SSO** to on
  2. Choose an enforcement scope:
     * **All users** — every user must log in via SSO
     * **All users except admins** — admins retain password login as a fallback
  3. Click **Save**

  After enforcement, the standard email/password login form is hidden for affected users. They see a **Log in with SSO** button instead.
</Steps>

## Just-in-time (JIT) user provisioning

When JIT provisioning is enabled, users who authenticate through your IdP are **automatically created** in HoopAI on their first login — no manual invitation needed.

To enable JIT provisioning:

1. Go to **Settings > Security > SSO / SAML**
2. Toggle **Just-in-time provisioning** to on
3. Select a **default role** for newly provisioned users
4. Optionally select a **default team**

<Tip>
  JIT provisioning only creates users — it does not deactivate them. To remove access, disable the user in your IdP and manually deactivate them in HoopAI, or use SCIM provisioning if available on your plan.
</Tip>

## SSO and two-factor authentication

| Scenario                                      | Behavior                                             |
| --------------------------------------------- | ---------------------------------------------------- |
| SSO enforced, 2FA enabled in HoopAI           | HoopAI's 2FA is **skipped** — your IdP handles MFA   |
| SSO enforced, IdP has MFA                     | Users complete MFA at the IdP before reaching HoopAI |
| SSO not enforced, user chooses password login | HoopAI's 2FA applies as normal                       |

<Note>
  For maximum security, enable MFA in your identity provider rather than relying on HoopAI's built-in 2FA when SSO is active.
</Note>

## Disabling SSO / fallback to password login

If you need to disable SSO:

1. Log in as an admin (admins can always use password login if enforcement excludes them)
2. Go to **Settings > Security > SSO / SAML**
3. Toggle **Enforce SSO** to off
4. All users regain access to password-based login
5. Optionally, remove the SAML configuration entirely by clicking **Delete SSO configuration**

## Troubleshooting SSO login failures

<AccordionGroup>
  <Accordion title="Certificate expired">
    SAML assertions are signed with an X.509 certificate. If your IdP's certificate has expired:

    1. Generate or renew the certificate in your IdP
    2. Download the new metadata XML
    3. Upload it in **Settings > Security > SSO / SAML** to update the certificate
    4. Test the connection again
  </Accordion>

  <Accordion title="Attribute mismatch — user not found">
    This occurs when the email in the SAML assertion does not match any HoopAI user.

    * Verify the `NameID` or `email` attribute is set to the user's **primary email**
    * Check for typos or domain mismatches (e.g., `company.com` vs `company.org`)
    * If JIT provisioning is off, the user must be invited to HoopAI first
  </Accordion>

  <Accordion title="Clock skew error">
    SAML assertions include timestamps. If your IdP server clock and HoopAI's clock differ by more than 5 minutes, authentication fails.

    * Sync your IdP server to an NTP time source
    * Most cloud IdPs (Okta, Azure AD, Google) handle this automatically — check on-premise IdP servers
  </Accordion>

  <Accordion title="Redirect loop or blank page after login">
    * Confirm the **ACS URL** in your IdP matches exactly what HoopAI provides (no trailing slashes)
    * Clear browser cookies and try again
    * Try in an incognito/private window
  </Accordion>

  <Accordion title="User sees password login instead of SSO">
    * SSO enforcement may not be turned on — check **Settings > Security > SSO / SAML**
    * The user may be an admin excluded from enforcement
    * The user may be accessing a direct password-login URL — share the SSO login URL instead
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use multiple identity providers?">
    HoopAI supports one SAML IdP configuration per account. If you need multiple IdPs, configure a federation proxy (e.g., Azure AD B2B) that aggregates them into a single SAML endpoint.
  </Accordion>

  <Accordion title="Does SSO work with the HoopAI mobile app?">
    Yes. The mobile app redirects to your IdP's login page in an in-app browser when SSO is enforced.
  </Accordion>

  <Accordion title="What happens if my IdP goes down?">
    If SSO is enforced and your IdP is unreachable, users cannot log in. Keep at least one admin excluded from SSO enforcement so they can disable it in an emergency.
  </Accordion>

  <Accordion title="Is SCIM provisioning supported?">
    SCIM-based user provisioning and de-provisioning is available on select Enterprise plans. Contact your account manager for details.
  </Accordion>
</AccordionGroup>