Skip to main content
Self-hosted availability: OIDC SSO is available on self-hosted installations without an Enterprise license. Free self-hosted instances are limited to 2 users total across the whole instance, regardless of whether users are created by registration, invitations, or OIDC provisioning. An Enterprise license is required to add more users.
OpnForm supports OpenID Connect (OIDC) based Single Sign-On (SSO), allowing users to authenticate using any OIDC-compliant identity provider (IdP).
OpnForm displays the exact callback URL for each connection. Copy that URL into your IdP’s allowed redirect URIs; it must match exactly.

​
Features

  • Domain-Based Routing: Automatically routes users to the correct OIDC provider based on their email domain
  • Group-to-Role Mapping: Automatically assign workspace roles based on IdP groups
  • Custom Field Mappings: Support for custom claim field names from your IdP
  • Automatic User Provisioning: Creates users automatically on first login
  • Force Login Mode: Optionally require all users to authenticate via OIDC

​
Prerequisites

Before setting up OIDC SSO, ensure you have:
  1. An OIDC-compliant identity provider (IdP) configured
  2. OAuth client credentials (Client ID and Client Secret) from your IdP
  3. Admin access to the workspace where you want to configure SSO
  4. The issuer URL from your IdP (typically found in the .well-known/openid-configuration endpoint)

​
Self-hosted instance setup

Before creating an OIDC connection, make sure that OpnForm is configured with its real public URL. This is a deployment prerequisite: it determines the callback URL shown in the OIDC connection form. For the standard Docker deployment where OpnForm is available at https://forms.example.com, the person who manages the deployment must set:
Do not configure the callback URI at your IdP if the value displayed in OpnForm contains localhost. Ask the person who manages the deployment to set the public instance URL, then recreate the containers before continuing.
If deployment and OIDC configuration are handled by different people, share this checklist with the person who manages the instance. See Public instance URL for the full reference and Docker Deployment for the Docker steps.
On self-hosted Community instances, OIDC can provision users until the instance reaches the free 2-user limit. Existing linked users can continue signing in with OIDC. Activate a self-hosted Enterprise license to add more than 2 users.

​
Setup Steps

1

Get OIDC Provider Information

From your identity provider, collect the following information:
  • Issuer URL: The base URL of your IdP (e.g., https://idp.company.com)
  • Client ID: OAuth client identifier
  • Client Secret: OAuth client secret
  • Email Domain: The domain you want to use for routing (e.g., company.com)
The issuer URL is typically found in your IdP’s OpenID configuration endpoint: {issuer}/.well-known/openid-configuration
2

Create OIDC Connection

  1. Navigate to your workspace settings
  2. Go to the SSO section
  3. Click Add Connection
  4. Fill in the connection details:
    • Name: Display name for this connection (e.g., “Company SSO”)
    • Slug: Unique identifier used in URLs (e.g., company-sso)
    • Email Domain: Domain for routing users (e.g., company.com)
    • Issuer URL: Your IdP’s issuer URL
    • Client ID: OAuth client ID from your IdP
    • Client Secret: OAuth client secret from your IdP
The redirect URI will be displayed automatically. Copy this URL and add it to your IdP’s allowed redirect URIs.
3

Configure Redirect URI in IdP

  1. Copy the redirect URI shown in the connection form
  2. In your IdP’s application settings, add this redirect URI to the allowed redirect URIs list
  3. Save the configuration in your IdP
Important: The redirect URI must match exactly. Ensure you copy the full URL including the protocol (https://) and path.
4

Configure Group-to-Role Mapping (Optional)

If your IdP provides group information in the ID token, you can map groups to workspace roles:
  1. In the connection settings, expand Role Mappings
  2. Click Add Mapping
  3. Enter the exact value from the token’s groups (or group) claim
  4. Select the corresponding workspace role (owner, admin, editor, or member)
  5. Repeat for each group you want to map
If a user belongs to multiple groups, the highest privilege role will be assigned. Role priority: owner > admin > editor > member.
Matching is exact and case-sensitive. Copy the raw value emitted in the ID token, not a display name from your IdP’s administration interface unless that display name is itself the claim value. Many IdPs emit an immutable group identifier rather than a human-readable name.
OpnForm reads only the groups or group claim. Configure your IdP to include one of these claims in the ID token. A custom claim name or a claim named roles is not used for role mapping.
5

Configure Field Mappings (Optional)

If your IdP uses non-standard claim names for email or name:
  1. In the connection settings, expand Field Mappings
  2. Enter the custom claim field name for email (if different from email)
  3. Enter the custom claim field name for name (if different from name)
  4. Save the connection
If field mappings are not configured, OpnForm will use standard OIDC claim names (email, name, etc.).
6

Enable and Test

  1. Ensure the connection is Enabled
  2. Save the connection
  3. Test the login flow:
    • Navigate to the login page
    • Enter an email address matching your configured domain
    • You should be redirected to your IdP for authentication
    • After successful authentication, you’ll be redirected back and logged in
If everything is configured correctly, users with emails from your domain will automatically be routed to your IdP for authentication.

​
Force Login Mode

Force Login Mode requires all users to authenticate via OIDC, disabling password-based login.

​
Configuration

Set the OIDC_FORCE_LOGIN environment variable to true in your backend .env file:
Important: Ensure at least one OIDC connection is configured and enabled before enabling force_login. If no connections exist, password login will remain available as a fallback.

​
Behavior

When enabled:
  • Password-based login attempts are blocked
  • Users attempting password login receive: “Password-based login is disabled. Please use OIDC authentication.”
  • The login form automatically redirects users to their OIDC provider based on email domain
  • If force_login is enabled but no OIDC connections exist, password login remains available as a fallback

​
Use Cases

  • Organizations requiring all users to authenticate via corporate SSO
  • Security policies mandating centralized identity management
  • Compliance requirements for authentication methods
For more details, see the Environment Variables documentation.

​
Updating a connection or changing the instance URL

You can edit an existing OIDC connection without deleting it.
  • Leave Client Secret empty to retain the current secret. Enter a value only when rotating or replacing it.
  • After changing the public URL of a self-hosted instance, update both the backend APP_URL and FRONT_URL, plus the frontend NUXT_PUBLIC_APP_URL and NUXT_PUBLIC_API_BASE. Recreate the relevant containers so the new environment values are loaded.
  • Edit the connection, click Use current app URL below its redirect URI, then save. Copy the refreshed URL into your IdP’s allowed redirect URIs.
See Custom Domain and Environment Variables for the instance URL and container steps.

​
Troubleshooting

Possible causes:
  • Email domain doesn’t match the configured domain
  • Connection is disabled
  • Domain not properly configured in connection settings
Solution: Verify the domain matches exactly (case-insensitive) and the connection is enabled.
Possible causes:
  • Redirect URI not added to IdP’s allowed list
  • Redirect URI copied incorrectly
  • HTTPS/HTTP mismatch
Solution: Copy the exact redirect URI from the connection settings and ensure it’s added to your IdP’s allowed redirect URIs. Verify HTTPS is used in production. If the instance URL changed, edit the connection, click Use current app URL, save it, and update the URL at the IdP.
Possible causes:
  • Groups not included in ID token
  • The mapping value does not exactly match the value in the token
  • The IdP sent a display name where OpnForm expects an identifier, or vice versa
  • The group claim is not configured in the ID token
  • The IdP omitted groups because the user belongs to too many groups
Solution: Inspect the decoded ID token returned for the user. Confirm it contains a groups or group claim, then copy one of its raw values exactly (including case) into the mapping. Configure the IdP to emit only the groups needed by this application if it omits a large group list.
OAuth authorization codes can only be exchanged once. This commonly happens when the callback URL is refreshed, revisited from history, or opened in a second tab.Solution: OpnForm starts one fresh sign-in automatically. If that cannot be completed, select Back to sign in and try again. Do not refresh or reuse the callback URL. Clearing the browser cache is not necessary.
Possible causes:
  • Email claim missing from ID token
  • Field mappings incorrect
  • Account with same email already exists (account linking blocked for security)
Solution: Verify email is present in ID token. Check field mappings if using custom claim names. For existing accounts, contact administrator to link accounts.
Possible causes:
  • OIDC_FORCE_LOGIN not set to true
  • No OIDC connections configured
  • Environment variable not loaded (restart required)
Solution: Verify environment variable is set correctly. Ensure at least one OIDC connection exists and is enabled. Restart application after changing environment variables.

​
Security Considerations

​
HTTPS Requirement

In production, all OIDC redirects require HTTPS. Ensure your application is served over HTTPS before configuring OIDC.

​
State Validation

OpnForm generates and validates an OIDC state value by default for login redirects. Callback requests without a valid, unexpired state are rejected to prevent login CSRF. State validation can be disabled explicitly on an OIDC connection by setting options.require_state to false, but this is not recommended unless required for a legacy identity provider.

​
Account Linking

For security, OpnForm prevents automatic linking of existing accounts. If a user with the same email already exists but isn’t linked to the OIDC connection, authentication will fail with a message to contact the administrator.

​
SSO-Only Accounts

Users created via OIDC SSO are created with:
  • Random 64-character password (prevents password-based login)
  • Email automatically verified
  • Provider metadata stored for tracking
These accounts can only authenticate via OIDC, not with passwords.

​
Best Practices

  • Test First: Always test with a small group before rolling out to all users
  • Monitor Logs: Check application logs for OIDC-related errors during initial setup
  • Backup Access: Ensure at least one admin account can still access the system if OIDC fails
  • Regular Updates: Keep your IdP configuration in sync with OpnForm connection settings
  • Documentation: Document your IdP configuration for future reference
With properly configured OIDC SSO, your users can seamlessly authenticate using their organization’s identity provider, improving security and user experience.