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. 🤩
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.
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 > Access Control (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:
Assertion Consumer Service
Name ID Format
Since we identify users by email address, you'll need to pass us the user's email address as the Name ID.
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.
The user's first name
The user's last name
The role you'd like to assign this user in HelpDocs (optional). Possible values:
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.
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 > Access Control (or click here)
- Under Single Sign-On, click SAML
- 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. 🎉