Using OpenID Connect for Single Sign On

Jake Peters Updated by Jake Peters

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. If email is not provided, login will fail for your users.

We expect custom claims for email, given_name & family_name. You can also provide role (admin editor or externalviewer) and a comma separated list of user_groups if you want to assign these at login.

New accounts created through OpenID Connect get the default role you've configured on your account in Settings > Users > Access

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 should not include the trailing /.well-known/openid-configuration
  1. Head to Settings > Users > Access
  2. Under Single Sign On click OpenID 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

What did you think of this doc?

Restricting your HelpDocs with Custom JWT SSO

Configuring Slack Single Sign On

Get in touch