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. πͺ
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.
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.
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 |
| Full access to that one group |
| Full access to both groups |
| 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 |
| A comma separated string |
| A JSON array. This is what Okta, Microsoft Entra ID, Auth0, and Keycloak send by default |
| 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.
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.
- Head to Settings > Sign-in & access
- Under Single sign-on find OpenID Connect and click the β― menu > Connect
- Fill in your Provider URL, Client ID, and Client Secret
- 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.
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.