# SAML ## Introduction Simplify and centralize your user authentication process by integrating SAML into your Form.io project. This integration allows you to configure your application login forms to support SAML SSO authentication for your application users. **SAML Provider** Choosing a SAML provider is the first step in the integration process. A SAML application will then be created and configured. Form.io offers integration with many providers, including the following: * [**OneLogin**](#onelogin) * [**Okta**](#okta) * [**Microsoft Entra ID**](#microsoft-entra-id) (formerly Azure AD) * [**Auth0**](#autho) *** [**Passport Configuration**](#saml-passport-config) Once a provider has been chosen and a SAML application has been created, the next step is to integrate the SAML application with your Form.io project. The integration process involves transferring specific credentials and endpoints from the SAML application and then using that information to construct a Passport Configuration JSON object that will be saved within the Form.io Project connected to your application. Form.io utilizes the Node.js SAML Authentication library. {% hint style="info" %} Form.io utilizes the Node.js SAML Authentication library. \ [**Click Here** ](https://github.com/node-saml/node-saml)for documentation and a full list of SAML Passport properties {% endhint %} *** [**Form.io Authentication Configuration**](#form.io-authentication-configuration) After applying the correct information from your SAML Provider to your Project's authorization settings, the Form.io authentication form embedded in your application will be configured to support SAML SSO authentication. *** [**Portal Base SSO with SAML** ](https://help.form.io/deployments/portal-base-project/portalsso#saml-sso) The following documentation is centralized around applying SAML to a client-based application connected to the Form.io project. The same concepts detailed in this documentation can also be applied to the Form.io Portal Base project that controls your Developer Portal to allow Form.io users to utilize SAML SSO to authenticate into the Form.io environment. *** ### Video Tutorial The following video demonstrates the creation of a SAML application, integration with Form.io, and configuring the authentication form that will instigate the SAML authentication process for the client application. OneLogin serves as the SAML Provider in this video, however, the same principles can be applied to other Providers. {% embed url="" %} ## How does Form.io SAML Work SAML authentication uses settings in the project to communicate with an external SAML identity provider (IdP) in order to authenticate the user into the Form.io environment. The project roles can be mapped to SAML roles via the SAML configuration in the project. When creating the login form, add custom JavaScript to trigger a service provider-initiated SAML authentication flow, that allows users to authenticate using the IdP. The IdP returns a JWT to the user. The following shows step-by-step on how this process works.

1. The **User** navigates to {{baseUrl}}/{{projectAlias}}/saml/sso (Usually via a button on the form that calls `Formio.ssoInit('saml')`) 2. The **Form.io Server** processes the SAML configuration settings into a SAML request .XML document and encodes it into a redirect link to the **IdP Server** for authentication.\ The redirect link looks something like the following:\\ {{Entry Point}}?SAMLRequest= {{encoded xml document}}& relayState={{your relay state}} {% hint style="info" %} The relayState is used to navigate the user back to the SP login page after IdP login and is automatically set to the URL of your SP login page. This can be modified via the relay option when creating the form. {% endhint %} 3. The user is redirected to a login page provided by the **IdP Server** (if the SAML request was valid). 4. Upon successful login, the **IdP Server** sends the user to an HTML document containing JavaScript that makes a POST request containing the SAML response .XML document to the callback URL specified in the SAML configuration.\ The callback URL should point to the assertion consumer service endpoint (ACS) and look something like the following:\ {{baseurl}}/{{projectUrl}}/saml/acs 5. The browser (**User**) executes the JavaScript to make the POST to the ACS endpoint (as described above). 6. The ACS endpoint on the **Form.io Server** processes the SAML response .XML document, verifying that the document and assertions are valid using the certificate specified in the SAMLE configuration.\ It then takes the assertions given by the SAML response XML and generates a Formio JWT token. The server then redirects the user to the relay URL, with the JWT added as a query parameter. It should look something like the following: \ {{relay}}?saml={{JWT}} 7. With the JWT from the query parameter, call `Formio.ssoInit('saml')` again to add the JWT to the browser's local storage.\ The user isnow authenticated to access **Form.io Server** resources! ## General Troubleshooting While the SAML provider configuration and settings fall outside of Form.io, here are some common errors and troubleshooting tips if your SAML authentication isn't functioning correctly. ### Required Config Parameters The only required fields needed by node-saml are... * Issuer - The unique identifier you give when sending saml requests * Cert - Used to verify the saml response document and assertions in the saml response All other fields are based on the configuration you have set in your IdP. This can very widely depending on what IdP you are using. A couple of recommended config parameters are... * Entry Point - The url of your IdPs login endpoint * Callback Url - The url that the saml response is sent to * Want Assertions Signed - Check this if you want to verify that your assertions are signed correctly.\ Note: Make sure your IdP is signing assertions if you have this checked or an error will occur * Want Authn Response Signed - Check this if you want the top level of your saml response document to be signed\ Note: Make sure your IdP is signing the top level of your saml response xml or an errro will occur ### **Errors** #### **Invalid Signature** * **Cause**: The signature in the SAML response or assertion could not be verified, often due to mismatched certificates between the IdP and Form.io or an unsupported signature algorithm. * **Solution**: Ensure that the public certificate used by the IdP matches the one configured in Form.io and that the IdP supported signature algorithm (preferably RSA-SHA256). * Ensure the cert from the Idp matches the cert saved in the Form.io SAML settings \ \ Form.io typically signs: * **SAML Assertions** (the payload that contains authentication and user details). * Optionally, **SAML Responses** (the overall message containing the assertion). If the SAML signature isn't validated correctly, you may need to check the certificate used in the IdP configuration and ensure the hashing algorithm is compatible (e.g., SHA-256). #### **Audience URI mismatch** * **Cause**: The Audience URI in the SAML response from the IdP does not match what Form.io expects. * **Solution**: Verify that the **Audience URI** in the IdP settings matches the URL of your Form.io application. This typically looks like: ```arduino http://myapplicationdomain.com ``` * Ensure there are no typos, extra slashes, or case-sensitivity issues. #### **SAML Assertion is not valid** * **Cause**: The SAML assertion may have expired, the certificate used to sign the assertion could be invalid, or the assertion lacks the necessary conditions. * **Solution**: Check the SAML assertion for correct timestamps and validity. Ensure that the IdP is signing the assertion properly and that Form.io can validate the signature. * Ensure the 'Email Path' and 'Roles Path' in the Form.io SAML settings align with the email and group parameters provided by the IdP. Often, these parameters will be set to 'email' and 'groups.' #### **Invalid RelayState** * **Cause**: The RelayState parameter in the SAML request is either missing or invalid. * **Solution**: Ensure that the RelayState parameter is properly set in the SAML authentication request, and that it is being passed correctly between the IdP and Form.io. This will often time be the hosted application domain. #### **NameID or Groups not found in SAML Assertion** * **Cause**: The SAML assertion does not contain the `NameID or groups` attribute, which is essential for identifying the user or user SAML group. * **Solution**: Ensure the IdP is configured to include the `NameID or group` attribute in the SAML assertion, typically within the `` element. #### **Missing Attribute Statement** * **Cause**: The SAML assertion is missing required attributes that Form.io expects (e.g., email, username, or custom attributes). * **Solution**: Check the IdP configuration to ensure it is passing the required user attributes in the SAML assertion. ### How to Troubleshoot: 1. **Use a SAML Tracing Tool**: Browser extensions like **SAML Chrome Panel** or **SAML-tracer** (Firefox) can capture SAML requests and responses for analysis. 2. **Check Configuration**: Verify that both the IdP and Form.io configurations are aligned, particularly regarding the Audience URI, ACS URL, and signature settings. 3. **Review Logs**: Check the IdP and SP logs for more detailed error messages that might provide clues to what went wrong. 4. **Password Configuration -** Utilize the **Passport Config** over the **SAML Metadata** when configuring the SAML integration settings within the Form.io Project. These error messages are typically due to configuration mismatches or signing issues, and can usually be resolved by carefully reviewing the settings on both sides. ## OneLogin This section covers the [**OneLogin Provider**](https://developers.onelogin.com/saml) SAML application setup process and integration with the Form.io Project. ### **Create and Configure Application** 1. From your OneLogin Admin dashboard, create a new application by clicking the **Applications tab** and then the **Add App** button.

2. Select the **SAML Custom Connector (Advanced)** for **SAML2.0** application

3. Give the Application a name and click the **Save** button with the default configurations ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2Fq5id7sMS36B8hc1dJl8D%2Fsaveapp.jpg?alt=media\&token=2a87dcaa-a560-43ae-82cd-ed618432a8fc) 4. Click the **Configuration** tab to set up the application details * Add the **RelayState** (optional) - Live endpoint of the hosted application\ `https://app.yoursite.com` * Add the **Audience (EntityID)** - Live endpoint of the hosted application\ `https://app.yoursite.com` * Add the **ACS (Consumer) URL Validator** - [ **Live Endpoint**](https://help.form.io/userguide/projects/project-ui#header) of the Form.io Project with form.io\\/saml\\/acs appended at the end of the URL. Backslash characters `\` should be added in front of all forward slash characters `/`\ `https:\/\/myproject.domain\/abc123\/saml\/acs` * Add the **ACS (Consumer) URL** - [**Live Endpoint**](https://help.form.io/userguide/projects/project-ui#header) of the Form.io Project with form.io/saml/acs appended at the end of the URL. \ `https://myproject.domain.com/abc123/saml/acs` The configuration should look similar to the following:

5. Within the Configuration tab, set the **SAML signature element** to the **Both** setting

#### **Configuring Parameters** 6. Click the **Parameters** tab and ensure the following parameter is set (this should be set by default) **NameID** **value** field is configured with the **Email** value 7. Click the **Paramter** Tab, click the **+** button to add a new Parameter * Set the Field Name to **groups** (case sensitive) * Set the Value to **User Roles** * Check the **Include in SAML assertion** flag * **Save** the Parameter

8. The application should have two parameters set\ **NameID Value** (created by default with the application) \ **group** parameter created in the previous step 9. **Save** the application

### Create Users With the application configured, create a user base within the OneLogin Admin dashboard. Users can then be assigned to a Role linked with the SAML Application, enabling mapping between SAML Groups and Form.io roles. 1. Within the OneLogin Admin dashboard, hover over the User tab and click **Users** 2. Click the **New User** button ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FvOfREx2Dw32gcyIVtbra%2Fusers.jpg?alt=media\&token=270fe923-546c-4fdb-812c-517b280d11eb) 3. Input the Information for the User and then click **Save User** 4. Click the **More Action** tab and set a **Password** for the User 5. Generate multiple users to assign them to different roles that will be created in the next step

### Create & Assign Groups With our Users in place, the next step is to create **Roles** the SAML Users will be assigned to. This will allow us to establish mappings between SAML Roles (Groups) and Form.io roles. 1. Within the OneLogin Admin dashboard, hover over the User tab and click **Roles** 2. Click the **New Role** button ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FEKk8Aq4XqrczfvuGzjxW%2Froles.jpg?alt=media\&token=f6017df1-ec8b-4c8b-b7d3-64d1eec07bd8) 3. Give the **Role** a name and select your SAML Application the Role should be associated with 4. Click the **Save** role ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FCLPj7kiH8L9wQhzdv9Mx%2Fassignroles.jpg?alt=media\&token=defe7fb7-181a-48f3-8edc-a7f38f4b4685) 5. Within the **Roles** tab, click the **Role** that was just created and click the **Users** Tab 6. Using the search bar, search and select all Users that should be added to the Role and click **Check**

7. Click the **Add To Role** button for each user 8. Click **Save**

#### **Assign Role To Application** With the Roles established, the next step is to assign the Role to the SAML application 1. Hover over the **Application** tab and select Applications 2. Navigate to your **SAML Application** 3. Click the **Access** tab 4. **Select** all of the **Roles** you wish to assign to the Application\ Users assigned to the selected roles will be associated with the Application. 5. Click **Save**

### Passport Configuration Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration. {% hint style="info" %} [**Click Here**](#saml-passport-config) for more information about SAML Passport Configurations {% endhint %} #### **Download XML File** 1. Navigate to the **OneLogin** application 2. Click the **More Actions** tab and click the **SAML Metadata** button to download the XML info

3. Store the XML information as it will be used to construct the **Passport Config**

4. Construct the **Passport Config JSON** object. Search the XML file for the property titles within the example below and input the data accordingly. * The **identityProviderUrl** and **entryPoint** endpoint can be found by searching the **SingleSignOnService** HTTP-REDIRECT endpoint * The **logoutUrl** endpoint can be found by searching **SingleLogoutService** * The **cert** can be found by searching the **X509Certificate** * The **identifierFormat** can be found by searching **NameIDFormat** * The **audience** must match the **Audience (EntityID)** endpoint within the **Configuration** tab within your OneLogin SAML application. * The **issuer** can be found by searching the **entityID** {% hint style="info" %} Quickly generate the JSON object by utilizing the [**SAML Passport Generator**](#saml-passport-generator) found within the SAML Settings of the Form.io Project. {% endhint %} ``` {"identityProviderUrl": "https://form-dev.onelogin.com/trust/saml2/http-redirect/sso/abc-123", "entryPoint": "https://form-dev.onelogin.com/trust/saml2/http-redirect/sso/abc-123", "logoutUrl": "https://form-dev.onelogin.com/trust/saml2/http-redirect/slo/abc-123", "cert": "abc123", "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "audience": "https://app.yoursite.com", "issuer": "https://app.onelogin.com/saml/metadata/abc-123"} ``` ### **Form.io Integration** With the Passport Config JSON object constructed, the Form.io project can now be configured. 1. Within the Form.io Project, click **Settings** > **Authentication** > **SAML** 2. Click the **Authorization Settings** tab

3. Scroll down and paste the **Passport Config** JSON from the previous step

4. Click the **Configuration** tab and add the following to the **Email Path** setting field\ `email` 5. Click the **Save Settings** #### **Role Mapping** In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings. 6. Within the Form.io SAML settings, click the Configuration tab and set the following to the **Role Path**\ [`groups`](#user-content-fn-1)[^1]

7. Within your OneLogin **SAML Application,** click the **Access** tab and take note of the **Role** **Names** assigned to the application.

8. Back to the Form.io SAML settings, scroll down to the **Role Mapping** setting 9. Map **SAML** **Roles** (case sensitive) to the desired **Form.io Roles** 10. **Save** your settings

After authentication, SAML users assigned to the **Admin** SAML role will obtain the Form.io **Administrator** role, while those assigned to the **Member** role will receive the Form.io **Authenticated** role. This can be seen by inspecting the user object within the dev console.

The **Attribute Statements** and **Group Attribute Statements** section is where we can define the name for different User Information (attributes) and define the name for SAML Groups. This will ensure the required information is provided by the SAML user when they authenticate. 8. Set the following for the **Attribute Statements**

Name	Format	Value
email	Basic	user.email
firstName	Basic	user.firstName
lastName	Basic	user.lastName

8. Set the following for the **Group Attribute Statements**\ Ensure the Matchest regex filter is set to: `.*`

Name	Format	Filter
groups	Unspecified	Matches regex: `.*`

![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FZFgmhgR3ADbAus0DBK8S%2Fattributestatements.jpg?alt=media\&token=ac672add-e832-48dd-9631-473cd7fc1cfe) 9. Click **Next** to complete the configuration of your Okta SAML 2.0 application. ### Create Users With the application configured, create a user base within the Okta Admin dashboard. These Users can then be assigned to a SAML group which will be associated with the SAML Application and allow for mapping between SAML Groups and Form.io roles. 1. Within your Okta Admin dashboard, click the **Directory** tab and select **People**

2. Within the People tab, click the **Add** **Person** button 3. Enter person **details** for the SAML User 4. Click the **Password** dropdown to determine how Users password will be set 5. Click **Save** to add the User

### Create & Assign Groups With our Users in place, the next step is to create **Groups** the SAML Users will be assigned to. This will allow us to establish mappings between SAML Groups and Form.io roles. 1. Within your Okta Admin dashboard, click the **Directory** tab and select **Groups** 2. Click the **Add Group** button ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FImxezlodIYs1ZDTH11sJ%2Fgroupsdirectory.jpg?alt=media\&token=52e40ce9-1a9f-44e3-ac86-833e8471886e) 3. Give your Group a **Name** and click **Save** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FRdQkOczNQLANKalyJ9Ji%2Faddgroup.jpg?alt=media\&token=8f16a70f-f5dd-4771-acb6-5b8df6fd6824) With a Group created, the next step is to assign users to the Group. 4. From the **Group** tab, select the Group to add Users to 5. Click the **Assign people** button

6. Click the **+** button next to a User to assign them to a Group

#### **Assign Groups To SAML Application** 7. To assign the Group, open the **Directory** tab, select the **Group,** and click the **Applications** tab

8. Click the **Assign applications** button 9. Within the modal window, click the **Assign** button next to your **SAML application**

### Passport Configuration Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration. {% hint style="info" %} [**Click Here**](#saml-passport-config) for more information about SAML Passport Configurations {% endhint %} 1. Within the Okta Admin Dashboard, click the **Application** tab and select your SAML app 2. Click the **Sign On** tab and copy the **Metadata URL** 3. Copy the **Metadata URL** and open the URL within your browser

4. Store the XML information as it will be used to construct the **Passport Config**

5. Construct the **Passport Config JSON** object. Search the XML file for the property names within the example below and input the data accordingly. * The **identityProviderUrl** and **entryPoint** endpoints can be found by searching **SingleSignOnService** * The **cert** can be found by searching the **X509Certificate** * The **identifierFormat** can be found by searching **NameIDFormat** (emailAddress endpoint) * The **issuer** can be found by searching the **entityID** * The **audience** must match the **Audience Restriction** endpoint within the **General** tab of your Okta SAML application. {% hint style="info" %} Quickly generate the JSON object by utilizing the [**SAML Passport Generator**](#saml-passport-generator) found within the SAML Settings of the Form.io Project. {% endhint %} Example Template:

{"identityProviderUrl": "https://trial-3793339.okta.com/app/trial-3793339_formiossoauthentication_1/abc123/sso/saml",
  "entryPoint": "https://trial-3793339.okta.com/app/trial-3793339_formiossoauthentication_1/abc123/sso/saml",
  "cert": "abc123",
  "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "issuer": "http://www.okta.com/abc123",
  "audience": "https://yourdomain.com/myproject/saml/metadata"}

### Form.io Integration With the Passport Config JSON object constructed, the Form.io project can now be configured. 1. Within the Form.io Project, click **Settings** > **Authentication** > **SAML** 2. Click the **Authorization Settings** tab

3. Scroll down and paste the **Passport Config** JSON from the previous step

4. Click the **Configuration** tab and add the following to the **Email Path** setting field\ `email` 5. **Save** your settings #### **Role Mapping** In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings. 6. Within the Form.io SAML settings, click the Configuration tab and set the following to the **Role Path**\ [`groups`](#user-content-fn-1)[^1]

7. Within your **Okta** **SAML Application,** click the **Assignments** tab and click **Groups**.\ Take note of the **Group** **Names** assigned to the application.

8. Back to the Form.io SAML settings, scroll down to the **Role Mapping** setting 9. Map **Okta** **SAML** **Groups** (case sensitive) to the desired **Form.io Roles** 10. **Save** your settings

4. Search and select **Entra SAML Toolkit**

5. Give the **Application** a name and click the **Create** button

6. Within the Entra ID application, click the **Single sign-on** button in the **Manage** toolbar 7. Select the **SAML** option

8. Within the application **Set up** section, scroll down and copy the **Microsoft Entra Identifier** endpoint. Save this ID for later.

9. Scroll back up to the **Basic SAML Configuration** section and click the **Edit** button

10. Apply the following **SAML Configuration** for the Application * Click the **Add Identifier** button and input the **Identifier (Entity ID)** - Microsoft Entra Identifier copied in the previous step\ `https://sts.windows.net/abc-123-def-456` * Add the **Reply URL** (Assertion Consumer Service URL) - [**Live Endpoint** ](https://help.form.io/userguide/projects/project-ui#header)of the Form.io Project application with form.io/saml/acs appended at the end of the URL. \ `https://myproject.domain.com/abc123/saml/acs` * Add the **Sign On URL** - Application domain endpoint\ `https://myapplication.domain.com` * **Save** the settings ![Edit Basic Information](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FeXPCMqTh9VJImpWI57lm%2Fbasicsamlconfig.jpg?alt=media\&token=b144e005-8f5d-4281-bbc6-b96a1045d838) 11. Within the **Single sign-on** of your application, click the **Edit** button for the **SAML Certificates**

12. Set **Signing Option** to **Sign SAML response and assertion** 13. Set **Signing Algorithm** to **SHA-256** 14. Click the **Save** button

### Create Users With the application configured, we can now add Users that will authenticate against Entra ID. 1. Return to the **Entra ID Portal** 2. Within the left-hand navigation bar, click the **Manage** tab and then **Users** {% hint style="info" %} Ensure you [**assign Microsoft License**](https://learn.microsoft.com/en-us/entra/fundamentals/license-users-groups) to users or groups within Entra ID {% endhint %} 2. Click the **+New User** button

3. Input the User information and click **Review + create** button 4. Select how the **User** **Password** should be set {% hint style="warning" %} Ensure the User **email address** and **name** is set within the **Properties** tab of the user profile Contact your Azure administrator if these properties are not available {% endhint %}

5. Click the **Create** button after reviewing the User information 6. Create several other users to test Group and Role mapping detailed in the next section.

### Create & Assign Groups With our Users in place, the next step is to create **Groups** the Entra ID Users will be assigned to. This will allow us to establish mappings between SAML Groups (Roles) and Form.io roles. 1. Click the **Groups** tab and **All Groups** within the left-hand navigation bar. {% hint style="info" %} Ensure you a [**assign Microfosft License**](https://learn.microsoft.com/en-us/entra/fundamentals/license-users-groups) to users or groups within Entra ID {% endhint %} 2. Click the **+New Group** button

3. Give the Group a **Group Name** and keep the remaining settings at their default values

4. Click the the **Create** button 5. Return to the main Group page and click the **Group** we just created

6. Expand the **Manage** tab and click **Members** 7. Click the **+Add members** button

6. **Search** for the User created in the previous section 7. Tick the **checkbox** next to the members you wish to add 8. Click the **Select** button at the bottom of the page

9. Follow the same steps to create additional Groups

#### **Enable Group Claims** With the Groups established, the next step is to enable the Group claim within the Entra ID application. 1. Navigate back to your **Entra ID SAML** application 2. Click the **Single sign-on** tab 3. Edit the **Attributes & Claims** section

4. Click the **+Add a group claim** button

5. Select the **Groups assigned to the application** option 6. Click the **Source attribute** dropdown and select the **Cloud-only group display names** option 7. **Save** the claim

8. Within the Attributes & Claim page, take note of the **Group Claim** endpoint \ `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`

#### **Assigning Groups to Application** 1. Navigate back to your **Entra ID SAML** application 2. Select the **Assign users and groups** tab then click the **+ Add user/group** button 3. On the next screen, click the **None Selected**

4. Tick the checkbox next to the **Groups** you wish to assign to the application 5. Click the **Select** button at the bottom of the screen and then **Assign** on the following page

After assigning the Groups, you should see the Groups displayed within the User and Groups tab of the Entra ID application. Users assigned to the selected groups will be associated with the Entra ID Application.

### Passport Configuration Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration. {% hint style="info" %} [**Click Here**](#saml-passport-config) for more information about SAML Passport Configurations {% endhint %} #### **Download XML File** 1. Navigate to your **Entra ID SAML** application 2. Click the **Single sign-on** tab 3. Within the **SAML Certificates** click the **download** button for the **Federation Metadata XML**

4. Store the XML information as it will be used to construct the **Passport Config**

5. Construct the **Passport Config JSON** object by locating the parameter titles in the XML file as shown in the example below, and input your specific data accordingly ``` {"identityProviderUrl": "https://login.microsoftonline.com/abc-123-def-456/saml2", "entryPoint": "https://login.microsoftonline.com/abc-123-def-456/saml2", "logoutUrl": "https://login.microsoftonline.com/abc-123-def-456/saml2", "cert": "abc123def567", "issuer": "https://sts.windows.net/1234-9f02-4c3a-abd-1234/", "callbackUrl": "https://app.domain.com/form.io/saml/acs", "signatureAlgorithm": "sha256"} ``` * The **identityProviderUrl**, **entryPoint**, and **logoutUrl** endpoint can be found by searching the **SingleSignOnService** * The **cert** can be found by searching the **X509Certificate** * The **issuer** can be found by searching the **entityID** * The **callbackUrl** must match the **Reply URL** endpoint within the **Single sign-on** tab of your Entra ID application * The **signatureAlgorithm** will be set to **sha256** {% hint style="info" %} Quickly generate the JSON object by utilizing the [**SAML Passport Generator**](#saml-passport-generator) found within the SAML Settings of the Form.io Project. {% endhint %} ### Form.io Integration With the Passport Config JSON object constructed, the Form.io project can now be configured. 1. Within the Form.io Project, click **Settings** > **Authentication** > **SAML** 2. Click the **Authorization Settings** tab

3. Scroll down and paste the **Passport Config** JSON from the previous step

4. Click the **Configuration** tab and add the following to the **Email Path** setting field\ `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` 5. Save your **Settings**

#### **Role Mapping** In many cases, you may want to map the SAML Role associated with the SAML User to a Form.io Role. Apply the following configurations to configure the Role mappings. 6. Within the Form.io SAML settings, click the Configuration tab and set the following to the **Role Path**\ `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`

7. Back to your **Entra ID** **SAML Application,** click the **Users and group** tab. Take note of the **Group** **Names** assigned to the application.

8. Back to the Form.io SAML settings, scroll down to the **Role Mapping** setting 9. Map **SAML** **Roles** (case sensitive) to the desired **Form.io Roles** 10. **Save** your settings

2. From the application Modal window, select **Single Page Web Applications**

3. Provide a **name** for the Application and click the **Create** button 4. Click the **Addons** tab 5. Toggle the **SAML 2.0** button

6. Click the **Settings** tab * Within the Modal window, provide the **Allowed Callback URL.**\ Also known as the [**ACS** **endpoint**](#user-content-fn-2)[^2] by other SAML providers. \ For this value, copy your Form.io project endpoint and append **/saml/acs** at the end of the URL. \ \ \&#xNAN;*Example*: if your project API endpoint is \ ****, \ then your Assertion Consumer Service URL will be the following.\ `https://yourdomain.com/myproject/saml/acs`

* Scroll down and click the **Enable** button * After enabling the application, click **Save**

The application should now be ready for SAML Authentication. The next step is to create Groups the SAML users will be assigned to. These Groups will then be mapped to Form.io roles for granular permissions. ### Create Users With the application configured, create a user base within the Auth0 Admin dashboard. These Users can then be assigned to a SAML group which will be associated with the SAML Application and allow for mapping between SAML Groups and Form.io roles. 1. Within the Auth0 admin dashboard, click the **User Management** tab and then **Users**

2. Click the **+Create User** button

3. Input user information and click **Create** ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2FzykLf7h3gJ5Mw4pPhOeC%2FUsers%202022-05-04%2014-01-57.png?alt=media\&token=66ea0fd5-d078-4765-86cc-dbbaeddd4c20) 4. Create additional users to assign to the different Roles that will be established in the next step.

### Create & Assign Groups With our Users in place, the next step is to create **Groups** the SAML Users will be assigned to. Auth0 groups are created and managed through extensions. This group extension will allow us to establish mappings between SAML groups and Form.io roles for granular permissions. 1. Within the left-hand navigation bar, click **Extensions** 2. Select **Auth0 Authorization**

3. Click **Install** within the Extension modal

4. Once installed, click the **Extension** and **Authorize** the extension for your application 5. Click the **GO TO CONFIGURATION** button

6. Click the **Groups** radio button 7. Click the **Publish Rule** button

8. Within the Extension, click the **Groups** tab then **+ Create Your First Group** button

9. Give the Group a **Name** and **Description**

10. Click the **+Add Member** button

11. Search and **select** the **user(s)** to assign to the Group and **Save**

### Passport Configuration Once the SAML application setup is finalized, XML data will be extracted from the application and utilized for building the Passport Configuration. This JSON configuration will be saved to the Form.io Project to complete the integration. {% hint style="info" %} [**Click Here**](#saml-passport-config) for more information about SAML Passport Configurations {% endhint %} 1. Within the Auth0 Admin Dashboard, click the **Application** tab and select your SAML app 2. Click the **Add On** tab and click the **SAML2 Web App**

3. Within the **Usage** tab, click the **Download** to extract the XML file

4. Store the XML information as it will be used to construct the **Passport Config**

5. Construct the **Passport Config JSON** object. Search the XML file for the property titles within the example below and input the data accordingly. * The **identityProviderUrl** and **entryPoint** endpoint can be found by searching the **SingleSignOnService** HTTP-REDIRECT endpoint * The **cert** can be found by searching the **X509Certificate** * The **identifierFormat** can be found by searching **NameIDFormat** * The **logoutUrl** endpoint can be found by searching **SingleLogoutService** * The **callbackURL** must match the **Application Callback URL** endpoint within the **Setting** tab of your Auth0 SAML application. * The **issuer** can be found by searching the **entityID** * Set the **wantAuthnResponseSigned** to **false** {% hint style="info" %} Quickly generate the JSON object by utilizing the [**SAML Passport Generator**](#saml-passport-generator) found within the SAML Settings of the Form.io Project. {% endhint %} ``` {"identityProviderUrl": "https://dev-3co66mp5xvfzciov.us.auth0.com/samlp/abc123", "entryPoint": "https://dev-3co66mp5xvfzciov.us.auth0.com/samlp/abc123", "cert": "abc123def456", "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "callbackUrl": "http://localhost:3000/ipajzfemjjsisnv/saml/acs", "issuer": "urn:dev-abc123.us.auth0.com", "wantAuthnResponseSigned": false} ``` ### Form.io Integration With the Passport Config JSON object constructed, the Form.io project can now be configured. 1. Within the Form.io Project, click **Settings** > **Authentication** > **SAML** 2. Click the **Authorization Settings** tab

3. Scroll down and paste the **Passport Config** JSON from the previous step

4. Click the **Configuration** tab and add the following to the **Email Path** setting field\ `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` 5. **Save** your settings

7. Within your **Auth0** **SAML application,** click the **Extensions** tab, and the **Auth0 Authorization** extension. 8. Click the **Groups** tab and take note of the **Groups** **Names** assigned to the extension.

9. Back to the Form.io SAML settings, scroll down to the **Role Mapping** setting 10. Map **SAML** **Roles Names** (case sensitive) to the desired **Form.io Roles** 11. **Save** your settings

#### **Authentication Configuration** The final step is to configure the Form.io Login form embedded in your application to support SAML. Alternatively, you can modify your application to support a similar process. Follow the link below for documentation. [**Form.io Authentication Configuration**](#form.io-authentication-configuration) ## Form.io Authentication Configuration SAML Authentication can be set up either by utilizing a Form.io Login form or by modifying the code within your application ### **Login Form Configuration** Follow the steps below to achieve SAML SSO authentication using a Form.io Login form. 1. Edit the authentication Form embedded within your application 2. Drag and drop a **Button** component 3. Modify the **Label** to reflect SAML authentication 4. Click the **Action** dropdown and select **Custom** 5. Copy the following code and paste it into the **Button Custom Logic** code block ```javascript Formio.ssoInit('saml'); ``` ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MPHoF2HwOA0s5HV_AIB%2Fuploads%2F8Gm5Eim9qkHqr8NIjmpG%2Fbuttonlogic.jpg?alt=media\&token=3945066d-8620-40e5-a31f-62d8e3921ab6) 6. Add a **Hidden** component 7. Click the **Data** tab and open the **Custom Default Value** tab 8. Add the following **JavaScript** within the code block 9. **Save** the Settings and Form ```javascript if (Formio.pageQuery().saml) { Formio.ssoInit('saml'); window.location.replace('/'); } ``` ![](https://3305536326-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MPHoF2HwOA0s5HV_AIB%2F-MPkVy0fPX_6GTdReOws%2F-MPkWDpa2Liy-dRTf0vo%2FScreen%20Shot%202020-12-29%20at%204.00.56%20PM.png?alt=media\&token=41ec03c6-0477-46da-88ef-7f7083b2bd1b) ### Application Configuration To achieve authentication within your application, the following code will instigate the SSO process. ```javascript import { Formio } from '@formio/js'; 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 on 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). ```javascript ``` ## SAML Passport Configuration The "Passport Config" setting simplifies the process of configuring SAML authentication settings for your Form.io project, allowing you to specify how your application interacts with the SAML identity provider using JSON configuration. Passport then utilizes this configuration to manage the authentication flow and grant access to authenticated users {% hint style="info" %} Form.io utilizes the Node.js SAML Authentication library. \ [**Click Here** ](https://github.com/node-saml/node-saml)for documentation and a full list of SAML Passport properties {% endhint %} 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": "" "entryPoint": "", "logoutUrl": "", "cert": "", "issuer": "", "audience" "", "wantAssertionsSigned": false } ``` This JSON configuration will ensure that Form.io is aware that it should not expect the assertions to be cryptographically signed. {% hint style="info" %} For those customers that use private key encryption for SAML responses and/or a private key for decryption, we provide two environment variables which allows you to 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. {% endhint %} ### SAML Passport Generator Quickly generate the Passport JSON object by utilizing the SAML Passport Generator found within the SAML Settings of the Form.io Project. This generator allows the user to simply input the required endpoints and credentials from the XML data of the SAML provider. The generator will then output the correct JSON structure for the user saving time and relieving potential user error. To access the Passport Generator, navigate to the SAML settings page: **Settings** > **Authorization** > **SAML** > **Authorization Settings** {% embed url="" %} Scroll down to the Passport Configuration of the settings page. Here you can select different SAML Properties required by the SAML provider. Once selected, input the correlated endpoint or settings from the XML file of your SAML provider.

A full JSON object will be generated and passed to the Passport configuration which will be used to authenticate and authorize SAML users.

### Custom Parser The Custom Parser generates a custom payload for the JWT token based on the SAML Profile object of the authenticating SAML user. This feature opens up additional SAML Profile attributes and claims within the user object as well as more granular control over SAML/Form.io role mappings. {% hint style="info" %} The API Server will first check if there is data saved to the "Custom Parser" tab before generating a token. If the Custom Parser is being utilized, then the filled Profile Fields are not taken into account when generating the JWT token. The Project ID within the payload can not be changed. {% endhint %} #### Custom Parser Example This example will include additional profile claims saved to the SAML Profile object as well as the ```javascript user = { _id: profile.id, data: { id: profile.id, roles: profile.roles, email: profile.email, name: 'Joe Smith' }, roles: [ 'ROLE_ID_1', 'ROLE_ID_2' ] } ``` *Profile* – the data from the SAML profile object. *Roles* - These are the IDs of the project roles you would like this user to have when authenticating. ### 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.

[^1]: This value is referencing the SAML group parameter configured within the application [^2]: The ACS URL is an *endpoint on the service provider where the identity provider will redirect to with its* authentication response