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.

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.

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 clicking 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 links to these configurations could be found on Sign On tab.

You will need to copy the Metadata XML and save it in a text editor for later Form.io configurations.

The Issuer info can be found by clicking on the View SAML Setup Instructions button.

Once you click on View SAML Setup Instructions, 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.

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.

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 hardcoded. 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 users. 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.

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>

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

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.

Azure AD SAML

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.

Add Azure AD SAML Subscription

Sign in to the Azure portal, on the left navigation pane, select the Azure Active Directory service.

Navigate to Enterprise Applications and then select All Applications. Add a 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.

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.

Then, in the Basic SAML Configuration click on the Edit Icon.

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/

Now, we can add users or groups to grant access to the Azure AD SAML Application

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.

Then, get the SAML Issuer ( Application ID)

And then, the Email Path URL to get the user's email information

Azure+Form.io Configuration

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.

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.

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.

Form.io Users & Groups

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.

AuthO SAML

The following instructions show how to setup Auth0 SAML provider.

Create Application

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.

Configure Application

Now that the application has been created, we will need to ensure that our redirect URLs are configured correctly for your deployment. To start, click on the Settings tab within your Auth0 application, and then set the Allowed Callback URLs 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 the 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.

Adding Users

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.

Form.io Configuration

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.

Login Form Configuration

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!

OneLogin SAML

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

Create Application

The first thing we will do is 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/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

In addition, you need to configure the Audience (EntityID) for your project to point to the URL of your hosted application.

https://app.yoursite.com

The configuration will look like the following.

Next, set SAML signature element as Both.

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

You can use SAML Metadata to create SAML Passport Configuration. The following properties are required for configuration: identityProviderUrl, entryPoint, logoutUrl, cert, issuer, audience. Open the XML file and copy the value of the identityProviderUrl, entryPoint, logoutUrl from the XML.

Copy cert, issuer from the SSO tab and audience from the Configuration tab.

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"

SAML Passport Configuration

Depending on your Identity Provider, it may become necessary to exert a greater level of control over certain configuration parameters. To enable this, the Form.io SAML configuration menu includes a "Passport Config" tab from which you can use JSON to configure your project's SAML authentication.

Keep in mind that the Enterprise Server will first check to see if the "SAML Metadata" tab has data before it parses the "Passport Config" JSON object. If you'd like to use Passport Config, make sure the "SAML Metadata" tab has been cleared of all of its data.

This field expects a JSON object, the properties of which you can find documented here. As an example, many Microsoft Azure Active Directory deployments do not cryptographically sign their SAML assertions (despite signing the top level SAML response). Form.io, however, expects both the SAML response and the SAML assertions to be signed by default. In this case, your Passport Config JSON object would set the wantAssertionsSigned parameter to false, and might look something like this:

{
  "identityProviderUrl": "<identity provider URL>"
  "entryPoint": "<entry point URL>",
  "logoutUrl": "<logout url>",
  "cert": "<cert>",
  "issuer": "<issuer url>",
  "audience" "<audience url>",
  "wantAssertionsSigned": false
}

This JSON configuration will ensure that Form.io is aware that it should not expect the assertions to be cryptographically signed.

For those customers that use private key encryption for SAML responses and/or a private key for decryption, we provide two environment variables which allow you provide the absolute paths to those key files in your container's file system rather than as plain text string values in the Passport Config JSON object. Those variables are SAML_PASSPORT_PRIVATE_KEY_PATH and SAML_PASSPORT_DECRYPTION_PVK_PATH. Alternatively, you can specify the private key and/or the decryption private key as strings in the JSON object.

Test Connection to SAML - COMING SOON

After the XML Metadata or Passport Config is filled in, you can use a test connection to SAML. Сlick on the "Save SAML Authorization Settings and Connect to SAML" button, and all unsaved authorization SAML settings will be saved and a new window will open with a test connection to the SAML provider.

After successful authorization, the authorized user's profile object will be available. This will make it easier to fill in the Profile Fields or use Custom Parser.

Custom Parser - COMING SOON

Custom Parser allows to generated payload for the JWT token based on SAML Profile object claiming certain roles configured within the project. At the same time, the project id cannot be changed.

Server will first checks if there is data on the "Custom Parser" tab before generating token. If you use a Custom Parser, then the filled Profile Fields are not taken into account when generating token

“User” should be set into the following format:

user = {
  _id: profile.id,
  data: {
    id: profile.id,
    roles: profile.roles,
    email: profile.email,
    name: 'Joe Smith'
  },
  roles: [
    'ROLE_ID_1',
    'ROLE_ID_2'
  ]
}

ROLE_ID_1, ROLE_ID_2 - These are the ID’s of the project roles you would like this user to have when authenticating.

Profile – the data from the SAML profile object.

Last updated