SAML
This section describes how to setup and configure Form.io with a SAML Authentication Provider for SSO functionality.
Introduction
Simplify and centralize your user authentication process by integrating SAML into your Form.io project. This integration allows you to configure your application login forms to support SAML SSO authentication for your application users.
SAML Provider
Choosing a SAML provider is the first step in the integration process. A SAML application will then be created and configured. Form.io offers integration with many providers, including the following:
Microsoft Entra ID (formerly Azure AD)
Once a provider has been chosen and a SAML application has been created, the next step is to integrate the SAML application with your Form.io project. The integration process involves transferring specific credentials and endpoints from the SAML application and then using that information to construct a Passport Configuration JSON object that will be saved within the Form.io Project connected to your application.
After applying the correct information from your SAML Provider to your Project's authorization settings, the Form.io authentication form embedded in your application will be configured to support SAML SSO authentication.
The following documentation is centralized around applying SAML to a client-based application connected to the Form.io project. The same concepts detailed in this documentation can also be applied to the Form.io Portal Base project that controls your Developer Portal to allow Form.io users to utilize SAML SSO to authenticate into the Form.io environment.
Video Tutorial
The following video demonstrates the creation of a SAML application, integration with Form.io, and configuring the authentication form that will instigate the SAML authentication process for the client application. OneLogin serves as the SAML Provider in this video, however, the same principles can be applied to other Providers.
OneLogin SAML
This section will cover the OneLogin Provider SAML application setup process and integration a Form.io Project.
Create and Configure Application
From your OneLogin Admin dashboard, create a new application by clicking the Applications tab and then the Add App button.
Select the SAML Custom Connector (Advanced) for SAML2.0 application
Give the Application a name and click the Save button with the default configurations
Click the Configuration tab to set up the application details
Add the RelayState (optional) - Live endpoint of the hosted application
https://app.yoursite.com
Add the Audience (EntityID) - Live endpoint of the hosted application
https://app.yoursite.com
Add the ACS (Consumer) URL Validator - Live Endpoint of the Form.io Project with form.io\/saml\/acs appended at the end of the URL. Backslash characters
\
should be added in front of all forward slash characters/
https:\/\/myproject.domain\/abc123\/saml\/acs
Add the ACS (Consumer) URL - Live Endpoint of the Form.io Project with form.io/saml/acs appended at the end of the URL.
https://myproject.domain.com/abc123/saml/acs
The configuration should look similar to the following:
Within the Configuration tab, set the SAML signature element to the Both setting
Configuring Parameters
Click the Parameters tab and ensure the following parameter is set (this should be set by default) NameID value field is configured with the Email value
Click the Paramter Tab, click the + button to add a new Parameter
Set the Parameter Name to groups (case sensitive)
Set the Value to User Roles
Check the Include in SAML assertion flag
Save the Parameter
The application should have two parameters set NameID Value (created by default with the application) group parameter created in the previous step
Save the application
Create Users
With the application configured, create a user base within the OneLogin Admin dashboard. Users can then be assigned to a Role linked with the SAML Application, enabling mapping between SAML Groups and Form.io roles.
Within the OneLogin Admin dashboard, hover over the User tab and click Users
Click the New User button
Input the Information for the User and then click Save User
Click the More Action tab and set a Password for the User
Generate multiple users to assign them to different roles that will be created in the next step
Create & Assign Groups
With our Users in place, the next step is to create Roles the SAML Users will be assigned to. This will allow us to establish mappings between SAML Roles (Groups) and Form.io roles.
Within the OneLogin Admin dashboard, hover over the User tab and click Roles
Click the New Role button
Give the Role a name and select your SAML Application the Role should be associated with
Click the Save role
Within the Roles tab, click the Role that was just created and click the Users Tab
Using the search bar, search and select all Users that should be added to the Role and click Check
Click the Add To Role button for each user
Click Save
Assign Role To Application
With the Roles established, the next step is to assign the Role to the SAML application
Hover over the Application tab and select Applications
Navigate to your SAML Application
Click the Access tab
Select all of the Roles you wish to assign to the Application Users assigned to the selected roles will be associated with the Application.
Click Save
Passport Configuration
Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration.
Download XML File
Navigate to the OneLogin application
Click the More Actions tab and click the SAML Metadata button to download the XML info
Store the XML information as it will be used to construct the Passport Config
Construct the Passport Config JSON object. Search the XML file for the property titles within the example below and input the data accordingly.
The identityProviderUrl and entryPoint endpoint can be found by searching the SingleSignOnService HTTP-REDIRECT endpoint
The logoutUrl endpoint can be found by searching SingleLogoutService
The cert can be found by searching the X509Certificate
The identifierFormat can be found by searching NameIDFormat
The audience must match the Audience (EntityID) endpoint within the Configuration tab within your OneLogin SAML application.
The issuer can be found by searching the entityID
Form.io Integration
With the Passport Config JSON object constructed, the Form.io project can now be configured.
Within the Form.io Project, click Settings > Authentication > SAML
Click the Passport Config tab and paste the Passport Config JSON from the previous step
Set the Email Path setting to nameID
Role Mapping
In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings.
Set the Role Path setting to
Within your OneLogin SAML Application, click the Access tab and take note of the Role Names assigned to the application.
Back to the Form.io SAML settings, scroll down to the Role Mapping setting
Map SAML Roles (case sensitive) to the desired Form.io Roles
After authentication, SAML users assigned to the Admin SAML role will obtain the Form.io Administrator role, while those assigned to the Member role will receive the Form.io Authenticated role. This can be seen by inspecting the user object within the dev console.
Authentication Configuration
The final step is to configure the Form.io Login form embedded in your application to support SAML. Alternatively, you can modify your application to support a similar process. Follow the link below for documentation.
SAML Authentication Configuration
Okta SAML
This section will cover the Okta SAML application setup process and integration Form.io.
Create and Configure Application
From your Okta Admin dashboard, create a new Okta application by clicking Applications and then Create App Integration.
Select SAML 2.0 from the modal window and click Next
Provide a Name for the application and click Next
Provide the Single Sign-On URL Copy your Form.io project endpoint and append /saml/acs at the end of the URL. Example: if your project API endpoint is https://myproject.domain.com/abc123 then your Assertion Consumer Service URL will be the following.
Provide the Audience URI Copy your Form.io project endpoint and append the path /saml/metadata at the end of the URL. Example: if your project API endpoint is https://myproject.domain.com/abc123 then your Audience URI will be the following.
Ensure the Name ID format is set to EmailAddress
Ensure the Application username is set to Email
The Attribute Statements and Group Attribute Statements section is where we can define the name for different User Information (attributes) and define the name for SAML Groups. This will ensure the required information is provided by the SAML user when they authenticate.
Set the following for the Attribute Statements
Name | Format | Value |
---|---|---|
Basic | user.email | |
firstName | Basic | user.firstName |
lastName | Basic | user.lastName |
Set the following for the Group Attribute Statements Ensure the Matchest regex filter is set to:
.*
Name | Format | Filter |
---|---|---|
groups | Unspecified | Matches regex: |
Click Next to complete the configuration of your Okta SAML 2.0 application.
Create Users
With the application configured, create a user base within the Okta Admin dashboard. These Users can then be assigned to a SAML group which will be associated with the SAML Application and allow for mapping between SAML Groups and Form.io roles.
Within your Okta Admin dashboard, click the Directory tab and select People
Within the People tab, click the Add Person button
Enter person details for the SAML User
Check the I will set password setting to set a password for the user
Click Save to add the User
Create & Assign Groups
With our Users in place, the next step is to create Groups the SAML Users will be assigned to. This will allow us to establish mappings between SAML Groups and Form.io roles.
Within your Okta Admin dashboard, click the Directory tab and select Groups
Click the Add Group button
Give your Group a Name and click Save
With a Group created, the next step is to assign users to the Group.
From the Group tab, select the Group to add Users to
Click the Assign people button
Click the + button next to a User to assign them to a Group
Assign Groups To SAML Application
To assign the Group, select the Group and click the Application tab
Within the modal window, click the Assign button next to your SAML application
Passport Configuration
Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration.
Within the Okta Admin Dashboard, click the Application tab and select your SAML app
Click the Sign On tab and copy the Metadata URL
Copy the Metadata URL and open the URL within your browser
Store the XML information as it will be used to construct the Passport Config
Construct the Passport Config JSON object. Search the XML file for the property names within the example below and input the data accordingly.
Example Template:
Form.io Integration
With the Passport Config JSON object constructed, the Form.io project can now be configured.
Authentication Settings
Within the Form.io Project, click Settings > Authentication > SAML
Click the Passport Config tab and paste the Passport Config JSON from the previous step
Set the Email Path setting to email
Role Mapping
In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings.
Set the Role Path setting to
Within your Okta SAML Application, click the Assignments tab and click Groups. Take note of the Groups Names assigned to the application.
Back to the Form.io SAML settings, scroll down to the Role Mapping setting
Map Okta SAML Groups (case sensitive) to the desired Form.io Roles
After authentication, SAML users assigned to the Admin SAML role will obtain the Form.io Administrator role, while those assigned to the Member role will receive the Form.io Authenticated role. This can be seen by inspecting the user object within the dev console.
Authentication Configuration
The final step is to configure the Form.io Login form embedded in your application to support SAML. Alternatively, you can modify your application to support a similar process. Follow the link below for documentation.
SAML Authentication Configuration
Microsoft Entra ID
This section will cover the Microsoft Entra ID SAML application setup process and integration with the Form.io Project.
The UI and theming may differ slightly between the free plan and paid plan
Create and Configure Application
After setting up your account, navigate to the Azure Portal, click the left navigation panel, and select Microsoft Entra ID.
Within the left-hand navigation bar, select Enterprise Applications
Click the +New Application button
Search and select Entra SAML Toolkit
Give the Application a name and click the Create button
Within the Entra ID application, click the Single sign-on button in the Manage toolbar
Select the SAML option
Scroll down to the Set up Form.io Entra SAML section and copy the Microsoft Entra Identifier endpoint
Scroll back up to the Basic SAML Configuration section and click the Edit button
Apply the following SAML Configuration for the Application
Add the Identifier (Entity ID) - Microsoft Entra Identifier copied in the previous step
https://sts.windows.net/abc-123-def-456
Add the Reply URL (Assertion Consumer Service URL) - Live Endpoint of the Form.io Project application with form.io/saml/acs appended at the end of the URL.
https://myproject.domain.com/abc123/saml/acs
Add the Sign On URL - Form.io domain endpoint
https://myproject.domain.com
Save the settings
Create Users
With the application configured, we can now add Users that will authenticate against Entra ID.
Click the Home button, User tab within the left-hand navigation bar, and then All Users
If you are using the free plan, click Home > Microsoft Entra ID > Users
Click the +New User button
Input the User information and click Review + create button
Uncheck the Auto-generate password setting to manually set the user password
Click the Create button after reviewing the User information
Create several other users to test Group and Role mapping detailed in the next section.
Create & Assign Groups
With our Users in place, the next step is to create Groups the Entra ID Users will be assigned to. This will allow us to establish mappings between SAML Groups (Roles) and Form.io roles.
Click the Groups tab and All Groups within the left-hand navigation bar.
If you are using the free plan, click Home > Microsoft Entra ID > Users
Click the +New Group button
Give the Group a Group Name and keep the remaining settings at their default values
Click the No Members Selected button to assign users
Search for the User created in the previous section
Select the User
Click the Select button
Click the Create button
Follow the same steps to create additional Roles
Enable Group Claims
With the Groups established, the next step is to enable the Group claim within the EntraID application.
Navigate back to your Entra ID SAML application
Click the Single sign-on tab
Edit the Attributes & Claims section
Click the +Add a group claim button
Select the Groups assigned to the application option
Click the Source attribute dropdown and select the Cloud-only group display names option
Save the claim
Within the Attributes & Claim page, copy the endpoint for the Group claim
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
Assigning Groups to Application
Navigate back to your Entra ID SAML application
Select the Users and groups tab then click the + Add user/group button
On the next screen, click the None Selected
Select the Groups created in the previous steps
Click the Select button at the bottom of the screen and then Assign on the following page
After assigning the Groups, you should see the Groups displayed within the User and Groups tab of the Entra ID application. Users assigned to the selected groups will be associated with the Entra ID Application.
Passport Configuration
Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration.
Download XML File
Navigate to your Entra ID SAML application
Click the Single sign-on tab
Within the SAML Certificates click the download button for the Federation Metadata XML
Store the XML information as it will be used to construct the Passport Config
Construct the Passport Config JSON object. Search the XML file for the parameters titles within the example below and input your specific data accordingly.
The identityProviderUrl, entryPoint, and logoutUrl endpoint can be found by searching the SingleSignOnService
The cert can be found by searching the X509Certificate
The issuer can be found by searching the entityID
The callbackUrl can be found within the Single sign-on tab of your Entra ID application
The signatureAlgorithm will be set to sha256
Form.io Integration
With the Passport Config JSON object constructed, the Form.io project can now be configured.
Within the Form.io Project, click Settings > Authentication > SAML
Click the Passport Config tab and paste the Passport Config JSON from the previous step
Set the Email Path to
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Role Mapping
In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings.
Set the Role Path setting to
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
Back to your EntraID SAML Application, click the Users and group tab and take note of the Group Names assigned to the application.
Back to the Form.io SAML settings, scroll down to the Role Mapping setting
Map SAML Roles (case sensitive) to the desired Form.io Roles
After authentication, SAML users assigned to the Admin SAML role will obtain the Form.io Administrator role, while those assigned to the Member role will receive the Form.io Authenticated role. This can be seen by inspecting the user object within the dev console.
Authentication Configuration
The final step is to configure the Form.io Login form embedded in your application to support SAML. Alternatively, you can modify your application to support a similar process. Follow the link below for documentation.
SAML Authentication Configuration
AuthO SAML
This section will cover the process of setting up a SAML application and configuring it for compatibility with the Form.io platform, utilizing the Auth0 Provider.
Create and Configure Application
From your Auth0 Admin dashboard, create a new Auth0 by clicking the Applications tab and clicking the +Create Application button
From the application Modal window, select Single Page Web Applications
Provide a name for the Application and click the Create button
Click the Addons tab
Toggle the SAML 2.0 button
Click the Settings tab
Within the Modal window, provide the Allowed CAllback URL. Also known as the by other SAML providers. For this value, copy your Form.io project endpoint and append /saml/acs at the end of the URL. Example: if your project API endpoint is https://yourdomain.com/myproject, then your Assertion Consumer Service URL will be the following.
https://yourdomain.com/myproject/saml/acs
Scroll down and click the Enable button
After enabling the application, click Save
Within the Modal window, Click the Usage tab and download the Identity Provider Metadata
The application should now be ready for SAML Authentication. The next step is to create Groups the SAML users will be assigned to. These Groups will then be mapped to Form.io roles for granular permissions.
Create Users
With the application configured, create a user base within the Auth0 Admin dashboard. These Users can then be assigned to a SAML group which will be associated with the SAML Application and allow for mapping between SAML Groups and Form.io roles.
Within the Auth0 admin dashboard, click the User Management tab and then Users
Click the +Create User button
Input user information and click Create
Create additional users to assign to the different Roles that will be established in the next step.
Create & Assign Groups
With our Users in place, the next step is to create Groups the SAML Users will be assigned to. Auth0 groups are created and managed through extensions. This group extension will allow us to establish mappings between SAML groups and Form.io roles for granular permissions.
Within the left-hand navigation bar, click Extensions
Select Auth0 Authorization
Click Install within the Extension modal
Click the GO TO CONFIGURATION button
Click the Groups radio button
Click the Publish Rule button
Within the Extension, click the Groups tab then + Create Your First Group button
Give the Group a Name and Description
Click the +Add Member button
Search and select the user(s) to assign to the Group and Save
Passport Configuration
Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration.
Within the Auth0 Admin Dashboard, click the Application tab and select your SAML app
Click the Add On tab and click the SAML2 Web App
Within the Usage tab, click the Download to extract the XML file
Store the XML information as it will be used to construct the Passport Config
Construct the Passport Config JSON object. Search the XML file for the property titles within the example below and input the data accordingly.
The identityProviderUrl and entryPoint endpoint can be found by searching the SingleSignOnService HTTP-REDIRECT endpoint
The logoutUrl endpoint can be found by searching SingleLogoutService
The cert can be found by searching the X509Certificate
The identifierFormat can be found by searching NameIDFormat
The callbackURL must match
The audience must match the Application Callback URL endpoint within the Setting tab within your Auth0 SAML application.
The issuer can be found by searching the entityID
Form.io Configuration
With the Passport Config JSON object constructed, the Form.io project can now be configured.
Authentication Settings
Within the Form.io Project, click Settings > Authentication > SAML
Click the Passport Config tab and paste the Passport Config JSON from the previous step
Set the Email Path setting to the following endpoint
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Role Mapping
In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings.
Set the Role Path setting to
http://schemas.xmlsoap.org/claims/Group
Within your Auth0 SAML application, click the Extensions tab, and the Auth0 Authorization extension.
Click the Groups tab and take note of the Groups Names assigned to the extension.
Back to the Form.io SAML settings, scroll down to the Role Mapping setting
Map SAML Roles Names (case sensitive) to the desired Form.io Roles
After authentication, SAML users assigned to the Admin SAML role will obtain the Form.io Administrator role, while those assigned to the Member role will receive the Form.io Authenticated role. This can be seen by inspecting the user object within the dev console.
Authentication Configuration
The final step is to configure the Form.io Login form embedded in your application to support SAML. Alternatively, you can modify your application to support a similar process. Follow the link below for documentation.
SAML Authentication Configuration
Authentication Configuration
SAML Authentication can be set up either by utilizing a Form.io Login form or by modifying the code within your application
Login Form Configuration
Follow the steps below to achieve SAML SSO authentication using a Form.io Login form.
Edit the authentication Form embedded within your application
Drag and drop a Button component
Modify the Label to reflect SAML authentication
Click the Action dropdown and select Custom
Copy the following code and paste it into the Button Custom Logic code block
Add a Hidden component
Click the Data tab and open the Custom Default Value tab
Add the following JavaScript within the code block
Save the Settings and Form
Application Configuration
To achieve authentication within your application, the following code will instigate the SSO process.
The Formio.ssoInit
method is used to both instigate the SSO process as well as handle the callback once the authentication occurs. Because of this, it may be beneficial to place this code within a button on so that the login will occur once you click on a "Login" button, and then trigger the Formio.ssoInit
method once the page returns with the ?saml=
query parameter (which indicates that the SSO process has completed).
SAML Passport Config
The "Passport Config" setting simplifies the process of configuring SAML authentication settings for your Form.io project, allowing you to specify how your application interacts with the SAML identity provider using JSON configuration. Passport then utilizes this configuration to manage the authentication flow and grant access to authenticated users
Form.io utilizes the Passport Config JSON object from the Node.js Authentication library, which is documented here.
As an example, many Microsoft Azure Active Directory deployments do not cryptographically sign their SAML assertions (despite signing the top-level SAML response). Form.io, however, expects both the SAML response and the SAML assertions to be signed by default. In this case, your Passport Config JSON object would set the wantAssertionsSigned
parameter to false, and might look something like this:
This JSON configuration will ensure that Form.io is aware that it should not expect the assertions to be cryptographically signed.
For those customers that use private key encryption for SAML responses and/or a private key for decryption, we provide two environment variables which allows you to provide the absolute paths to those key files in your container's file system rather than as plain text string values in the Passport Config JSON object. Those variables are SAML_PASSPORT_PRIVATE_KEY_PATH and SAML_PASSPORT_DECRYPTION_PVK_PATH. Alternatively, you can specify the private key and/or the decryption private key as strings in the JSON object.
Test Connection to SAML - COMING SOON
After the XML Metadata or Passport Config is filled in, you can use a test connection to SAML. Сlick on the "Save SAML Authorization Settings and Connect to SAML" button, and all unsaved authorization SAML settings will be saved and a new window will open with a test connection to the SAML provider.
After successful authorization, the authorized user's profile object will be available. This will make it easier to fill in the Profile Fields or use Custom Parser.
Custom Parser - COMING SOON
Custom Parser allows to generated payload for the JWT token based on SAML Profile object claiming certain roles configured within the project. At the same time, the project id cannot be changed.
Server will first checks if there is data on the "Custom Parser" tab before generating token. If you use a Custom Parser, then the filled Profile Fields are not taken into account when generating token
“User” should be set into the following format:
ROLE_ID_1, ROLE_ID_2 - These are the IDs of the project roles you would like this user to have when authenticating.
Profile – the data from the SAML profile object.
After the SAML Toolkit is added to our tenant, we can now set up the SSO configurations. Find the Manage section and select single sign-on.
Last updated