Out Of The Box Authentication Support

Form.io is forms as infrastructure. That means authentication works the same way as a number of other integrations: Form.io does not attempt to become your identity provider. Instead, it integrates with whatever authentication system you already have, converts those credentials into a standardized JWT token, and uses that token for all subsequent API interactions.

This design matters because enterprise applications rarely exist in isolation. They connect to Active Directory, Okta, Azure AD, Auth0, or some homegrown LDAP server that’s been running since 2004. Form.io assumes this reality and builds authentication around it.

How Authentication Actually Works in Form.io

Every authentication method in Form.io, regardless of provider, follows the same fundamental pattern. The external identity provider verifies the user. Form.io receives confirmation of that verification. Form.io generates a JSON Web Token (JWT) containing the user’s identity, project context, and assigned roles. That JWT is then used for every subsequent API call.

This is the critical architectural decision that makes Form.io work in enterprise environments. You do not need to synchronize user databases. You do not need to duplicate profile data. The identity provider remains the source of truth for who people are. Form.io only cares about what they’re allowed to do once they’ve proven their identity.

The Authentication and Authorization documentation explains the complete flow, but the short version is: external provider confirms identity, Form.io issues a JWT, that JWT controls access to forms and submissions.

Supported Authentication Methods

Form.io supports several authentication protocols, each suited to different enterprise contexts.

SAML

SAML is the standard for enterprise single sign-on, particularly in organizations that use identity providers like Okta, OneLogin, or Azure AD. When a user attempts to access a Form.io application, they’re redirected to the SAML identity provider. After authenticating there, the provider sends a signed XML assertion back to Form.io. Form.io validates the signature, extracts the user’s identity and group memberships, maps those to Form.io roles and permissions [/features/roles-and-permissions], and issues a JWT.

The SAML integration guide walks through the configuration, including the Passport Generator that builds the required JSON configuration from your SAML provider’s metadata. The key settings you’ll need from your IdP are the SSO endpoint URL, the certificate for signature verification, and the attribute mappings for user identity and roles.

One common mistake: SAML configuration happens at the project level, not globally. If you’re building a multi-tenant application, each tenant project may need its own SAML configuration pointing to different identity providers. This is intentional. Form.io treats each project as an isolated environment with its own authentication context.

OAuth and OpenID Connect

OAuth 2.0 with OpenID Connect (OIDC) is the more modern alternative to SAML, particularly common with cloud-native identity providers like Auth0, Azure AD, Google Workspace, or Keycloak. The flow is similar in concept: redirect to the provider, authenticate there, receive tokens back.

The OAuth integration documentation covers the configuration in detail. You’ll configure the authorization endpoint, token endpoint, client ID, and client secret within your Form.io project settings. Form.io supports the standard OIDC discovery mechanism via the .well-known/openid-configuration endpoint, which simplifies setup considerably.

Role mapping with OIDC works through claims. Your identity provider includes group or role information in the ID token, and Form.io maps those claims to Form.io roles. The OAuth action on your login form specifies which claim contains the role information and how to map each value to a Form.io role.

LDAP

LDAP integration allows Form.io to authenticate users directly against an LDAP directory like Active Directory or OpenLDAP. Unlike SAML and OAuth, LDAP authentication happens server-side. The user enters credentials in a Form.io login form, Form.io binds to the LDAP server with those credentials, and if the bind succeeds, the user is authenticated.

The LDAP documentation explains the configuration. You’ll need the LDAP server URL, bind DN and password for the service account, search base, and search filter. The search filter is particularly important because it defines how usernames map to LDAP entries.

One constraint to understand: LDAP users are not stored in Form.io as resources. They exist only in LDAP. This means you cannot view or manage LDAP user accounts from the Form.io portal. User management happens entirely in LDAP. Form.io only uses LDAP for authentication, not as a user database.

Resource-Based Authentication

If you don’t have an external identity provider or need to manage users directly within Form.io, resource-based authentication stores user accounts as submissions to a User resource within your project. Users register by submitting a registration form, their credentials are stored (with passwords hashed), and they authenticate by submitting a login form.

This approach is documented in the Resource Based Authentication guide. It’s appropriate for simpler applications or cases where Form.io is the primary application rather than infrastructure embedded within a larger system. For enterprise deployments, external identity providers are almost always preferred.

Custom JWT Authentication

For deployed Form.io environments, you can bypass all external authentication systems and generate JWT tokens directly from your own backend. This is useful when you have an existing authentication layer that doesn’t fit the SAML/OAuth/LDAP patterns, or when you need to integrate Form.io into a system that already has authenticated sessions.

The process works like this: your backend generates a JWT with the correct payload structure (user ID, project ID, role IDs) and signs it with the same JWT secret configured in your Form.io deployment. Your frontend stores this token in localStorage under the formioToken key. Form.io accepts the token as valid authentication for all API requests.

This is documented in the Custom JWT Authentication section. The key constraint is that this only works with self-hosted Form.io deployments where you control the JWT secret. The hosted Form.io platform does not support custom JWT generation.

JWT as the Universal Authentication Token

Understanding that JWT is the internal currency of Form.io authentication clarifies several design decisions. Regardless of how a user authenticates, whether through SAML, OAuth, LDAP, or direct resource login, the result is always a JWT token. This token contains the user’s ID, the project ID, and an array of role IDs.

The token is stored in the browser’s localStorage as formioToken and sent with every API request. You can decode any Form.io JWT at jwt.io to see exactly what it contains. The payload structure is documented in the authentication tokens section.

Session management in Form.io uses the jti claim in the JWT. This is a session identifier that’s invalidated when the user logs out. Outstanding tokens with that session ID become invalid, which means logging out on one device effectively logs out all devices. This is a security feature, not a limitation.

Role Mapping: Where Authentication Meets Authorization

Authentication answers “who is this person?” Authorization answers “what can they do?” In Form.io, authorization is handled through roles and permissions. But the connection between identity provider groups and Form.io roles happens during authentication.

Every authentication method includes a role mapping step. For SAML, you map SAML role/group assertions to Form.io role IDs. For OAuth, you map OIDC claims to roles. For LDAP, you map LDAP group memberships to roles. The role mapping documentation shows the configuration for each method.

This mapping is essential for secure authentication because it controls what permissions the resulting JWT will carry. A misconfigured role mapping can give users more access than intended or lock them out entirely. Test your role mappings with users from different groups before deploying to production.

Two-Factor Authentication

Form.io supports two-factor authentication (2FA) for resource-based authentication. The Two-Factor Authentication documentation explains the setup, which involves adding 2FA forms to your project and configuring the User resource to store 2FA settings.

If you’re using external authentication (SAML, OAuth, LDAP), 2FA should be configured in your identity provider, not in Form.io. Form.io simply accepts the tokens from the identity provider. If the provider requires 2FA before issuing tokens, that’s transparent to Form.io.

What Secure Authentication Means in Practice

The security of Form.io authentication depends on the security of your identity provider and your configuration. Form.io provides the integration layer, not the identity infrastructure.

This means:

  • Use HTTPS for all endpoints (Form.io enforces this for the hosted platform)
  • Configure appropriate token expiration times for your security requirements
  • Audit your role mappings to ensure least-privilege access
  • Enable 2FA in your identity provider for sensitive applications
  • Use the CORS configuration to restrict which domains can authenticate

Form.io supports the Teams and Permissions system for fine-grained access control once users are authenticated. Authentication gets you in the door; permissions determine which rooms you can enter.

When Authentication Configuration Breaks

Common authentication failures and their causes:

SAML: “Invalid signature” errors usually mean the certificate in your Form.io configuration doesn’t match the one your IdP is using to sign assertions. IdPs rotate certificates; Form.io doesn’t automatically update.

OAuth: Redirect URI mismatch happens when the callback URL registered with your OAuth provider doesn’t match what Form.io is sending. Check the exact URL, including trailing slashes.

LDAP: “Bind failed” errors mean either the service account credentials are wrong or the LDAP server is unreachable from Form.io’s network location. For self-hosted deployments, check firewall rules.

JWT: “Token expired” or “Invalid token” usually means the token has exceeded its expiration time or the JWT secret doesn’t match between your token generator and Form.io’s configuration.

The help.form.io documentation includes troubleshooting sections for each authentication method. The API documentation is useful for debugging specific authentication API calls.

Why Form.io Does Not Replace Your Identity Provider

The decision to integrate with identity providers rather than replace them is fundamental to Form.io’s architecture as forms infrastructure. Enterprise organizations already have identity management. They have processes for onboarding and offboarding users, for managing group memberships, for enforcing password policies and multi-factor authentication.

Duplicating that infrastructure inside a form platform would create synchronization problems, security gaps, and operational overhead. Instead, Form.io integrates with your existing identity infrastructure and focuses on what it does well: schema-driven forms, API generation, and data capture.

If you need user management, that’s what identity providers are for. Form.io handles form management.

Related Documentation