Setting Up and Using SAML Single Sign-On

Taylor Sloane Updated by Taylor Sloane

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.

  1. In your HelpDocs account head to Settings > Users > Access (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

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.

  1. Head to Settings > Users > Access
  2. Under Single Sign On find SAML2 and click ā‹® More > Connect
  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?

Setting Up Two-Factor Authentication

Restricting your HelpDocs with Custom JWT SSO

Get in touch

This site is protected by hCaptcha and its Privacy Policy and Terms of Service apply.