SAML is a standard XML-based framework that enables different organizations (with different security domains) to securely exchange authentication and authorization information. Form.io supports the SAML 2.0 Single Sign on standard which allows you to use your organizations authentication to automatically authenticate into a Form.io application.
There are many software services that offer SAML authentication, which makes it very easy to test out this feature capability. Here are just a few that provide SAML integration.
For this tutorial, we will use OneLogin.
Create a OneLogin Account
The first thing we will do is to register for an account with OneLogin by clicking on the Start a Free Trial button
Once you create your account, the first thing we will want to do is to create some User Roles. We can do this by first going to the Administration section of your account by clicking on the following.
We can add new roles, by clicking on Users link then Roles
We will then click New Role button.
Next we will type the name of our role (such as “Employee”) and then press Save Button.
Next, we will add a user that has this role.
To add new users, we will click on the Users menu item, then select All Users
Next click New User
Next add some user information, then click Save User
We will now assign this user a Role by clicking on Applications then click on the Employee role.
Make sure to press Save User again to save the settings.
Next we will need to set the password for this user by clicking on More Actions and select Change Password
Change the password of this user then click Save
We will now create a new application.
We can create a new application by clicking on Apps and then Add Apps
On the next page, type saml test in the find bar and press Enter to search. Once the results show up, select the one that says SAML Test Connector (ldP)
On the next page, press Save.
Next we will configure the ACS URL by clicking on Configuration and then providing the following url to the ACS url.
where you will replace YOURPROJECT with the subdomain of your project on Form.io. If you have deployed the API server, then this will simply be the URL to your project followed with
Next for the ACS URL Validator we will just copy the string above, and just put a backslash in front of all the
/ as follows.
You will now need to configure the RelayState for your project to point to the URL of your hosted application. This may look like the following.
The configuration will look like the following.
We will now add all Employee roles to have access to this application, we do this by clicking on Access and then click on the Employee role under the Role-Based Policy section.
Make sure you Save the application after making this change.
We can now verify that our user is part of this application by going to the Users section where we will see our user.
Next, we will need to ensure that our roles field is included within the Parameters of our application. We can do this by clicking on the Parameters link and then clicking on Add Parameter
For the name of the field, we will just call it roles
Once you click Save, we will now want to ensure that the value of this field points to the user User Roles property. You will also want to make sure you click the Include in SAML assertion checkbox. Now press Save
Next, we will make sure the id field is provided.
For OneLogin, we can just use the OneLogin ID as the value for this field.
Next we will want to make sure we save our application by clicking on Save button.
After this is done, we can now download our SAML Metadata to be used when we configure this within our Form.io project. To do this, we will click on the More Actions button and then select SAML Metadata.
We will need to save this file for our project configuration, which is what we will setup next.
We are now done with our work within OneLogin. It is now important to Logout of our account since it will cause problems when performing the SSO later in this tutorial.
After you are done logging out, we will now move over to Form.io to configure our project.
Within your Form.io project, we will now click on Settings then click on Authentication and then SAML
For the Identity Provider XML we will copy the contents of the SAML Metadata that we downloaded previously and paste that within this textarea.
For the field ID Path we can just leave them blank since the OneLogin paths match the defaults.
The next section SAML Role, we will add our Employee role mapped to our Authenticated role within Form.io. This could be any role that is within the project including any custom roles that you create.
Next press Save Settings
We will now provide the code to our application that will perform a Single Sign On.
Single Sign On
To perform Single Sign On within your application, we will use the Formio.js library to perform the SSO login with SAML for this project.
To get started, we will first need to make sure that we are including the Formio.js library within your application, but it can manually be added with the following script.
Once this library has been added, we can perform a SSO with the following code in our application.
You will typically want to place this code as the first thing within the application and it will perform the SSO automatically.
Login Button SSO
If you wish to have authentication triggered by a login Button, this can be created by adding a simple Button component to your form, configure it with Custom action, and then within the Button Custom Logic place the following code.
Next, within your application, you will want to place the following code so that it will complete the authentication process after the redirect.
What you get is the following.
You can try this out using the following login credentials.
- user: firstname.lastname@example.org
- pass: password123