SSO with SAML

If you have an identity provider (IDP) that supports SAML 2.0, you can use it with FireHydrant as a single sign-on provider.

Prerequisites

• You'll need to reach out to our support team to enable SSO for your organization
• You will need Owner permissions to configure SSO settings on FireHydrant
• You will need administrative access to your IDP to create a new SAML application and administer users

Entra ID (Azure AD)

Setting up single-sign on with Entra ID enables employees in your Entra tenant to authenticate to and access FireHydrant accounts.

1. From the Entra Portal, click into Applications > Enterprise Applications

2. Click New Application > Create your own application

3. Name your app "FireHydrant" and select "Integrate any other application you don't find in the gallery (Non-gallery). Click Create.

4. Click into Single Sign-on once your app has been created and select SAML

5. Click Edit for "Basic SAML Configuration" and configure it as follows, then Save (please note all fields are case-sensitive).

   1. Identifier (Entity ID): firehydrant
      1. Add this as a second identifier without switching it to the default: https://app.firehydrant.io/sso/saml/consume
   2. Reply URL (Assertion Consumer Service URL): https://app.firehydrant.io/sso/saml/consume
   3. (Optional) If you want to enable SP-initiated sign-in, set the Sign on URL: https://app.firehydrant.io/sessions/new

6. Click Edit for "Attributes & Claims" and configure it as follows, then Save:

   1. Unique User Identifier (Name ID)

      1. Name identifier format: Email address
      2. Source: Set to attribute that stores the user's email address. This should match how you expect the user to appear in FireHydrant.

   2. Additional Claims

      Claim Name	Namespace	Recommended Mapping
      emailAddress	http://schemas.xmlsoap.org/ws/2005/05/identity/claims	Attribute that stores user's email address
      firstName	http://schemas.xmlsoap.org/ws/2005/05/identity/claims	user.givenname
      lastName	http://schemas.xmlsoap.org/ws/2005/05/identity/claims	user.surname

7. Under "SAML Certificates," download the Certificate (Base64). In order to open the certificate in a readable format that you can enter into FireHydrant, you will need to run to run the following:
   openssl x509 -in certificatename.cer -outform PEM -out certificatename.pem
   Open the resulting file in a text editor.

8. In a separate browser tab, open FireHydrant's SSO settings page and check Enable SSO. Enter the following information from Entra ID:

   Entra ID Value	FireHydrant Field
   Login URL	IdP Login URL
   Microsoft Entra Identifier	IdP Issuer
   Use the output from step 6	IdP X509 Certificate

   1. (Optional) Add a domain for SP-initiated logins. When users attempt to log in to FireHydrant directly with an email address that matches this domain, FireHydrant will display a note and redirect them to your IDP sign-in.

9. Click Save. You will now be able to test the login process from within Entra by assigning it to yourself and using the Test This Application button.

Google SSO

Setting up single sign-on with Google enables your G Suite account users to authenticate and access FireHydrant accounts.

1. Follow Google's instructions on setting up a custom SAML application until you get to the Google Identity Provider details page.
2. In a separate browser tab, open FireHydrant's SSO settings page and check Enable SSO. Three additional fields will appear: IDP Login URL, IDP Issuer, and IDP X509 Certificate. Copy the values from Google into FireHydrant as follows:

3. (Optional) In the Domains section of FireHydrant, you can add the email domain name for your organization.

   1. When users attempt to log in to FireHydrant directly with an email address that matches this domain, FireHydrant will display a note and redirect them to your IDP sign-in.

4. Click Save in FireHydrant.

5. In Google, click Next. Google prompts you to fill in Service Provider details. For the ACS URL and Entitiy ID fields, enter https://app.firehydrant.io/sso/saml/consume.

6. Enable the Signed Response checkbox.

7. Verify that Primary Email is selected for the Name ID section. This is how your SSO configuration automatically creates accounts or logs existing users into FireHydrant.

8. For the Name ID Format field, select Email. Click Next.

9. (Optional) On the last step of the Google setup, provide any attribute mappings you'd like to include when users are sent to FireHydrant. These are optional, but we recommend setting the first and last name attributes so when users are provisioned, their names are automatically set correctly in FireHydrant.

   

10. Click Finish. This completes your Google SSO setup.

Okta SSO

📘

Note:

When a user is authenticated with Okta, they are automatically added to the organization with a Member role if they do not have an account.

Otherwise, accounts are matched on the email provided by Okta on a successful login. When a user is removed from Okta, they are not automatically removed from FireHydrant.

Our Okta SAML integration is one-way - FireHydrant accounts will be automatically provisioned but not automatically de-provisioned. Users whose accounts are auto-provisioned with Okta are set to the Member role.

1. As an Okta admin, view all applications in the Applications tab. Then:
2. Click Browse App Catalog
3. Search for the FireHydrant app, click it, and then click Add Integration
4. Name your app and click Next. This will drop you onto the Assignments page.
5. Click into Sign On and go to View SAML setup instructions.
6. In a separate browser tab, open FireHydrant's SSO settings page and check Enable SSO. Enter the IDP Login URL, IDP Issuer, and IDP X509 Certificate details from Step #4 into FireHydrant.
   1. (Optional) Add a domain for SP-initiated logins. When users attempt to log in to FireHydrant directly with an email address that matches this domain, FireHydrant will display a note and redirect them to your IDP sign-in.
7. Enable SSO and save your configuration. This completes the setup for Okta SAML 2.0.

Generic

1. For other identity providers aside from Google and Okta, you can set up the integration by entering FireHydrant's SAML details as below when creating a new SAML application:
   1. Consumer URL: https://app.firehydrant.io/sso/saml/consume
   2. Recipient URL and Audience URL: Same as the consumer URL
   3. Audience: firehydrant
   4. Attribute statements: First Name as firstName, Last Name as lastName
2. After you've created your SAML application, you will then need to configure settings within FireHydrant:
   1. In FireHydrant, navigate to Settings > Single Sign On.
   2. On the Single Sign On page, check the box labeled  Enable SSO.
   3. Additional fields appear. In these fields, provide your IDP login URL, IDP issuer, and IDP X509 certificate as generated by your identity provider.
   4. (Optional) If you'd like, you can add Domains. When users attempt to log in to FireHydrant directly with an email address that matches this domain, FireHydrant will display a note and redirect them to your IDP sign-in.

Testing

To test, leave your session in FireHydrant open. Visit your IDP in a new window or tab and attempt to log in with your newly configured integration.

Leaving your FireHydrant session open should prevent you from getting locked out of your account during setup. If you encounter a lockout, submit a ticket on our contact form for help.

Common Errors (and how to fix them)

This guide explains the various error messages that users may encounter when attempting to log in via SAML SSO to FireHydrant, along with troubleshooting steps for each scenario.

Error Messages

"No Organization has been setup for that SSO issuer: [issuer_name]"

When this occurs:

• The SAML response contains an issuer that doesn't match any configured SSO settings in FireHydrant
• This typically happens when the Identity Provider (IdP) is sending an incorrect issuer value (or the issuer is not configured in FireHydrant correctly)

What to check:

• Verify that your Identity Provider's issuer/entity ID matches exactly what's configured in FireHydrant
• Check with your FireHydrant administrator to confirm the SSO configuration is complete
• Ensure you're using the correct SSO login URL for your organization

Next steps:

• Contact your FireHydrant administrator to verify the SSO configuration
• If the issue persists, email [email protected] with your organization name and the issuer value shown in the error

"Invalid SSO login - Invalid user for organization"

When this occurs:

• A user with your email address exists in FireHydrant but belongs to a different account/organization
• You're attempting to log in to an organization that you don't belong to

What to check:

• Confirm you're using the correct SSO login URL for your organization
• Verify with your administrator that your email should have access to this specific FireHydrant organization
• Check if you might have multiple FireHydrant accounts under the same email address

Next steps:

• Use the correct SSO login URL provided by your organization
• Contact your FireHydrant administrator to verify your account membership
• If you need to be added to the organization, have an admin invite you

"Your membership in this organization has been deactivated. Please contact one of your organization's owners for access."

When this occurs:

• Your user account exists but has been deactivated/disabled in the organization
• An administrator has removed your access, either intentionally or accidentally

What to check:

• Confirm with your team if there were any recent changes to user access
• Verify if this was an intentional deactivation (e.g., role change, department transfer)

Next steps:

• Contact your organization's FireHydrant administrator or owner
• Request reactivation of your account if appropriate
• Your admin can reactivate your account from the Users settings page

"Could not create account from SSO login: [specific_error_message]"

When this occurs:

• FireHydrant attempted to create a new user account based on your SSO login but failed
• The specific error message will provide more details about what went wrong

Common specific errors:

• User limit reached: For free tier accounts, there's a maximum of 10 users
• Invalid email format: The email from your IdP doesn't meet validation requirements
• Missing required attributes: Your IdP isn't sending required user information

What to check:

• Review the specific error message for details
• For user limit errors, check if your organization needs to upgrade their plan
• Verify your IdP is configured to send all required SAML attributes (email, name)

Next steps:

• Share the complete error message with your FireHydrant administrator
• For user limit issues, consider upgrading your FireHydrant plan
• Contact [email protected] with the full error message if unclear

"Invalid SSO login"

When this occurs:

• The SAML response from your Identity Provider is invalid or malformed
• The digital signature on the SAML response doesn't match the configured certificate
• The SAML response has expired or has timestamp issues

What to check:

• Ensure your Identity Provider's certificate in FireHydrant matches the current certificate
• Verify there are no time synchronization issues between your IdP and FireHydrant
• Check if your IdP recently updated their signing certificate

What to check:

• Try logging in again - sometimes this is a temporary issue
• Clear your browser cache and cookies
• Ensure you're not using a bookmarked/outdated SSO URL

Next steps:

• Have your administrator verify the SSO configuration, especially the certificate
• Check your Identity Provider's logs for any errors
• Contact [email protected] with timestamp of the failed attempt

General Troubleshooting Tips

1. Always use the SSO login URL provided by your organization, not the general FireHydrant login page
2. Clear browser cache and cookies if experiencing persistent issues
3. Use an incognito/private browser window to rule out browser-related issues
4. Check with colleagues to see if others are experiencing the same issue
5. Note the exact time of any errors to help with troubleshooting

Need Further Assistance?

If you continue to experience issues after following this guide:

1. Gather the following information:

   • Exact error message
   • Time and date of the error
   • Your email address
   • Organization name
   • Browser and version being used

2. Contact [email protected] with the above information

Our support team will help diagnose and resolve your SSO login issues as quickly as possible.