OpenID Connect

HeyForm can use a standards-compliant OpenID Connect (OIDC) provider for dashboard login. This is a single, instance-wide provider intended for self-hosted deployments such as Authelia, Authentik, and Keycloak.

Register HeyForm with the provider

Create a confidential web application in the identity provider and register this exact redirect URI:

https://forms.example.com/connect/oidc/callback

Replace https://forms.example.com with the public APP_HOMEPAGE_URL of the HeyForm instance. The URL must match exactly, including the scheme, host, and port.

Enable the authorization code flow and allow the openid, profile, and email scopes. The provider must publish OIDC discovery metadata and return a stable sub claim. Account linking and provisioning require the provider to return an email address that it marks as verified with email_verified: true.

Configure HeyForm

Set these variables on the HeyForm server or container:

APP_HOMEPAGE_URL=https://forms.example.com

OIDC_CLIENT_ID=heyform
OIDC_CLIENT_SECRET=replace-with-a-secret
OIDC_ISSUER=https://sso.example.com
OIDC_DISPLAY_NAME=Company SSO
OIDC_CLIENT_AUTH_METHOD=client_secret_basic
OIDC_ALLOW_PROVISIONING=false

OIDC_ISSUER is the issuer identifier advertised by the provider, not an arbitrary authorization or token endpoint. HeyForm uses it to discover the provider metadata. Do not include OIDC_CLIENT_SECRET in frontend build variables or expose it through a reverse proxy.

The OIDC button is enabled only when OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_ISSUER are all set. OIDC_DISPLAY_NAME controls its label and defaults to SSO.

OIDC_CLIENT_AUTH_METHOD controls how the confidential client authenticates at the token endpoint. It accepts client_secret_basic (the default used by common Authelia and Keycloak client configurations) or client_secret_post. The value must match the client registration in the provider.

By default, APP_DISABLE_REGISTRATION=true prevents a new OIDC identity from creating a HeyForm account. Set OIDC_ALLOW_PROVISIONING=true only when the configured provider is trusted to control account creation. Existing linked OIDC users can continue to sign in.

Restart HeyForm after changing these values.

When running the webapp directly with Vite, also set VITE_DISABLE_LOGIN_WITH_OIDC=false and optionally VITE_OIDC_DISPLAY_NAME. These frontend-only variables control the development button; the server-side OIDC variables are still required to complete authentication. Production deployments receive the button state and label from the server at runtime.

Reverse proxy and network requirements

• Serve the public HeyForm URL over HTTPS. The OAuth state cookie is secure and the callback must return to the same browser that started the login.
• Ensure the HeyForm container can resolve and reach the issuer discovery, JWKS, token, and UserInfo endpoints.
• Forward /connect/oidc and /connect/oidc/callback to the HeyForm server without rewriting their paths or query parameters.
• Keep APP_HOMEPAGE_URL aligned with the external URL seen by users. An internal container hostname will produce an invalid redirect URI.

Provider examples

Use the provider's issuer identifier and register the callback URL above. Typical issuer formats include:

# Authelia
OIDC_ISSUER=https://auth.example.com

# Authentik application provider
OIDC_ISSUER=https://auth.example.com/application/o/heyform/

# Keycloak realm
OIDC_ISSUER=https://auth.example.com/realms/company

Always copy the issuer value from the provider's discovery metadata or administration UI. Paths and trailing slashes are provider-specific.

Rollout and recovery

Keep password login available while validating the first OIDC administrator account. OIDC configuration enables an additional login method; it does not disable password login, password reset, or local registration by itself.

Before changing OIDC_ISSUER, confirm how existing linked accounts will be migrated. An OIDC subject is scoped to its issuer, so an identity from a different issuer must not be assumed to be the same user solely because it has the same sub value.

If login fails, restore the previous OIDC variables or remove all three required OIDC variables and restart HeyForm. Removing the configuration hides the OIDC button without deleting local users or their existing data.