SAML Authentication

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.

Create Roles

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.

Add Users

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.

Create 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.

https://YOURPROJECT.form.io/saml/acs

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 saml/acs

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.

https:\/\/YOURPROJECT.form.io\/saml\/acs

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.

https://app.yoursite.com

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.

Project Configuration

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.

<script src="https://unpkg.com/formiojs@latest/dist/formio.full.min.js"></script>

Once this library has been added, we can perform a SSO with the following code in our application.

Formio.setProjectUrl('https://yourproject.form.io');
Formio.ssoInit('saml');

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.

Formio.ssoInit('saml');

Next, within your application, you will want to place the following code so that it will complete the authentication process after the redirect.

<script type="text/javascript">
if (Formio.pageQuery().saml) {
    const sso = Formio.ssoInit('saml');
    if (sso) {
        sso.then((user) => {
          console.log(user);
        });
    }
}
</script>

What you get is the following.

You can try this out using the following login credentials.

  • user: joe@example.com
  • pass: password123


Result