Enabling SSO with Okta as the 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 your IdP is Okta. For more general information on adding and using SSO with Help Scout, check out Enabling SSO in Your Account.
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.
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 Account Owner or an Administrator to get this setup for your account.
- Once you've logged in to Help Scout, head to Manage > Company > Authentication.
- Before making any changes, take note of the Post-back URL and the Audience URI at the bottom of the page.
- Log in to Okta as an administrator, go to Admin > Applications (menu) > Applications (item).
Add Application button.
Create New App under the "Can't find an app?" heading on the left.
SAML 2.0 as the sign on method and click
Help Scout as the name of the new app. If you wish to upload a Help Scout logo select an image (you can take the icon from our
logos file, but you will need to resize it to fit the Okta size restrictions) and click on the
Upload Logo button, then
Post-back URL and the
Audience URI from step 2 into
Single sign on URL and
Audience URI (SP Entity ID) respectively.
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.
- On the final set up screen pick I'm an Okta customer adding an internal app to answer the question "Are you a customer or partner?", and click Finish.
The app is now created, but none of your Users can access it yet. Assign them to the app either individually via the
or as part of groups using the Groups tab.
Navigate to the
Sign On tab.
- 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. You will need these to complete step 16.
Log out from Okta (you will want to test with a non-admin user in a moment).
- Head back to Help Scout, then head to Manage > Company > Authentication . You can now click Enable SAML.
- Paste the URL and upload the certificate that you saved from step 13.
- Toggle Force SAML Sign-in if you want Users to only log in to Help Scout via SSO with Okta. 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 is now enabled. Users who try to log in with an email address for any of the domain(s) set in step 17 will authenticate with Okta and redirected to Help Scout upon a successful log in.