QuackbackQuackback
Navigation

Set up custom OIDC

One less password for your users. Connect any OpenID Connect provider - Okta, Auth0, Keycloak, or your own identity server - and let users sign in with their existing work accounts.

Overview

Custom OIDC lets you integrate any OAuth 2.0 / OpenID Connect identity provider beyond the built-in social logins. This is ideal for:

  • Enterprise SSO - Okta, Azure AD, Auth0, OneLogin, PingFederate
  • Self-hosted identity - Keycloak, Authentik, Zitadel, Authelia
  • Custom providers - Any service that supports OIDC discovery or manual OAuth 2.0 configuration

Configure Custom OIDC

Step 1: Register Quackback in your identity provider

Create an OAuth / OIDC application in your identity provider with these settings:

FieldValue
Application typeWeb application
Redirect URIhttps://YOUR_DOMAIN/api/auth/callback/custom-oidc
Scopesopenid email profile

Note the Client ID and Client Secret.

Step 2: Add credentials in Quackback

[Dashboard]

  1. Go to Admin → Settings → Portal Authentication (or Security for team auth)
  2. Find Custom OIDC in the provider list
  3. Fill in the required fields:
FieldDescriptionRequired
Display NameName shown on the sign-in button (e.g. "Okta", "Company SSO")Yes
Client IDFrom your identity providerYes
Client SecretFrom your identity providerYes
Discovery URLOIDC discovery endpoint (recommended)No
Authorization URLOAuth authorize endpointIf no Discovery URL
Token URLOAuth token endpointIf no Discovery URL
ScopesSpace-separated scopesNo (defaults to openid email profile)

Use the Discovery URL when your provider supports it. Quackback auto-discovers the authorization and token endpoints from /.well-known/openid-configuration, so you don't need to enter them manually.

Step 3: Enable the provider

Toggle Custom OIDC on in the Portal Authentication or Security settings. The sign-in button appears immediately.

Provider examples

Okta

FieldValue
Display NameOkta
Discovery URLhttps://your-org.okta.com/.well-known/openid-configuration
Client IDFrom Okta app
Client SecretFrom Okta app

Auth0

FieldValue
Display NameAuth0
Discovery URLhttps://your-tenant.auth0.com/.well-known/openid-configuration
Client IDFrom Auth0 app
Client SecretFrom Auth0 app

Keycloak

FieldValue
Display NameKeycloak
Discovery URLhttps://keycloak.example.com/realms/your-realm/.well-known/openid-configuration
Client IDFrom Keycloak client
Client SecretFrom Keycloak client

Manual configuration (no discovery)

If your provider doesn't support OIDC discovery, provide the URLs directly:

FieldValue
Authorization URLhttps://provider.example.com/oauth/authorize
Token URLhttps://provider.example.com/oauth/token
Scopesopenid email profile

How it works

  1. User clicks the custom sign-in button on the login page
  2. Quackback redirects to your identity provider's authorization endpoint
  3. User authenticates with their existing credentials
  4. Provider redirects back to Quackback with an authorization code
  5. Quackback exchanges the code for user information (email, name)
  6. A session is created

Quackback uses the email claim from the OIDC token to identify users. If a user with that email already exists, the account is linked automatically.

Troubleshooting

"Redirect URI mismatch"

The redirect URI in your identity provider must match exactly:

https://YOUR_DOMAIN/api/auth/callback/custom-oidc

Check for protocol mismatches (http vs https), trailing slashes, and port numbers.

"Invalid client_id"

Verify the Client ID and Client Secret are copied correctly with no extra whitespace. Check that the OIDC application is active in your identity provider.

"Unable to get email"

Quackback requires an email address from the OIDC provider. Ensure:

  • The email scope is included
  • Your provider returns the email claim in the ID token or userinfo response

Discovery URL not working

If auto-discovery fails:

  1. Verify the URL returns valid JSON when accessed in a browser
  2. Try providing the Authorization URL and Token URL manually instead

Next steps