SAML
This section describes how to setup and configure Form.io with a SAML Authentication Provider for Single-Sign-On functionality.
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.
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.
https://yourdomain.com/myproject/saml/acs
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.
https://yourdomain.com/myproject/saml/metadata
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.
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.
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.
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.
https://yourproject.form.io/saml/acs
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.
To achieve authentication within your application, the following code will instigate the SSO process.
import { Formio } from 'formiojs';
Formio.ssoInit('saml');
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).<button class="btn btn-primary" role="button" onclick="Formio.ssoInit('saml')">Login</button>
<script type="text/javascript">
// Check to see if the saml query is provided.
if (Formio.pageQuery().saml) {
// Perform the login.
Formio.ssoInit('saml');
// Navigate to the homepage after they login.
window.location.replace('/');
}
</script>
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
Formio.ssoInit('saml');
Next, you will drag-and-drop a Hidden component above the login button with the following Custom Default Value configurations.
if (Formio.pageQuery().saml) {
Formio.ssoInit('saml');
window.location.replace('/');
}
This will now allow you to login to your application using the login form.
To configure the integration of Azure AD SAML into Form.io, you need an Azure AD subscription. If you don't have a subscription, you can get a free account.
Sign in to the Azure portal, on the left navigation pane, select the Azure Active Directory service.
Azure AD Portal
Navigate to Enterprise Applications and then select All Applications. Add a new application.
Enterprise Applications
Add New Application
In the Add from the gallery section, type Azure AD SAML Toolkit in the search box, select Azure AD SAML Toolkit, and then add the app.
Search SAML
After the SAML Toolkit is added to our tenant, we can now set up the SSO configurations. Find the Manage section and select single sign-on.
SSO
Then, in the Basic SAML Configuration click on the Edit Icon.
Edit
Here, we need to add our Form.io SAML ACS endpoint
https://yourdomain.com/myproject/saml/acs
and our Sign-on URL
https://yourdomain.com/
Edit Basic Information
Now, we can add users or groups to grant access to the Azure AD SAML Application
users
add users
select user or group
Now, we have everything we need to set up our Form.io Project. Let's gather all the information we need starting from Downloading Signing Certificate Metadata XML.
Download XML metadata
Then, get the SAML Issuer ( Application ID)
Application ID
And then, the Email Path URL to get the user's email information
edit user information
email path url
Finally, add all the information gathered into the Integration Settings from your Form.io Project Base. Open the SAML Signing Certificate XML and Copy and Paste the code, then add your Application ID and Finally add the Email Path URL.
SAML Settings
Now, we can set up our Login Form to Login with SSO Azure SAML. For this example, we will create a Button Component and configure a Custom Logic Action to trigger SAML SSO. Let's get into our forms and add a Button Component into your Login Form.
login form
Then, Select Action: Custom and add the SAML trigger code into Button Custom Logic
Formio.ssoInit('saml');
Then, add a hidden component to our saml token from the URL. Add the following Custom Default Value configurations.
if (Formio.pageQuery().saml) {
Formio.ssoInit('saml');
window.location.replace('/');
}
Finally, we can log in with Azure SAML SSO into our portal.
Login SSO
If we need to configure Roles to map our user groups. You need to create groups in Azure AD SAML. Here is the documentation to create Groups and Claims in Azure AD for SAML. Link
Then you map the groups to a Form.io Role to manage the access to the form definition and submissions.
Settings Form.io SAML Role.
The following instructions show how to setup Auth0 SAML provider.
To get started, first create a new application within Auth0 by logging into your account, and then clicking on Create Application
After you land on the next page, add a Name, then click on Single Page Web Application, and then click on the Create button when you are done.
Now that the application has been created, we will need to ensure that our redirect URL's are configured correctly for your deployment. To start, click on the Settings tab within your Auth0 application, and then set the Allowed Callback URL's to the domain of your application like so.
Next, we will want to enable the SAML 2 Web App AddOn. This can be done by clicking on the AddOns tab, and then clicking on the SAML 2 Web App Addon like so.
This should then open up a SAML configuration modal, where you will need to store some of the SAML configurations. We will want to download the Identity Provider Metadata by clicking on that link shown in the image below.
We will need to store this for later when we configure our Form.io project SAML configurations. Next, click on the Settings tab, and then set the Application Callback URL to the following format.
https://yourdomain.com/myproject/saml/acs
So, for example, it may look like the following.
Now scroll to the bottom and click on the Enable button.
Your application should now be ready for SAML. Let's setup some users to be used within the application.
Next, within Auth0 admin interface, click on User Management and then click on Users link.
You can now create a new user by clicking on the + Create User button.
Next, we will fill out some user information for our user using the application we are developing.
Then click Create to create the new user.
Now that we have a user, we are now ready to integrate our SAML into our Form.io application.
Now, within your Form.io Portal, you will need to navigate to your Project Settings, and then click on Authentication and then SAML.
Next, you will open up your Identity Provider Metadata XML file that we downloaded earlier in this section, and then copy and paste the contents of this file into the following text area.
Next, we will need to look at our XML file and copy the value of the entityID from the XML, and paste that for our Issuer as follows.
Next, we need to figure out the Email Path to find the email address of the user. This can be done by looking at the "email" attribute within the XML file like so.
Next, we will make sure that any user logging into the Form.io SAML will receive the Authenticated role, we can do this by adding the following Role Mapping configurations.
Now click Save Settings, and we will move onto setting up our Login form.
Now that you have the SAML configuration setup, we will now edit our User Login Form of our application. This is the exact same steps as discussed in the Login Form Configuration, so go there and walk through these steps within your project. You are now done configuring your project for Auth0 SAML authentication!
The following instructions show how you will setup the OneLogin SAML Provider.
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.
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/acsNext 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.
Next click Save to save our application.
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.
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
Next, we need to add in parameters for the form.io portal to use.
Mappings:
- roles = "User Roles"
- id = "OneLogin ID"
- email = "email"
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.
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 6mo ago