Enabling SSO with Azure AD 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 Azure AD. 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, Azure AD etc.).
Setting up SSO With Azure AD
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.
Login to Help Scout, then navigate to Manage → Company → Authentication.
Before making any changes on this page, take note of the Post-back URL and the Audience URI at the bottom of the page.
Log in to Azure as an administrator, then click on Azure Active Directory from the menu on the left-hand side.
Once in the directory, click on Enterprise applications under Manage on the left.
Click on + New Application from the main section of the screen.
Select All from the list of categories on the left-hand side to open the Add an application screen. Then, enter Help Scout into the search field in the Add from the gallery section.
Select Help Scout from the list of found apps, then click Add to launch the app creation wizard.
Select Configure single sign-on from the Quick start screen.
Now it's time to start configuring your new application. Select SAML-based Sign-on from the Single Sign-On Mode dropdown menu, then paste the Audience URI from Step 3 into the Identifier field and the Post-back URL into the Reply URL field. Lastly, select user.mail from the User Identifier menu.
In the User Attributes section, you can optionally add a first name and last name attribute. Select Add a new claim to open the Manage user claims dialog. In the Name section of the menu, type firstName. Leave Namespace blank, select Attribute, and pick the correct Source attribute. For the surname, repeat the same process, and set the attribute Name as lastName.
Ensure that you have an active certificate by clicking Create new certificate and/or ticking Make new certificate active if necessary. Then enter a notification email for the certificate expiry reminders and click Save at the top on the screen.
Click on Configure Help Scout at the bottom of the screen and then Download Azure AD Signing Certificate (Base64 encoded). The downloaded file - Help Scout.cer - will be needed later in Step 15.
Note: If at this point the Download Azure AD Signing Certificate (Base64 encoded) link is not available (e.g. showing a message that the certificate has not yet been generated), or it is available but clicking on it does not trigger the file to download, you will have to close the app configuration and reopen it. You can return to this section via Azure Active Directory > Enterprise applications > All applications > Help Scout > Single sign-on. If that doesn't help reload the Azure portal in your browser, refresh your browser by hitting Ctrl/Cmd + R and try downloading the certificate again.
From the Configure sign-on section copy the Azure AD Single Sign-On Service URL. This will also be needed in Step 15.
Next up - granting your teammates access! Just exit the Configure sign-on section from the last step and head over to Users and groups to grant your users access to the Help Scout app.
With that, your app configuration within Azure is now complete! Back in Help Scout, head over to Manage → Company → Authentication, and toggle Enable SAML on.
Once SAML has been enabled, you will need to upload the certificate from Step 11 via the Upload Certificate button and enter the Service URL that you copied in Step 12 in the Single Sign-On URL field.
Lastly, you can toggle Force SAML Sign-in if you want Users to only log in to Help Scout via through this method. If you'd still like to leave the option for them to sign in with their Help Scout credentials, you can leave it toggled off. Even if this is enabled, an Account Owner will always be able to log in to Help Scout with their account password.
Click Save and you'll be ready to go!
Single Sign-On will now be enabled for your account. Users must first log in via the identity provider prior to logging in to Help Scout.