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 a Group

Once you have created a new account with Okta, we will first create a Group that will be used to assign users as well as establish a mapping between these groups and Roles within Form.io. To do this, we will first click on Directory, and then click on Groups. Then click on the Add Group button.
We will now give our Group a name, and then click Save.
After we have a group created, the next thing we will do is click on the Assign People button, which will allow you to add the users you wish to belong to this group into the group as follows.
Once you are done adding members, click Save button to save the group.
Now that we have a group, we can now create an Application to be used within our Form.io project.

Create an Application

You can create a new application by clicking on the Applications link in the top of the screen, and then click on the Create App Integration button.
On the next screen, you will select SAML 2.0 then click Next.
On the next page, you will just provide a name for your project in the App Name section, then click Next.
On the next page, you will need to provide your Single Sign On URL, or also known as the ACS endpoint. For this value, 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://yourdomain.com/myproject, then your Assertion Consumer Service URL will be the following.
1
https://yourdomain.com/myproject/saml/acs
Copied!
Next, for the Audience URI, you will append the path /saml/metadata to the end of your project url, so that it would look as follows.
1
https://yourdomain.com/myproject/saml/metadata
Copied!
For the Name ID format and the Application Username you will also want to ensure that you have Email selected. This page should look as follows.
Below this section, you will now see a place where you can configure Attribute Statements and Group Attribute Statements. For this section, we will want to configure the following so that our user attributes as well as groups will be provided in the SAML profile when we login.
Make sure that the groups property has the Filter set to Matches Regex with the value set to .*
Now just click Next to complete the configuration of your application integration.

Assign Group to Application

Now that you have the application created, we will need to ensure that our group that we created within a previous section has access to login to this application. We can do this by first clicking on the Assignments tag, and then click on the Assign dropdown, and then select Assign to Group. You will now click on the Assign link next to your group name, and then click the Done button.

Get Application Credentials

Once your application has been created and the group has been assigned, you will now need to get the configurations that will be needed for your project. There are two things that we will need.
  • Identity Provider Metadata
  • Identity Provider Issuer
The Identity Provider Metadata can be grabbed by clicking on the link that says Identity Provider Metadata.
This will take you to a page that shows XML. You will need to copy this XML and save it in a text editor for later Form.io configurations.
Next we will need to get the Issuer. this can be done by clicking on the View Setup Instructions button, which can be found in the SSO section of your project.
Once you click on this, you should see the following page.
You will need to save the value for #2 in this page, since that is the Identity Provider Issuer, which we will use later.
We will now save these configurations for when we configure our Form.io Project.

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 3d ago