---
title: "Using OpenID Connect for Single Sign On"
description: "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. 💪"
url: "https://support.helpdocs.io/article/h961z8xb7r-using-open-id-connect-for-single-sign-on"
category: "Authentication"
updated_at: "2026-08-31T15:13:20Z"
---

# 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. 💪

Only some of [our plans](https://www.helpdocs.io/pricing/) 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](https://developers.google.com/identity/protocols/OpenIDConnect) or [Salesforce](https://developer.salesforce.com/page/Inside_OpenID_Connect_on_Force.com). 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 **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** > **Access** > **Options**

#### Assigning Permission Groups with user\_groups

Each value in **user\_groups** 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.

| 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 should **not** include the trailing */.well-known/openid-configuration*

1. Head to **Settings** > **Access** > **Options**
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](mailto:hi@helpdocs.io)