Enabling SSO with Onelogin as the Identity Provider

In this article

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 log-in 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 Onelogin

This section explains step by step how to configure SAML Single Sign-On between Help Scout and Onelogin as the Identity Provider. If you are using a different Identity Provider please see the  Enabling SSO with a Generic Identity Provider article.

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

1
Login to Help Scout, then navigate to ManageCompany →  Login.
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 Onelogin as an administrator, go to AppsAdd Apps.
4
Type "saml" into the search box of the Find Applications page. From the filtered list pick SAML Test Connector (IdP w/attr).
5
Enter "Help Scout" as the Display Name of the new app, keeping it Visible in portal. If you'd to upload a Help Scout logo, click on the Rectangular icon and Square icon and select the images you want to use. You can take these from the "logo" and "icon" folders respectively within our  brand assets .zip file. Click the Save button.
6
Go to the "Configuration" tab and paste the "Post-back URL" from step 3 twice into the "ACS (Consumer) URL" and "Recipient" fields and the "Audience URI" from step 3 into the "Audience" field. Paste the regular expression listed below into the "ACS (Consumer) URL Validator".

[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)

7
Click Save to store the app settings.
8
Head over to the "Parameters" tab and select "Add parameter". Type in "email" as the name in the popup and check "Include in SAML assertion". Once saved, the new parameter will have no value, so you'll need to click on "- No default -" in the value column, and within the next popup, select "Email" as the value from the dropdown.

9
The app is now created, but none of your users can access it. You can assign them to the app either individually via "Users" menu → "All Users" or, depending on how you manage your user base, as part of roles ("Users" → "Roles") and groups ("Users" → "Groups").
10
Navigate back to the "Help Scout" app and select the "SSO" tab. Copy the "SAML 2.0 Endpoint (HTTP)" and click "View details" for the "X.509 Certificate" - this opens a new page where you can click the "Download" button to download the onelogin.pem file. You will need both the "SAML 2.0 Endpoint (HTTP)"  and the "X.509 Certificate" in step 15.

11
Log out from Onelogin (you will want to test with a non-admin user in a moment).
12
Head back to Help Scout  Manage → Company →  Login. You will not be able to click "Enable SAML"
13
On the form that you are presented with, use the details from step 10 - paste the URL and upload the certificate.
14
Provide the email domain(s) that will trigger Single Sign-On. The login screen will be aware of these domains and users trying to login with an email from either of these domains will be taken through single sign-on.
15
Toggle Force SAML Sign-in if you would like your Users to only log in to Help Scout via SSO with Onelogin. 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 for your account. Users who try to login with an email address for any of the domain(s) provided in step 14, will be taken to Onelogin to authenticate, and then redirected to Help Scout upon a successful log in.

Still stuck? How can we help? How can we help?