Setting Up and Using SAML Single Sign-On

Need to use HelpDocs with a large team? Signing up individually can be tiresome. With SAML Single Sign-On (SSO) you can make it super simple for your team to log in and get started.

There's a few things to set up before you can start using it, so let's get going 🤩

Only some of our plans have access to SAML SSO

Add the HelpDocs Service Provider to your Identity Provider

To use SAML federation with HelpDocs as a Service Provider (SP) you'll need to make sure you've got an Identity Provider (IDP) set up. We'll redirect users to your IDP to make a connection 💞

We've designed our platform to work with SAML 2.0 and tested against a variety of IDPs including Okta, but any standards-compliant SAML 2.0 implementation should work out of the box.

If your connection doesn't work right away, please get in touch.

Add HelpDocs with XML Metadata

If your IDP supports it, the easiest way to add HelpDocs' SP to your IDP is with our XML metadata.

In your HelpDocs account head to Settings > Users > Access (or click here)
Under SAML 2.0, hit the button to View SP Metadata
Provide this metadata to your IDP

Add HelpDocs Manually

If your SP doesn't support configuration with metadata, you can add it manually. Here's what you'll need to share with your IDP:

Attribute	Value
Assertion Consumer Service	https://{your-subdomain}.helpdocs.io/login/saml2/post
Entity ID	https://{your-subdomain}.helpdocs.io
Name ID Format	emailAddress

Since we identify users by email address, you'll need to pass us the user's email address as the Name ID.

Assertions

When a new user tries to access HelpDocs through SAML we'll create an account for them. To make the experience more fluid you can pass us their first and last names as custom assertions.

Assertion	Value
firstName	The user's first name
lastName	The user's last name
role	The role you'd like to assign this user in HelpDocs (optional). Possible values: `admin` `editor` `externalviewer`
userGroups	Any user groups you'd like to assign to this user in HelpDocs (optional). This must be provided as a comma separated list of user group IDs.

New accounts created through SAML get the default role you've configured on your account in Settings > Users > Access

Setting Up SAML SSO in HelpDocs

Now that you have your IDP set up you can tell HelpDocs to use SAML as a login method. You'll need your IDP's XML metadata for this step.

Head to Settings > Users > Access
Under Single Sign On find SAML2 and click ⋮ More > Connect
In the code editor paste in your IDP XML Metadata
Hit Connect

If everything's gone ok, you'll now see a button on the login page of your account to log in with SAML 🎉