Portal Single Sign On

One you configure your deployment to enable the Deployed Portal, the next thing you may wish to accomplish is to use your Single-Sign-On to authenticate into the Deployed developer interface. Our portal interfaces currently support SAML authentication into our deployed portal interfaces for both the Developer portal seen @ https://portal.form.io as well as our Form Manager portal application.

We will cover setting up Single Sign On for the Deployed portal first.

Developer Portal SSO

To get started, you will first need to become familiar with how the SAML integration works with Form.io. You can read this documentation within the SAML Single Sign On section. Once you are familiar with this, you will want to setup SAML integration within the Portal Base project which is created when you deploy a new portal with the PRIMARY=true environment variable. You will see this project when you log into the deployed portal when you authenticate using the ADMIN_EMAIL and ADMIN_PASS that you used when creating the deployed portal. This will looke like the following.

When you click on this project, you will then want to configure the SAML configuration with the settings that you setup by walking through the SAML documentation above.

Now that you have setup your main portal project with the SAML configuration, you will now need to provide a single Environment variable to your deployment to enable the SSO portal. This environment is as follows.


For now, the only supported type is “saml” which should be the value of this environment variable. Once you have set this variable, then logout, you will then notice that the portal authenticates with the SAML SSO authentication.

The next item that can be configured for SSO is the Form Manager application.

Team Management

In addition to allowing users to create their own projects, you can also use the Portal SSO in conjunction with our Team support within the Developer Portal. This system creates a One-to-One connection between Roles within your SAML configuration, that will then map to Teams within the Form.io developer portal.

To start, you will first need to create Teams within your developer portal that will be related to Roles within your SAML configuration.

Make sure you check the checkbox called SSO Team which will tell the API platform that you wish to map this team with an SSO Role.

You do not need to worry about assigning anyone to that Team since that will be handled automatically through the SSO process when they authenticate by associating SAML roles to that Team.

Next, you will need to assign that Team to your projects you wish to allow SSO people to have access to within the Form.io developer portal interface. You can do this by clicking on the Project, and then clicking on the team, then select the role you wish that team to have wthin that Project.

Once you have done this, anyone with a SAML Role name that matches the name of the Team will be automatically assigned to that team and be granted access to a project.

Form Manager SSO

To enable the Form Manager with SAML SSO authentication, you will need to first navigate to your project, and just like you did for the Portal Base project above, configure this project with some SAML configuration. Important: Make sure that you configure a separate SSO application within your SAML provider to use the correct project urls instead of using the same SAML configuration provided in the previous step.

After you do that, you will now need to provide the SSO configuration within your projects Public Configuration section.

Form Manager Configurations

You can also use the Public Configuration to provide any of the following configurations, which will customize how the Form manager behaves.

Setting Description Example
title The title you would like to give to the Form Manager Application Form Manager
logo The url for the logo to present within the Form Manager https://manager.form.io/assets/logo.png
logoHeight The height of the logo within the Form Manager 40px
logout The Logout URL which will redirect when the user clicks logout. https://yourapplication.com/logout
js The URL to a custom JavaScript file that allows for custom components and logic. https://yoursite.com/js/custom.js
css The URL to a custom CSS file for custom styling. This can also be used to change the Bootswatch theme as follows. assets/lib/bootswatch/dist/cosmo/bootstrap.min.css
navbar The class to apply to the Navbar to allow for inverted, etc. navbar-dark bg-primary
sso The type of Single Sign On to perform. Currently only supports “saml”. saml
ssoProject The project that will be used as the Authentication project for the Form Manager application. https://yourdomain.com/formio
environments A JSON string list of environments that you would like for the Form Manager to control [{“name”:”Staging”,”url”:”http://localhost:3000/humanresources”},{“name”:”Public”,”url”:”http://localhost:3000/stage-humanresources”},{“name”:”Internal”,”url”:”http://localhost:3000/test-humanresources”}]
userIndicator An HTML indicator that you would like to have for the user indicator within the navbar of the application {{ user.data.email }}

Once this is done, you can now go to the following URL to see the Form Manager application.


Or, if you are using subdirectory project path method, it may look like the following.


Once you do this, you will see that it will trigger the SAML SSO for the form manager application.

Multi-Tenant Configuration

Using the Form Manager in combination with the Portal SSO can be utilized within a Multi-tenant setup where each tenant has access to their Projects within the deployed portal, and then within each project they have access to the Form Manager application within each project. To enable this configuration, you must do the following.

  • First, configure your Portal to allow for PORTAL_SSO as described in the section above.
  • Next create a new project for the Tenant, and then create a new Team, enable SSO Team configuration, and then assign that team to the project as Project Admin.
  • Now, within each project, you can setup multiple “stages” that you wish the form builders to be able to “save to”. Make sure you remember the API domains for each of the stages within each tenant project.
  • Next, you will navigate to the Public Project Configurations section and provide the following configs.
Setting Value
sso saml
ssoProject https://yourdomain.com/formio
environments [{“name”:”Staging”,”url”:”https://yourdomain.com/stage-yourproject”},{“name”:”Public”,”url”:”https://yourdomain.com/yourproject”},{“name”:”Internal”,”url”:”https://yourdomain.com/test-yourproject”}]

This will make it so that every tenant user will still authenticate with the main SAML configuration to then gain access to their main project as well as each stage when managing the forms using the Form Manager application.