Skip to main content
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

SSO with SAML is available on the Enterprise plan only. Contact your account manager to enable it.
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 or Agency Owner role in HoopAI

​
Supported identity providers

Identity providerStatusNotes
OktaFully supportedPre-built integration available
Microsoft Azure AD (Entra ID)Fully supportedEnterprise application template
Google WorkspaceFully supportedCustom SAML app setup
OneLoginFully supportedConnector available
Custom SAML 2.0SupportedAny IdP that supports SAML 2.0

​
Step-by-step SAML setup

1
Locate your HoopAI SAML details
2
Navigate to Settings > Security > SSO / SAML. You will see three values you need to provide to your IdP:
3
FieldDescriptionExampleEntity ID (Audience URI)Unique identifier for HoopAI as a service providerhttps://app.hoopai.com/saml/metadataACS URL (Reply URL)The endpoint where your IdP sends the SAML assertionhttps://app.hoopai.com/saml/acsMetadata URLXML document describing HoopAI’s SAML configurationhttps://app.hoopai.com/saml/metadata.xml
4
Copy these values — you will paste them into your IdP in the next step.
5
Configure your identity provider
6
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
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
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
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
7
Configure attribute mapping
8
Your IdP must send these attributes in the SAML assertion:
9
SAML attributeRequiredMaps toExpected valueemail or NameIDYesUser emailUser’s primary email addressfirstNameRecommendedFirst nameGiven namelastNameRecommendedLast nameFamily nameroleOptionalHoopAI roleadmin, user, or a custom role name
10
If firstName and lastName are not provided, HoopAI will use the portion before @ in the email as the display name.
11
Enter IdP details in HoopAI
12
Back in Settings > Security > SSO / SAML:
13
  • Paste your IdP Metadata URL — or upload the metadata XML file
  • HoopAI will auto-populate the IdP SSO URL, IdP Issuer, and X.509 certificate
  • Click Save configuration
    • 14
    Test the connection
    15
  • Click Test SSO connection
  • A new window opens and redirects you to your IdP login page
  • Authenticate with your IdP credentials
  • If successful, you are redirected back to HoopAI with a “Connection verified” message
    • 16
    Do not enforce SSO until you have successfully tested the connection. Enforcing a broken SSO configuration can lock all users out.
    17
    Enforce SSO for all users
    18
    Once testing succeeds:
    19
  • Toggle Enforce SSO to on
  • Choose an enforcement scope:
    • All users — every user must log in via SSO
    • All users except admins — admins retain password login as a fallback
  • Click Save
    • 20
    After enforcement, the standard email/password login form is hidden for affected users. They see a Log in with SSO button instead.

    ​
    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
    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.

    ​
    SSO and two-factor authentication

    ScenarioBehavior
    SSO enforced, 2FA enabled in HoopAIHoopAI’s 2FA is skipped — your IdP handles MFA
    SSO enforced, IdP has MFAUsers complete MFA at the IdP before reaching HoopAI
    SSO not enforced, user chooses password loginHoopAI’s 2FA applies as normal
    For maximum security, enable MFA in your identity provider rather than relying on HoopAI’s built-in 2FA when SSO is active.

    ​
    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

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

    ​
    FAQ

    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.
    Yes. The mobile app redirects to your IdP’s login page in an in-app browser when SSO is enforced.
    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.
    SCIM-based user provisioning and de-provisioning is available on select Enterprise plans. Contact your account manager for details.
    Last modified on March 6, 2026