Skip to main content

SAML SSO for the Huntress Platform

Tyler
  • Updated

Team: Huntress Platform
Product: Huntress Platform
Environment: Huntress Platform and third-party identity providers
Summary: Configure and enforce SAML single sign-on for Huntress users.

In this Article

Overview

Before You Begin

Huntress Guides for SSO Configuration

Setup Guides for Common Identity Providers

Add Your Provider to Huntress

Enforce SAML SSO (Optional)

Disable Huntress 2FA for Enforced SSO

Troubleshooting

Overview

Single Sign-On (SSO) lets Huntress users authenticate with an existing SAML 2.0 identity provider (IdP), such as Microsoft Entra ID, Okta, Google Workspace, Cisco Duo, WatchGuard AuthPoint, or miniOrange.

Before You Begin

Review the following requirements and limitations before setting up SAML SSO.

Account-Level Support Only

SAML SSO is supported for Account-level logins only. It is not supported for Organization-level or Reseller-level logins.

Manual User Provisioning

SAML SSO does not automatically create Huntress users. Add each user to Huntress before they sign in through SSO, and confirm that they accept their Huntress invitation.

Email Attribute Claim

Your identity provider must send the user’s Huntress login email in the email claim. For Microsoft Entra ID, use the claim name http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. Other identity providers might use a different label for the same email value.

Single SSO Configuration

Only one SSO configuration is permitted per Huntress account.

Multi-Account Limitations

Users who belong to multiple Huntress accounts cannot use SAML SSO unless all accounts share the same configuration. If a user needs access across multiple accounts, consider using email aliases.

Email Address Is Unavailable

If your email address is unavailable in Preferences, check whether SSO enforcement is enabled.

If SSO is enforced, disable Enforce SSO to edit your email address. You do not need to disable SSO completely; disable only the enforcement setting. After updating your email address, re-enable SSO enforcement if needed.

Users must still set and remember their Huntress password. A Huntress password is required to change user preferences (such as name or phone number) or if SSO enforcement is temporarily turned off.

Huntress Guides for SSO Configuration

Use these Huntress guides for provider-specific configuration steps and SAML SSO troubleshooting.

Setup Guides for Common Identity Providers

Use these third-party guides to manually create a SAML application with your identity provider. The steps and field names can vary by provider.

Attribute Mapping

If you use an identity provider other than Microsoft Entra ID, such as Cisco Duo, you might need additional attribute mappings.

NameID Attribute Format:urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

SAML Response Attribute Identity Provider Attribute
NameID <Email Address>
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname <First Name>
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname <Last Name>

Example mappings in Entra:

mceclip0.png
mceclip1.png

Add Your Provider to Huntress

  1. Log in to Huntress and go to Account Settings.

  2. Select Set Up SAML SSO. (If this option is missing, contact Huntress Support.)

  3. Enter the details provided by your SAML provider.
    • SSO Service URL: The login endpoint URL from your IdP.
    • Entity ID (URL): The unique identifier URL for your IdP.

    • Certificate: Copy and paste the X.509 Base64 certificate from your IdP.

      mceclip1.png
  4. Select Save.

Enforce SAML SSO (Optional)

Enforcing SSO requires all users within the account to authenticate using your SAML provider. Password-based logins for the Huntress Platform will be disabled.

  1. Go to Account Settings.
  2. Turn on the Enforce SSO toggle. You can allow specific users to bypass enforcement by enabling SSO Enforcement Bypass Users. Use this option for emergency administrator accounts that need a fallback sign-in method.
  3. Select Save.

If you use SSO Enforcement Bypass Users, keep Huntress 2FA enabled for those accounts. Users can manage their 2FA settings from Preferences; administrators cannot change these settings for them.

Before enforcing SSO, ensure all active users have successfully tested logging in via SSO. Enabling enforcement on an account where users belong to multiple accounts not configured for SSO will be blocked.

Disable Two-Factor Authentication for Enforced SSO

If your identity provider enforces multi-factor authentication (MFA), you can disable Huntress two-factor authentication (2FA) to avoid duplicate prompts.

mceclip2.png
  1. Log in to Huntress using SSO.
  2. Go to Profile Preferences > Two-Factor Authentication (2FA).

  3. Select Disable.

    mceclip1.png

Do not delete your existing MFA integration or backup codes. Select Disable so that Huntress stops prompting for secondary 2FA while preserving your integration settings.

Troubleshooting

Use a browser-based SAML tracing tool to capture the SAML response when SSO fails. SAML Chrome Panel can capture SAML requests and responses in Chrome. Firefox users can use SAML-tracer.

If you would like to contribute screenshots and setup information for products other than Microsoft Entra ID and Cisco Duo, please submit them to support@huntress.io.

Related articles