Enabling SSO with Okta 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 Okta

This section explains step by step how to configure SAML Single Sign-On between Help Scout and Okta as the Identity Provider. If you are using a different Identity Provider, check out 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
Once you've logged in to Help Scout, head to ManageCompany →  Login
2
Before making any changes, take note of the Post-back URL and the Audience URI at the bottom of the page.
 
3
Log in to Okta as an administrator, go to Admin → Applications (menu) → Applications (item).
4
Click the Add Application button.


5
Click Create New App (under the "Can't find an app?" heading on the left).


6
Select SAML 2.0 as the sign on method and click the Create button.

7
Enter Help Scout as the name of the new app. If you wish to upload a Help Scout logo select an image (e.g. you can take the icon from our  brand assets zip file, but you will have to resize it to fit the Okta size restrictions) and click on the Upload Logo button, then click the Next button. 

8
Paste the Post-back URL and the Audience URI from step 2 into Single sign on URL and Audience URI (SP Entity ID) respectively.


9
On the same screen, but a little bit further down the page, you'll see the ATTRIBUTE STATEMENTS (OPTIONAL) section. You want to add three “attributes” there:

Name: " given_name", Name format: "Unspecified", Value: " user.firstName"
Name: " family_name", Name format: "Unspecified", Value: " user.lastName"
Name: " email", Name format: "Unspecified", Value: " user.email"Click the Next button to save the app settings.
10
On the final set up screen pick I'm an Okta customer adding an internal app when asked "Are you a customer or partner?", and finally press Finish
11
The app is now created, but none of your Users can access it. You can assign them to the app either individually via the People tab  


or as part of groups using the Groups tab.

12
Navigate to the Sign On tab.
13
Click the View Setup Instructions tab and from the new page that opens, copy the Identity Provider Single Sign-On URL and download the X.509 Certificate. These will be needed later in step 18.

14

Log out from Okta (you will want to test with a non-admin user in a moment).

15
Head back to Help Scout, then head to ManageCompany →  Login. You can now click Enable SAML.
16
On the form that you are presented with, use the details from step 14. Paste the URL and upload the certificate.
17
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.
18
Toggle Force SAML Sign-in if you want Users to only log in to Help Scout via SSO with Okta. 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 who try to login with an email address for any of the domain(s) provided in step 17, will be taken to Okta to authenticate, and then redirected to Help Scout upon a successful log in.

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