Skip to main content
Support

Using OpenID Connect for Single Sign On

If you're using OpenID Connect to let users log in to your own app already, you can use that exact same login for HelpDocs. πŸ’ͺ

Taylor
Updated by Taylor
4 min read

If you're using OpenID Connect to let users log in to your own app already, you can use that exact same login for HelpDocs. πŸ’ͺ

Only some of our plans have access to OpenID Connect SSO

Setup, Requested Scopes & Claims

To use OpenID Connect federation with HelpDocs you'll need to make sure you've got a standards-compliant OpenID Connect server with a public provider endpoint that our servers can use for discovery.

If you don't have an OpenID Connect server of your own you can also use our OpenID Connect to auth against a public identity provider like Google or Salesforce. Then users can use their login to those services rather than manually creating a HelpDocs account.

We request the openid, email, and profile scopes from your OpenID Connect server. We identify users by email, so make sure email is in the ID token. Without it, the user gets a placeholder address built from their subject ID, which won't match an existing HelpDocs user.

We read the email, given_name, and family_name claims from the ID token. You can also provide role (admin, editor, writer, or externalviewer, which is the Read only role) and user_groups if you want to assign these at login. If role differs from the user's current role we update it at sign-in, but we never change an owner's role.

If you don't send a role, new accounts created through OpenID Connect get the role on their invitation if they have one. Otherwise they get the Default role under Settings > Sign-in & access > New people. With Anonymous Mode on, read-only users don't get an account at all.

Assigning Permission Groups with user_groups

Each value in user_groups 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.

user_groups 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 user_groups Can Look Like

There's no standard groups claim in OpenID Connect, so providers format it differently. Most send a multi-valued claim as a JSON array rather than as a comma separated string. We accept either, so you can send whichever shape your provider emits by default.

Claim value

Shape

"bj5lezkgzv,xawhraks28"

A comma separated string

["bj5lezkgzv","xawhraks28"]

A JSON array. This is what Okta, Microsoft Entra ID, Auth0, and Keycloak send by default

["bj5lezkgzv,xawhraks28"]

An array whose values are themselves comma separated, which Entra ID claim transformations can produce

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 claim, not in user_groups. Group IDs are the only values user_groups 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.

Callback URL

When you set up HelpDocs in your SSO provider it'll ask you for a callback URL. That's https://your-domain.helpdocs.io/login/oidc/callback (replacing "your-domain" with your HelpDocs subdomain).

Setting Up OpenID Connect SSO in HelpDocs

Lastly you need to set up OpenID Connect in your HelpDocs dashboard. You'll need your server's Provider URL, Client ID, and Client Secret for this step.

Your Provider URL must be a public https address and should not include the trailing /.well-known/openid-configuration
  1. Head to Settings > Sign-in & access
  2. Under Single sign-on find OpenID Connect and click the β‹― menu > Connect
  3. Fill in your Provider URL, Client ID, and Client Secret
  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 OpenID Connect.

If your connection doesn't work right away get in touch

The button says Sign in with OpenID Connect. 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

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.

What did you think of this doc?

Previous Restricting your HelpDocs with Custom JWT SSO Next Setting Up and Using SAML Single Sign-On