Ferndesk
Authentication

OIDC SSO Authentication

Use your existing identity provider (Okta, Auth0, Google, etc.) to authenticate users accessing your help center via OpenID Connect (OIDC).

Requires a Team or Enterprise plan with Private mode enabled.

What You'll Need

From your identity provider:

  • Discovery URL: The .well-known/openid-configuration endpoint

  • Client ID: Your application identifier

  • Client Secret: Confidential key for token exchange

  • Scopes: At minimum openid, profile, and email

Setting Up OIDC

  1. Go to Help Center > Customize > Access Control

  2. Select Private mode

  3. Open the Login methods accordion

  4. Click Add OIDC Provider

  5. Fill in your provider details:

    • Discovery URL: Usually ends with .well-known/openid-configuration

    • Client ID: From your provider's app settings

    • Client Secret: Keep this secure

    • Scopes: openid profile email (space-separated)

  6. Click Save changes

Ferndesk will fetch your provider's configuration from the discovery URL to complete the setup.

The discovery URL must be publicly accessible and return valid OIDC configuration. Test it in your browser first.

Redirect URI for Your Provider

Configure this callback URL in your identity provider:

https://<your-help-domain>/auth/oidc/callback

This is where users return after authenticating.

Testing OIDC

  1. Open your help center in an incognito window

  2. Click the SSO sign-in button

  3. Authenticate with your identity provider

  4. Verify you're redirected back and can access content

Preview your sign-in page immediately by saving changes. The Access Control settings page shows a live preview iframe.

Common Setup Issues

Invalid discovery URL

The URL must return JSON with issuer, authorization_endpoint, and token_endpoint fields. Common fix: ensure it ends with .well-known/openid-configuration

Client authentication failed

Client ID or secret is incorrect. Double-check values from your provider's dashboard.

Scope error

Your provider must support openid, profile, and email scopes. Check provider documentation for required scopes.

Redirect URI mismatch

Ensure https://<your-help-domain>/auth/oidc/callback is whitelisted in your provider's allowed callback URLs.

Provider-Specific Examples

Okta

  • Discovery URL: https://your-domain.okta.com/.well-known/openid-configuration

  • Create a Web App Integration in Okta

  • Use Authorization Code flow

Auth0

  • Discovery URL: https://your-domain.auth0.com/.well-known/openid-configuration

  • Create a Regular Web Application

  • Enable password grant if using username/password login

Google

  • Discovery URL: https://accounts.google.com/.well-known/openid-configuration

  • Create OAuth 2.0 credentials in Google Cloud Console

  • Application type: Web application

Multiple Providers

You can enable OIDC alongside Magic Links and JWT. Users will see all options on the sign-in page and can choose their preferred method.

Disabling OIDC

To remove OIDC authentication:

  1. Go to Access Control settings

  2. Click Remove OIDC Provider

  3. Save your changes

Active sessions remain valid until they expire.

Was this helpful?