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. 🀩

You'll need to be on the Growth plan or above to use 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.

  1. In your HelpDocs account head to Settings > Access Control (or click here)
  2. Under SAML 2.0, hit the button to View SP Metadata
  3. 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

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

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.

  1. Head to Settings > Access Control (or click here)
  2. Under Single Sign-On, click SAML
  3. In the code editor, paste in your IDP XML Metadata
  4. 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. πŸŽ‰


What did you think of this doc?