SAML Authentication

SAML is a standard XML-based framework that enables different organizations (with different security domains) to securely exchange authentication and authorization information. supports the SAML 2.0 Single Sign on standard which allows you to use your organizations authentication to automatically authenticate into a 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.

where you will replace YOURPROJECT with the subdomain of your project on 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.


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 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 to configure our project.

Project Configuration

Within your 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 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=""></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, you will drag-and-drop a Hidden component onto the same form, and then add the following to the Custom Default Value code in the Data tab.

if (Formio.pageQuery().saml) {
    const sso = Formio.ssoInit('saml');
    if (sso) {
        sso.then((user) => {
          window.location.href = '/';

You will change the value of the href in the code above to be the place you would like to navigate the user after they login.

What you get is the following.

You can try this out using the following login credentials.

  • user:
  • pass: password123