SAML
This section describes how to setup and configure Form.io with a SAML Authentication Provider for Single-Sign-On functionality.

Okta SAML

This section will discuss how to configure SAML integration using the Okta Identity Provider.

Create an Application

Once you have created a new account within Okta, the first thing you will need to do is to create a new application. You can do this by clicking on the Applications link in the top of the screen, and then click on the Add Application button.
Next you will type saml in the search bar, and then select SAML Service Provider.
On the next "overview" page, you will then just click the Add button.
On the next page, under General Settings, just click Next to accept all default options.
On the next Sign-On Options page, you will need to add the following field Attribute Statements and Group Attribute Statements.
Next, you will click on the View Setup Instructions button and then take not of the following configurations which will be used when we configure our Form.io project.
Next, for the Assertion Consumer Service URL, you will want to copy the endpoint of your project with a /saml/acs at the very end of it. So, for example, if your project API endpoint is https://yourproject.form.io, then your Assertion Consumer Service URL will be the following.
1
https://yourproject.form.io/saml/acs
Copied!
Next, for the Service Provider Entity Id, you will append the path /saml/metadata to the end of your project url, so that it would look as follows.
1
https://yourproject.form.io/saml/metadata
Copied!
Now click on the Done button to save the application.

Create a Group

On the next page, we will now need to add a test Group. We can do this by clicking on the Directory link in the top navigation, then clicking on the Groups sub-link. Next, we will click the Add Group button.
Adding a new Group
We will give this group a name of Managers and then click the Add Group button.

Assign Group

Next, we will navigate back to our Application that we just created, and then click on the Assignments tab, and then click on the Groups tab. We will then select the Assign dropdown and select Assign to Groups item. Click on Assign next to the Managers group to assign this group to the new application. When you are done, your groups section should look as follows.
Next, we will assign our default user to this application, by clicking on the People tab and then selecting our default Okta user to belong to this application. We do this by clicking on the Assign dropdown and select Assign to People item. It should look as follows.
We now need to assign the Managers group to the default user. We can do this by clicking on the People menu item from the Directory navigation item.
We can now add the group to the user by clicking on the user, then clicking on the Groups tab, typing the name of the Group we wish to add, and then click on the Add button.
Next we will click on the Sign On tab within our application configuration and download the Identity Provider Metadata shown in the link below.
We will need to save this metadata for configuration of the Form.io Project configurations. We are now ready to configure our project to login with SAML.

Form.io SAML Configuration

Within your Form.io project, click on the Project Settings | Authentication | SAML
The first thing we will do is copy over our Identity Provider Metadata that we downloaded in our provider configurations and paste this into the Identity Provider Metadata text area.
Next we will copy the Identity Provider Issuer which was copied in a previous step into the Issuer input.
For the Callback URL, simply input the same value that was used for the ACS endpoint provided in a previous step. For example.
1
https://yourproject.form.io/saml/acs
Copied!
Next, we need to tell the SAML configuration where to find the User ID. This is either provided by default for your SAML configuration and will differ per provider. This can also point to the "email" of the user if an ID is not provided as follows.
This can either be set to the userID or the "email" of the user who is logging in
Next, we will need to configure the Roles Path which contains the groups the user belongs to. Some providers allow this to be configured, while others it is hard coded. For this example, we are assigning the groups of the user to the "groups" property so our configuration will look as follows.
Finally, we will need to configure which roles we wish to map to our user. If you wish "anyone" within the SAML authentication to be granted the Form.io role, then you can use the text "Everyone" as the role name.

Application Authentication

To achieve authentication within your application, the following code will instigate the SSO process.
1
import { Formio } from 'formiojs';
2
Formio.ssoInit('saml');
Copied!
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 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).
1
<button class="btn btn-primary" role="button" onclick="Formio.ssoInit('saml')">Login</button>
2
<script type="text/javascript">
3
// Check to see if the saml query is provided.
4
if (Formio.pageQuery().saml) {
5
// Perform the login.
6
Formio.ssoInit('saml');
7
8
// Navigate to the homepage after they login.
9
window.location.replace('/');
10
}
11
</script>
Copied!

Login Form Configuration

You can also achieve this same login process through the configuration of a Login form within the Form.io form builder. To do this, you will first drag-and-drop a Button component on your form, and give it the following configurations.
Button Custom Logic
1
Formio.ssoInit('saml');
Copied!
Next, you will drag-and-drop a Hidden component above the login button with the following Custom Default Value configurations.
1
if (Formio.pageQuery().saml) {
2
Formio.ssoInit('saml');
3
window.location.replace('/');
4
}
Copied!
This will now allow you to login to your application using the login form.

OneLogin SAML

The following instructions show how you will setup the OneLogin SAML Provider.

Create Application

The first thing we will do is to register for an account with OneLogin by clicking on the Start a Free Trial button. After you have your account, we will get started by creating a new application.
Next select Add App
Next, type SAML in the search and click on the SAML Test Connector for SAML2.0
One the next page, just create the application with default configurations.
Next we will configure the ACS URL by clicking on Configuration and then providing the following url to the ACS url.
1
https://YOURPROJECT.form.io/saml/acs
Copied!
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.
1
https:\/\/YOURPROJECT.form.io\/saml\/acs
Copied!
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.
1
https://app.yoursite.com
Copied!
The configuration will look like the following.
Next click Save to save our application.

Add Roles

After you have an application, we will now navigate back to the Administrator page and click on Users then on 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 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
We now need to add our new role to our application, we can do this by navigating back to our application, select Access, and then click on our new role.
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.

Form.io Configuration

The configuration for Form.io is very similar to what is described above in the Form.io SAML Configuration section, so you will follow along with that configuration, except for the following.
    Issuer: You can leave this field empty in the Form.io configuration page.
    ID Path: Should be "nameID"
Last modified 5mo ago