MergeWhy
Back to Docs

OIDC Authentication Setup

Configure single sign-on with Okta, Azure AD, Keycloak, Auth0, or any OIDC-compliant identity provider.

Overview

Self-hosted MergeWhy uses OpenID Connect for authentication. Any OIDC-compliant identity provider works, including Okta, Azure AD (Entra ID), Keycloak, Auth0, and Google Workspace.

Provider Setup

Okta

  1. In the Okta Admin Console, go to Applications → Create App Integration
  2. Select OIDC - OpenID Connect and Web Application
  3. Set the sign-in redirect URI to https://your-mergewhy-url/api/auth/callback/oidc
  4. Copy the Client ID and Client Secret to your environment
  5. Set OIDC_ISSUER_URL to https://your-domain.okta.com

Azure AD (Entra ID)

  1. In Azure Portal, go to Azure Active Directory → App Registrations → New
  2. Set redirect URI to https://your-mergewhy-url/api/auth/callback/oidc (Web platform)
  3. Create a client secret under Certificates & secrets
  4. Set OIDC_ISSUER_URL to https://login.microsoftonline.com/{tenant-id}/v2.0

Keycloak

  1. Create a new realm or use an existing one
  2. Create a new client with Client authentication: On
  3. Set valid redirect URI to https://your-mergewhy-url/api/auth/callback/oidc
  4. Set OIDC_ISSUER_URL to https://keycloak.example.com/realms/{realm-name}

Role Mapping

MergeWhy maps your IdP roles to its internal role hierarchy: OWNER, ADMIN, MEMBER, VIEWER. Configure the mapping with environment variables:

.env
# Comma-separated IdP roles that map to OWNER
OIDC_OWNER_ROLES="admin,super-admin,org-owner"

# Comma-separated IdP roles that map to ADMIN
OIDC_ADMIN_ROLES="manager,team-lead"

# All other authenticated users default to MEMBER

Single-Tenant Mode

For organizations with a single tenant, set OIDC_DEFAULT_ORG to automatically assign all users to one organization. This skips the organization creation step during onboarding.

.env
OIDC_DEFAULT_ORG=my-company
ConfigurationAPI Reference