Enable SSO with a Generic Identity Provider

Enabling single sign-on (SSO) for your domain within Help Scout allows your Users to easily and securely log in to their accounts. This article will help you get set up if we do not have a specific guide for your IdP. For more general information on adding and using SSO with Help Scout, check out Enabling SSO in Your Account. The SSO feature is available on the Pro plan or as an add-on to the Plus plan.

What is SSO?

Single sign-on (or SSO) is a way to authenticate and log in to an application with just one set of credentials, rather than having to set up multiple usernames and passwords across different platforms. It's a more secure process and prevents potentially losing or forgetting login credentials since it's stored through another service. 

SAML is an open standard for allowing single sign-on between 2 systems: A Service Provider (that's Help Scout) and an Identity Provider (that's the system storing your organization's user database e.g. Okta, OneLogin etc.).

Setting up SSO with a Generic Identity Provider

This section explains step by step how to configure SAML Single Sign-On between Help Scout and a generic Identity Provider. Please see the separate articles listed below for setup instructions if your Identity Provider is Okta, OneLogin, or Azure AD:

• Enabling SSO with Okta as the Identity Provider
• Enabling SSO with OneLogin as the Identity Provider
• Enabling SSO with Azure AD as the Identity Provider

Note: Service Provider (Help Scout) provisioning is not supported. Accounts should be created first in the IdP or Help Scout, and then authenticated via the IdP prior to logging in to Help Scout. 

You'll need to be either the Account Owner or an Administrator to get this setup for your account.

1

Login to Help Scout, then navigate to Manage → Company → Authentication. 

2

Before making any changes on this page, take note of the Post-back URL and the Audience URI at the bottom of the page.

3

Log in to your preferred Identity Provider as an administrator.

4

Following the IdP documentation, create an "app" that uses the Post-back URL and the Audience URI from step 2. You can also upload a Help Scout logo (if that option is available) to make it easier for users to see which application they are signing in to. Help Scout allows for three optional attributes in the SAML Response: given_name, family_name, and email.

5

Configure the IdP application to allow access to all the relevant users within the organization. This can typically be done either manually or by using groups/roles defined within the IdP users list.

6

Now that you have the app created, locate the Single Sign-On URL and the X.509 Signing Certificate. The certificate should be a file for download, if it is simply displayed on the page then copy it and save it as a file.

7

Head back to Help Scout, then navigate to  Manage → Company → Authentication. You can now click Enable SAML . 

8

On the form that you are presented with, use the details from step 6. Paste the URL and upload the certificate.

Note: If the certificate upload fails with an error saying the certificate has to be in PEM or CER format then you will have to convert the certificate before uploading it to Help Scout. Your IdP will indicate what sort of certificate it is providing, so use that to find out the easiest way of converting the certificate. An example command for converting a CRT certificate to a PEM certificate is as follows:

openssl x509 -in idpcertificate.crt -out convertedcertificate.pem -outform PEM

9

Toggle Force SAML Sign-in if you want users to only log in to Help Scout via SSO with the Identity Provider. Even if this is selected, an Account Owner will always be able to log in to Help Scout with their account password (this is to prevent the Account Owner from getting locked out). Don't forget to click the Save button.

Single Sign-On will now be enabled. Users need to log in via the identify provider prior to logging in to Help Scout.