Form Manager Group Access

Enterprise organizations do not manually provision portal access for individual users. They manage identity through centralized systems: Active Directory groups, SAML providers like Okta or Azure AD, OIDC configurations, or LDAP directories. Form.io’s group access model bridges these external authentication realms to the Teams and Permissions system, enabling automatic team membership based on identity provider group assignments.

The practical result: when a user authenticates via your SSO provider with a specific group or role, they automatically receive the corresponding Form.io team membership and project access. No invitation emails, no acceptance clicks, no manual provisioning. Add someone to an Active Directory group, and they can immediately access the Form.io projects assigned to that team.

Authentication Realms Explained

An authentication realm is a domain of trust where user identities are validated. Form.io does not require you to recreate your user directory inside its platform. Instead, it accepts authentication assertions from external providers and maps those assertions to internal teams and roles.

Form.io supports three primary authentication methods that can serve as realms:

SAML (Security Assertion Markup Language) works with enterprise identity providers like Okta, OneLogin, Microsoft Entra ID (formerly Azure AD), and Auth0. The identity provider authenticates users and sends signed assertions containing user attributes and group memberships. Form.io consumes these assertions and maps SAML groups to Form.io teams.

OIDC (OpenID Connect) provides similar functionality through OAuth 2.0 flows. OIDC providers issue tokens containing claims about user identity, including group membership. Form.io processes these claims and maps them to team assignments, just as with SAML.

LDAP (Lightweight Directory Access Protocol) connects directly to directory services like Active Directory or OpenLDAP. Users authenticate against the directory, and Form.io extracts group membership from LDAP attributes to determine team assignments.

Each method produces the same outcome: external identity verification translated into Form.io team membership and project access. The choice depends on your existing identity infrastructure, not on Form.io requirements.

SSO Teams: Automatic Membership Through Identity Providers

The key mechanism enabling group-based access is the SSO Team. Unlike standard Form.io teams where members must be explicitly invited and must accept invitations, SSO Teams automatically include any user whose identity provider assigns them to the matching group.

Creating an SSO Team requires two steps (assuming a self-hosted configuration):

First, enable SSO Teams in your environment by adding the appropriate environment variable to your deployment configuration. This tells the API server to recognize SSO Team configurations.

Second, create a team with the SSO Team checkbox enabled, naming the team to exactly match the group name from your identity provider. If your SAML provider has a group called “FormBuilders”, create an SSO Team named “FormBuilders”. The name match is case-sensitive.

When users authenticate through SSO with the “FormBuilders” group in their assertion, they automatically become members of the “FormBuilders” SSO Team. No invitation required. No acceptance step. The team membership is derived from the identity provider at authentication time.

SSO Team members do not appear in the team roster the same way manually-added members do. Membership is dynamic, determined at each authentication event. If an administrator removes a user from the identity provider group, that user loses Form.io team membership on their next login.

Mapping Identity Provider Groups to Form.io Roles

Group-based access operates at two levels: Teams control Developer Portal access (who can build and manage forms), while Roles control application-level authorization (who can submit forms and access data). Both can be mapped from identity provider groups.

For Developer Portal access, SSO Teams handle the mapping automatically. Create teams matching your identity provider groups, assign those teams to projects with appropriate permission levels (Access, Read, Write, or Admin), and users authenticating with those groups receive the corresponding portal access.

For application-level roles, configure role mapping in your project’s authentication settings. The SAML configuration includes a Role Mapping section where you specify which SAML groups map to which Form.io roles. Similarly, OIDC configuration allows mapping OIDC claims to Form.io roles.

A typical enterprise configuration maps multiple levels:

Your identity provider might have groups like “HR-Staff”, “HR-Managers”, and “HR-Admins”. In Form.io, you create three SSO Teams with matching names. The “HR-Staff” team receives Read access to the HR Forms project. The “HR-Managers” team receives Write access. The “HR-Admins” team receives Admin access.

Simultaneously, the role mapping configuration assigns the Form.io “Authenticated” role to HR-Staff group members, and the Form.io “Administrator” role to HR-Admins group members. This controls what authenticated users can do within the deployed application, separate from what they can do in the Developer Portal.

The Relationship Between Teams and Roles

Understanding the distinction prevents configuration confusion:

Teams exist at the portal level. They control which projects and stages users can see and modify in the Form.io Developer Portal. Team permissions (Access, Read, Write, Admin) determine whether a user can view forms, edit forms, or access project settings. Teams are about platform administration.

Roles exist at the project level. They control what authenticated users can do within deployed applications. Role permissions determine whether users can submit forms, view submissions, or perform CRUD operations on data. Roles are about application authorization.

A user might be on a team with Write permission to the Developer Portal (can edit form definitions) but have the Authenticated role in the application (can only submit and view their own submissions). These are independent permission systems serving different purposes.

SSO integration can populate both systems from identity provider groups, but the configurations are separate. SSO Teams handle portal access. Role mappings in authentication settings handle application authorization.

Configuring SAML Group Integration

SAML integration requires configuration on both the identity provider side and the Form.io side.

On the identity provider (Okta, OneLogin, Azure AD, etc.), configure your SAML application to include group membership in the assertion. This typically involves:

  1. Creating groups and assigning users to them
  2. Configuring “Group Attribute Statements” to include group names in SAML responses
  3. Specifying the attribute name (often “groups” or “memberOf”) that will contain group data

On the Form.io side, navigate to Project Settings > Authentication > SAML and configure:

  1. The standard SAML settings (Entry Point, Issuer, Certificate)
  2. The Role Path setting to specify where group information appears in the SAML profile (typically “groups”)
  3. The Role Mapping settings to connect SAML group names to Form.io roles

For Portal SSO, apply the SAML configuration to your Portal Base Project. This enables SSO for the Developer Portal itself, allowing SSO Teams to function for portal access.

Configuring OIDC Group Integration

OIDC configuration follows a similar pattern. On your OIDC provider:

  1. Configure the application to include group claims in tokens
  2. Add the “groups” scope to the application’s allowed scopes
  3. Configure which groups are included in tokens for this application

On Form.io, navigate to Project Settings > Authentication > OAuth and configure:

  1. Client ID, Client Secret, and provider endpoints
  2. The Group Parameter to specify the claim containing group data
  3. Role mappings connecting OIDC groups to Form.io roles

OIDC groups map to Form.io teams the same way SAML groups do. Create SSO Teams with names matching your OIDC group names, and users authenticating with those groups automatically receive team membership.

LDAP Integration Differences

LDAP authentication operates differently from SAML and OIDC. LDAP users are not imported into Form.io as Resources. They exist only externally in the LDAP directory. Form.io queries the directory at authentication time, validates credentials, and extracts group membership from LDAP attributes.

The LDAP Action configuration includes settings for mapping LDAP properties to roles. You specify the LDAP attribute containing group information (often “memberOf” for Active Directory), the attribute values that indicate group membership, and the Form.io roles to assign.

LDAP is typically used for application-level authentication rather than Developer Portal SSO. If you need LDAP users to access the Developer Portal, consider federating LDAP through a SAML or OIDC provider (like Azure AD, which can front an on-premises Active Directory) rather than direct LDAP integration.

Scaling to Thousands of Users

The SSO Team model scales because it eliminates per-user provisioning:

No invitation management: Traditional teams require inviting each member by email, then waiting for acceptance. SSO Teams derive membership from identity provider groups at authentication time.

No synchronization: You do not need to keep Form.io user lists synchronized with your identity provider. There is no user list. Membership is computed dynamically from SSO assertions.

Centralized administration: User provisioning and deprovisioning happen in your identity provider, not in Form.io. When IT removes a user from an Active Directory group, that user loses Form.io access without any Form.io-specific action.

Consistent policy enforcement: Identity provider policies (password requirements, MFA, session timeouts) apply to Form.io access because authentication flows through the provider.

For organizations with thousands of form builders, this model is not optional. Manually provisioning Form.io access for 1,000 users, then managing changes as people join teams, change roles, or leave the organization, would consume prohibitive administrative effort. SSO Teams reduce this to identity provider group management, which your IT team already does.

Stage-Level Access for Development Workflows

SSO Teams work with Stage-level permissions to support development workflows. A single project might have Development, Staging, and Production stages. Different identity provider groups can receive access to different stages:

The “Developers” SSO Team gets Write access to the Development stage but only Access permission at the project level, preventing modifications to Production.

The “DevOps” SSO Team gets Write access to the Production stage for deployment activities.

The “Auditors” SSO Team gets Read access to all stages for compliance review without modification capability.

Configure this by first assigning the SSO Team to the project with Access permission (visibility only), then assigning the same team to specific stages with Read or Write permission. Stage permissions work identically for SSO Teams and regular teams.

What Group Access Does Not Do

SSO Teams handle membership but not team creation. You must create teams in Form.io and configure their project assignments. The SSO integration populates membership; it does not auto-create teams based on identity provider groups.

SSO integration does not synchronize user profiles. Form.io does not store user names, email addresses, or other profile data from LDAP users. For SAML and OIDC users, minimal profile data may be captured from tokens, but Form.io is not a user directory replica.

Group-based access requires consistent group naming. If your identity provider group is “Form-Builders” and your Form.io SSO Team is “FormBuilders”, the mapping fails. Names must match exactly, including case.

SSO Teams do not support mixed membership. A team is either an SSO Team (membership from identity provider) or a regular team (membership by invitation). You cannot have some members join via SSO and others by invitation on the same team. Create separate teams if you need both models.

Related Resources