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 > Sign-in & access
Under Single sign-on find SAML2 and click the ⋯ menu > Connect
Click View SP Metadata
Provide this metadata to your IDP

Add HelpDocs Manually

If your IDP 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. If the Name ID is blank and there's no email attribute, sign-in is refused with a "That response was incomplete" error.

Assertions

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

Attributes are optional. Sign-in works even if your IDP sends no attribute statement at all, which is the Okta default. In that case we use the email address from the Name ID. You only need to add attributes if you want to send names, a role or Permission Groups.

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`, `writer`, or `externalviewer` (the Read only role). If it differs from the user's current role we update it at sign-in, but we never change an owner's role.
userGroups	The Permission Groups you'd like to assign this user (optional). The Group IDs, described below.

If you don't send a role, new accounts created through SAML get the role on their invitation if they have one. Otherwise they get the Default role under Settings > Sign-in & access > New people

Assigning Permission Groups with userGroups

Each value in userGroups is the Group ID of one of your Permission Groups. That's a ten character code like bj5lezkgzv, not the group's name.

To find a Group ID head to Settings > Groups, then click Edit on the group row. The Group ID is shown just under the Edit Group heading.

Send a single ID, or several. Add :read after an ID to give read-only access to that group's articles instead of full access.

userGroups value	What the user gets
`bj5lezkgzv`	Full access to that one group
`bj5lezkgzv,xawhraks28`	Full access to both groups
`bj5lezkgzv,xawhraks28:read`	Full access to the first group, read-only access to the second

What userGroups Can Look Like

You can send several groups either as one comma separated value, or as a multi-valued attribute with one <AttributeValue> element per group. We read every value either way, so you can use whichever your IDP produces by default. Okta and Entra ID send separate elements.

<saml2:Attribute Name="userGroups">
  <saml2:AttributeValue>bj5lezkgzv</saml2:AttributeValue>
  <saml2:AttributeValue>xawhraks28:read</saml2:AttributeValue>
</saml2:Attribute>

Spaces around the commas are fine, repeated values are collapsed, and an ID written with a group: prefix (group:bj5lezkgzv, or group:bj5lezkgzv:read) works the same as the bare ID.

Roles go in the role assertion, not in userGroups. Group IDs are the only values userGroups assigns.

A value that doesn't match a Permission Group on your account is ignored, so a mistyped ID signs the user in without that group rather than showing an error.

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 > Sign-in & access
Under Single sign-on find SAML2 and click the ⋯ menu > 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 🎉

The button says Sign in with SAML2. To use the name your team knows it by, click the ⋯ menu > Edit button label and fill in Sign in button text.

To limit who can sign up through SSO, add your domains to Email domains in the same section.

Requiring SSO

Once SSO is working you can turn off password sign-in for your whole account with Require SSO.

Require SSO applies to everyone on your account, including the owner, except guests. Guests sign in through their own organization. Sign in with SSO yourself before you turn it on, because a password won't get you in afterwards.