Enable SSO with OneLogin as the Identity Provider
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 your IdP is OneLogin. For more general information on adding and using SSO with Help Scout, check out Enable SSO in Your Account. The SSO feature is available on the Pro plan or as an add-on to the Plus plan.
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 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 OneLogin
This section explains step by step how to configure SAML Single Sign-On between Help Scout and OneLogin 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 the Help Scout Account Owner or an Administrator to get this setup for your account.
- Login to Help Scout, then navigate to Manage > Company > Authentication. If you do not see the option to Use SAML SSO on this page, see Enable SSO in your Account.
Do not toggle Enable SAML just yet! Take note of the
Post-back URL and the
Audience URI at the bottom of the page in your Help Scout account. You will need to copy and paste this information into OneLogin. You'll come back to this page to Enable SAML before the end.
Log in to OneLogin as an administrator, go to
Applications > Applications. Click the
Add App button in the top right corner.
- Search for test connector on the Find Applications page. From the filtered list pick SAML Test Connector (Advanced) for SAML 2.0
Help Scout as the
Display Name of the new app, and make sure
Visible in portal is on. If you'd like 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 our
logos file. Click the
Save button when these are all set.
You'll find a new left side navigation menu after saving. Click
Configuration. Paste the
Audience URI from Help Scout in to the
Audience (Entity ID) field. Paste the
Post-back URL from step 2 in to both the
ACS (Consumer) URL and
Recipient fields. Paste the regular expression listed below in to the
ACS (Consumer) URL Validator.
- Click Save to store the app settings.
Parameters in the left navigation menu. Click the
+ button to add a new field.
- Type in email as the name in the popup and check Include in SAML assertion, and click Save to go to the next screen. Click on - No default - in the value column on the next screen and select Email as the value from the dropdown. Click Save.
- Repeat this process for two more fields. Create a field first_name with the value mapped to First Name, and last_name mapped to value Last Name. You will have email, first_name, and last_name when you're back on the Parameters screen.
- You'll need to grant your users permission to the application you just created, either by adding to individual Users or by adding to Roles or Groups within OneLogin according to how you prefer to manage your Users there.
Navigate back to the Help Scout app and select
SSO from the left side navigation. 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 13.
Head back to Help Scout
Manage > Company > Authentication. Click
Enable SAML. Paste in the
SAML 2.0 Endpoint (HTTP) from OneLogin to the
Single Sign-On URL field and upload the X.509 certificate from OneLogin here.
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 using OneLogin is all set! Users need to log in via the identify provider prior to logging in to Help Scout.