--- title: "Setting Up and Using SAML Single Sign-On" description: "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." url: "https://support.helpdocs.io/article/i8fpdjc43n-setting-up-saml-single-sign-on" category: "Authentication" updated_at: "2026-08-31T15:13:49Z" --- # 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](https://www.helpdocs.io/pricing/) 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](https://www.okta.com/), 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](mailto:hi@helpdocs.io). #### 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** > **Options** (or [click here](https://my.helpdocs.io/app/settings?tab=users)) 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 | The [Permission Groups](/article/zcf0rx726v-managing-permission-groups) you'd like to assign this user (optional). The Group IDs, described below. | New accounts created through SAML get the default role you've configured on your account in **Settings** > **Access** > **Options** #### Assigning Permission Groups with userGroups Each value in **userGroups** is the **Group ID** of one of your [Permission Groups](/article/zcf0rx726v-managing-permission-groups). That's a ten character code like `bj5lezkgzv`, not the group's name. To find a Group ID head to **Settings** > **Access** > **Groups**, then click ☰ **More** > **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 `` 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. ```xml bj5lezkgzv xawhraks28:read ``` 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. 1. Head to **Settings** > **Access** > **Options** 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 🎉