Enabling SSO with Azure AD Premium 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, Azure AD Premium etc.).

Setting up SSO with Azure AD Premium

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

Note: To set up the SAML SSO integration with Help Scout you need an Azure Active Directory Premium license (either P1 or P2). The basic subscription to Azure AD allows access to Microsoft's app gallery, which only supports Help Scout using regular username/password logins rather than SAML SSO.

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 Manage → Company → 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 Azure as an administrator, then click on Azure Active Directory from the menu on the left-hand side.

4

Once in the directory, click on Enterprise applications under Manage on the left.

5

Next, click on + New Application from the main section of the screen.

6

Select All from the list of categories on the left-hand side to open the Add an application screen, then select Non-gallery application.

7

In the Add your own application section on the right, give your new application a name (ie. Help Scout), then click Add to launch the app creation wizard.

8

Next, select Configure single sign-on from the Quick start screen.

9

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.

10

Enter a notification email for the certificate expiry reminders, then click Save at the top on the screen.

11

Azure does not provide the X.509 certificate as a file that you can download directly, so we have to create it. First download the Metadata XML file.

Then, open the XML file and find the following section.

...<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><KeyDescriptor use="signing"><KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#"><X509Data><X509Certificate>{{ certificate is here }}</X509Certificate></X509Data></KeyInfo></KeyDescriptor>...

Copy the content of the X509Certificate tag and paste it into a new file. Then add -----BEGIN CERTIFICATE----- as the first line of the file and -----END CERTIFICATE----- as the last line of the file. The content should be something like this:

-----BEGIN CERTIFICATE-----
MII... {{ certificate content goes here, either as one or many lines }}
-----END CERTIFICATE-----

Save the resulting file as azure-helpscout.pem, we'll come back to this in Step 17.

12

Click on Configure Help Scout at the bottom of the screen and then copy the SAML Single Sign-On Service URL. This will also be needed in Step 17.

13

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.

14

With that, your app configuration within Azure is now complete! Back in Help Scout, head over to Manage→Company→Login, and toggle Enable SAML on.

15

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.

16

Next, enter your company or organization's email domain(s) in the Email Domainsfield. You can separate multiple domains with a comma. Anytime a Help Scout User or Administrator who enters that specific domain on the Help Scout log-in page will be routed to your Identity Provider to authenticate with their credentials.

17

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.

18

Click Save and you'll be ready to go!

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 16 will be taken to Azure AD to authenticate, and then redirected to Help Scout upon a successful log in.

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