M-FILES CORPORATION

SETTING UP THE BACKEND FOR THE

NEW M-FILES WEB AND WEB-BASED ADD-INS
FOR M-FILES SEPTEMBER '22 UPDATE AND EARLIER

LAST UPDATED 17 NOVEMBER 2022

VERSION 3.4
Contents
1. Version Information ............................................................................................................................................................ 3

2. Introduction ........................................................................................................................................................................ 3

2.1 Prerequisites ............................................................................................................................................................. 3

3. Preparing the Internet Information Services Server ........................................................................................................... 4

3.1 Adding the URL Rewrite Component ........................................................................................................................ 4

3.2 Setting Up the Application Request Routing Cache Component .............................................................................. 4

4. Configuring the vNext Backend Server ............................................................................................................................... 6

4.1 vNext as a New Server .............................................................................................................................................. 6

4.2 vNext as a Web Application Under the Current M-Files Web Server ..................................................................... 10

5. Configuring the Authentication Mode and Allowed Server Variables .............................................................................. 15

6. Validating the Server Connection ..................................................................................................................................... 16

7. Optional: Setting Up OAuth 2.0 ........................................................................................................................................ 17

8. Optional: Defining Settings for Cross-Origin Resource Sharing ........................................................................................ 17

9. Change History .................................................................................................................................................................. 17

10. Reference Documents ................................................................................................................................................. 18

Appendix A: Additional Settings ................................................................................................................................................ 19

Settings for Cross-Origin Resource Sharing ........................................................................................................................... 19

M-Files Web Specific Settings ............................................................................................................................................... 21

M-Files Server Firewall .......................................................................................................................................................... 21

Appendix B: Troubleshooting .................................................................................................................................................... 22

vNext Backend Server Not Working After Updating M-Files Server to March '20 Update ................................................... 22

vNext Backend Server Not Working After Updating M-Files Server to January '20 Update ................................................. 22
1. Version Information

This document is for M-Files September '22 Update and earlier. If you use M-Files October '22 update or later and M-Files
Web has not been previously set up on the server, instead refer to Setting Up Web and Mobile Access to M-Files.

2. Introduction

This document tells you how to set up the backend server environment for the new M-Files Web (also called vNext or vNext-
based M-Files Web). In addition to M-Files Web, the backend service allows vNext-based add-ins (for example, for M-Files
Add-In for Teams and SharePoint Online) to connect to M-Files Server. The vNext web engine is included in the M-Files
server software package.

The document is intended for M-Files consultants and customer IT administrators who are setting up the new M-Files Web
and the above-mentioned add-ins.

Note: This environment is available for M-Files Online installations only.

2.1 Prerequisites

Before you continue with the setup, make sure that these prerequisites have been completed:

• You use the latest available, 64-bit installation of M-Files.

o For the add-ins, the minimum requirement is M-Files November '19 Update.
o The new M-Files Web user interface is supported in M-Files December '20 Update and later.
• You have the license for the component that you want to use:
PRODUCT LICENSE

M-Files for Teams and SharePoint Online M-Files for SharePoint

M-Files for Salesforce CRM M-Files for Salesforce CRM

New M-Files Web M-Files Web (vNext)

Contact [email protected] if you do not yet have a license.

• You use Windows Server 2012 or later and have the required features in use.

To enable the required features in Windows Server 2012:

1. Open the Windows start menu, type in server manager, and open Server Manager.
2. In Server Manager, select Manage > Add Roles and Features.
3. Under Server Roles, make sure Web Server (IIS) is enabled.
4. Under Features, make sure .NET Framework 4.5 Features > .NET Framework 4.5 is enabled.
5. Under Web Server Role (IIS) > Role Services, make sure that these features are enabled:
o Web Server > Common HTTP Features
▪ Default Document
▪ Directory Browsing

Page 3 of 22 M-Files Corporation | www.m-files.com | [email protected]

 ▪ HTTP Errors
▪ Static Content
o Web Server > Health and Diagnostics
▪ HTTP Logging
o Web Server > Performance
▪ Static Content Compression
o Web Server > Security
▪ Request Filtering
o Web server > Application Development Features
▪ WebSocket Protocol
This feature is required for electronic signatures.
o Management Tools
▪ IIS Management Console
6. Finally, in the Confirmation section, select Install.

3. Preparing the Internet Information Services Server

The Internet Information Services (IIS) server is used as a reverse proxy server to expose the vNext backend server over a
secure protocol for public access. For this purpose, you need to install the URL Rewrite and Application Request Routing IIS
components as explained in this section.

3.1 Adding the URL Rewrite Component

The URL Rewrite component is a rule-based URL rewriting engine. It is used for transforming the public URL request into a
vNext backend server URL. Download the URL Rewrite extension and install it to the server computer. The download page
also provides a more exhaustive description of the component.

3.2 Setting Up the Application Request Routing Cache Component

In addition to the URL Rewrite component, you need to install Application Request Routing Cache by following these steps:

1. Download the Application Request Routing extension and install it to the server computer.
2. Restart IIS.
a) Open the Windows command prompt as an administrator.
b) Type in and execute the following command:
iisreset /restart
3. Open Internet Information Services (IIS) Manager and select the server node.

Page 4 of 22 M-Files Corporation | www.m-files.com | [email protected]

 4. Open Application Request Routing Cache.

5. Click the Server Proxy Settings… link under the Actions > Proxy section.

6. Under Actions, make sure that the Enable proxy checkbox is checked and select Apply.

You can keep the other settings as default, but if you want, you can edit them. For example, the Time-out (seconds) and the
Keep alive settings.

Page 5 of 22 M-Files Corporation | www.m-files.com | [email protected]

4. Configuring the vNext Backend Server

Environment setup structure:

• In a single-server machine setup, the vNext server configuration and the IIS configuration are carried out on the
same machine.
• In proxy-application server model with a separate server for IIS and the M-Files application, the IIS configuration is
carried out on the proxy server and the CORS configuration on the application server.

Image 1: In a proxy-application server model, the IIS configuration is carried out on the proxy server and the CORS configuration on the
application server.

If you are configuring the vNext backend server as a completely new installation, follow the instructions in section 4.1.
Alternatively, if you want to configure vNext to run based on your current M-Files Web deployment, see section 4.2 instead.

Note: If you are using a proxy–application server model, update the url value of the action element in the
vNext.config file with your application server URI and complete the IIS configuration on the proxy server
machine. Use the port number 7767 for the application server. For more information, see the definition for
GRPCWEBPORT in M-Files Web Specific Settings.

Note: The backend server must use the same connection protocol (HTTP or HTTPS) as the add-in host
environment.

4.1 vNext as a New Server

To configure vNext as a new server:

1. In Internet Information Services (IIS) Manager, either:

a) Create a new site and select it.
or
b) Select the default site in the navigation pane.
2. Select Bindings in the right-side Actions area.

Page 6 of 22 M-Files Corporation | www.m-files.com | [email protected]

 3. Set your site binding and the SSL certificate.

If you do not yet have an SSL certificate available, you can find instructions for creating and configuring SSL
certificates on the Internet. Refer to, for instance, this Digicert article.

4. Copy the attached configuration, vNext.config, into a physical location (for example C:\MFilesWeb_vNext).
5. Rename the file to web.config.
The name of the attached configuration is vNext.config to distinguish it from an earlier version of the file.
6. Specify that file location as the physical path of the site.

You can open the Edit Site dialog by selecting the site and then clicking Basic Settings… in the right-side Actions area.

Page 7 of 22 M-Files Corporation | www.m-files.com | [email protected]

 7. Open the URL Rewrite section for the site and make sure that the inbound rules are enabled.

Page 8 of 22 M-Files Corporation | www.m-files.com | [email protected]

 8. Optional: If there are no rules, you can add them manually according to the vNext.config content.
You must first add the rule and then a rewrite map.
a) To add a rule:
i. Under the Actions section, select Add Rule(s)…
ii. In the Add Rule(s) dialog, under Inbound rules, select Blank rule and click OK.
iii. Define the settings according to the vNext.config content. You can use the image below as
reference.

Note: If you are using a proxy–app server model, enter the URL of the application server to the
Rewrite URL field instead of localhost.

For example: http://appserver.mycompany.com:7767/{R:1}

Page 9 of 22 M-Files Corporation | www.m-files.com | [email protected]

 b) To add a rewrite map:
i. Under the Actions section, select View Rewrite Maps…
ii. In the View Rewrite Maps window, under the Action section, select Add Rewrite Map…
iii. Enter MapProtocol as the map name, and click OK.

iv. In the Edit Rewrite Map window, under the Action section, select Add Mapping Entry… and create
two entries according to the examples below.

9. To configure the authentication settings, see section 5.

10. Restart Internet Information Services (IIS).
a) Open the Windows command prompt as an administrator.
b) Type in and execute the following command:
iisreset /restart

Note: In some cases, you may need to restart the IIS server machine for the configuration to take effect.

4.2 vNext as a Web Application Under the Current M -Files Web Server

You can alternatively configure the vNext server as a new web application under your current M-Files Web site by following
the instructions below, or by using the ConfigurevNextServerUndervCurrent.ps1 PowerShell script that is part of
the same multi-file document as this guide. The PowerShell script is designed for cloud server deployments.

Important: Before running the script, modify the value of the $mfilesFolder variable to point to your M-Files
installation directory (for example C:\Program Files\M-Files). Additionally, make sure the example
Default Web Site value refers to your website name (check the website name from IIS Manager).

1. In Internet Information Services (IIS) Manager, right-click the current M-Files Web server site (for example Default
Web Site).

Page 10 of 22 M-Files Corporation | www.m-files.com | [email protected]

 2. Select Add Application to add a new web application for the site.

3. Copy the attached configuration, vNext.config, into a physical location (for example C:\MFilesWeb_vNext).
4. Rename the file to web.config.
The name of the attached configuration is vNext.config to distinguish it from an earlier version of the file.
5. Specify that file location as the physical path of the site.

Page 11 of 22 M-Files Corporation | www.m-files.com | [email protected]

 6. Open the URL Rewrite section for the site and make sure that the inbound rules are enabled.

Page 12 of 22 M-Files Corporation | www.m-files.com | [email protected]

 7. Optional: If there are no rules, you can add them manually according to the vNext.config content.
You must first add the rule and then a rewrite map.

Note: The default contents of the vNext.config file and using localhost as the URL apply only when the
environment is set up on one computer. If you have M-Files Server on a different computer, you must use the
URL of the M-Files Server when defining the settings.

a) To add a rule:To add a rule:

i. Under the Actions section, select Add Rule(s)…
ii. In the Add Rule(s) dialog, under Inbound rules, select Blank rule and click OK.
iii. Define the settings according to the vNext.config content. You can use the image below as
reference.

Page 13 of 22 M-Files Corporation | www.m-files.com | [email protected]

 Note: If you are using a proxy–app server model, enter the URL of the application server to the
Rewrite URL field instead of localhost.

For example: http://appserver.mycompany.com:7767/{R:1}

b) To add a rewrite map:

i. Under the Actions section, select View Rewrite Maps…
ii. In the View Rewrite Maps window, under the Action section, select Add Rewrite Map…
iii. Enter MapProtocol as the map name, and click OK.

iv. In the Edit Rewrite Map window, under the Action section, select Add Mapping Entry… and create
two entries according to the examples below.
v. Under the Actions section, select View Rewrite Maps…
vi. In the View Rewrite Maps window, under the Action section, select Add Rewrite Map…
vii. Enter MapProtocol as the map name, and click OK.

viii. In the Edit Rewrite Map window, under the Action section, select Add Mapping Entry… and create
two entries according to the examples below.

8. To configure the authentication settings, see section 5.

9. Restart Internet Information Services (IIS).
a) Open the Windows command prompt as an administrator.
b) Type in and execute the following command:
iisreset /restart

Note: In some cases, you may need to restart the IIS server machine for the configuration to take effect.

Page 14 of 22 M-Files Corporation | www.m-files.com | [email protected]

5. Configuring the Authentication Mode and Allowed Server Variables

Configure the authentication mode of the vNext backend server by following the instructions below, or by using the
ConfigurevNextServerUndervCurrent.ps1 PowerShell script that is part of the same multi-file document as this
guide. The PowerShell script is designed for cloud server deployments.

1. In Internet Information Services (IIS) Manager, select the vNext site or application depending on your vNext backend
server configuration method, and open the Configuration Editor section.

2. Enter the following text to the Section field and press Enter to open the Windows authentication settings for vNext
backend server: system.webServer/security/authentication/windowsAuthentication
3. Set the enabled property to False and click Apply in the right-side Actions area.

4. Enter the following text to the Section field and press Enter to open the anonymous authentication settings for vNext
backend server: system.webServer/security/authentication/anonymousAuthentication

Page 15 of 22 M-Files Corporation | www.m-files.com | [email protected]

 5. Set the enabled property to True and click Apply in the right-side Actions area.

6. Enter the following text to the Section field and press Enter to open the Allowed Server Variables settings for vNext
backend server: system.webServer/rewrite/allowedServerVariables
7. Click Edit Items in the right-side Actions area.
Result: The Collection Editor dialog is opened.
8. Create the following server variables via the Add button:
o HTTP_X_FORWARDED_PROTO
o HTTP_X_FORWARDED_HOST
9. When you are finished, click Apply in the right-side Actions area of main window.

6. Validating the Server Connection

You can ensure the server connection is working as expected by doing the following steps:

1. Open a browser of your choice.

2. Open the following address to verify that the application server can be reached:
http://<application server address>:<application server port>
3. For example: http://localhost:7767

Note: In a proxy–application server model, complete this step on the application server machine.

Page 16 of 22 M-Files Corporation | www.m-files.com | [email protected]

 4. If you are using a proxy–application server model, test the connection to the application server machine in a browser
of your choice by opening the following address on the proxy machine:
http://<application server IP or DNS address>:<application server port>
For example: http://10.1.2.123:7767
5. To verify that the public URL of the backend server can be accessed, either:
a) Open the following address if you have set up vNext as a new site (section 4.1):
http(s)://<your domain>
For example: https://mycompany.com
b) Open the following address if you have configured vNext under the current web client (section 4.2):
http(s)://<your domain>/<your subsite alias>
For example: https://mycompany.com/vnext
The subsite alias is defined in step 5 of section 4.2.

7. Optional: Setting Up OAuth 2.0

To set up OAuth 2.0 based authentication for M-Files Web or the add-ins, refer to Setting Up OAuth 2.0 for the New M-Files
Web and Web-Based Add-Ins.

8. Optional: Defining Settings for Cross-Origin Resource Sharing

If you are setting up the vNext backend for M-Files add-ins such as M-Files Add-In for Teams and SharePoint Online and
M-Files Add-In for Salesforce CRM, and you are using M-Files March '20 Update or later, please see the separate installation
instructions for the add-in. If you are using M-Files February '20 Update or earlier, please see the section Settings for Cross-
Origin Resource Sharing before installing the add-in.

9. Change History

The table below describes the essential changes by document version.

VERSION DATE ESSENTIAL CHANGES

1.0 2019/03/28 Initial version.

1.1 2019/04/12 Added a note about the M-Files Online requirement to the introduction.

1.2 2019/04/17 Updated step 7 under section 4 as well as the version requirement in section 2.1.

1.3 2019/05/23 M-Files Server requirement updated. Section 4 divided into two separate scenarios. Download links
added to sections 3.1 and 3.2. Added detailed instructions for creating an inbound rule.

1.4 2019/06/07 Added the troubleshooting section and a note about port changes in M-Files June '19 Update.

1.5 2019/07/26 Updated the default port value in Appendix A.

1.6 2019/08/26 Updated the Appendix B with troubleshooting content.

1.7 2019/09/16 Added the authentication configuration section 3.4 and referred this in section 3.3.1. and in 3.3.2.

1.8 2019/10/14 Added notes in section 4.2 and Appendix A: Additional Settings.

Page 17 of 22 M-Files Corporation | www.m-files.com | [email protected]

 1.9 2019/11/15 Changed the references to M-Files versions.

2.0 2020/01/08 Updates to Appendix A and Appendix B. Added a table of contents.

2.1 2020/01/14 Updated section 5, vNext.config and PowerShell scripts for configuring Allowed Server Variables.

2.2 2020/01/23 Updates to sections 3.2 and 4.

2.3 2020/02/26 The documentation now uses a more suitable template. Multiple changes throughout the document.
Instructions for validating the server setup added.

2.4 2020/03/09 Updated sections 4.1, 4.2, Appendix A and Appendix B. Added section 7. Added a note to the
prerequisites section.

2.5 2020/04/06 Added notes to section 4 and Appendix B.

2.6 2020/05/07 Added a design diagram for the proxy-app model to section 4. Updated section 6, Appendix A and
Appendix B.

2.7 2020/08/19 Screenshot updated in section 4.1.

2.8 2020/10/16 The key of the GRPCWEBPORT setting was updated.

2.9 2020/12/08 Review of the entire document.

3.0 2020/12/15 The document now has a section for setting up OAuth 2.0 authentication.

3.1 2021/12/22 Added the requirement for the IIS feature WebSocket Protocol to section 2.1.

3.2 2022/07/01 Information about traffic filtering added to Appendix A.

3.3 2022/10/17 The new M-Files Web can now be set up with M-Files Admin. Updated the start of the document.

3.4 2022/11/17 Updated section 1.

10. Reference Documents

You may want to see these articles for additional information:

• IIS 8 and IIS 8.5: Create CSR and Install SSL Certificate (Digicert article)
• URL Rewrite (IIS.NET article)
• Application Request Routing (IIS.NET article)

Page 18 of 22 M-Files Corporation | www.m-files.com | [email protected]

Appendix A: Additional Settings

This section lists additional, optional registry settings for M-Files vNext configurations.

Note: If you are using a proxy–app server model, configure the registry settings listed in this section on the app
server machine.

Settings for Cross-Origin Resource Sharing

If you are using M-Files February '20 Update or earlier, the settings listed here need to be set for M-Files add-ins (like M-Files
Add-In for Teams and SharePoint Online and M-Files Add-In for Salesforce CRM) to work as required.

The cross-origin resource sharing (CORS) settings define domains that can be accessed from M-Files add-in. They are added
under the following key:

Key HKEY_LOCAL_MACHINE\SOFTWARE\Motive\M-Files\<version>\Server\MFServer\Http\AccessControl

Value name CrossOriginAccess

Value type REG_SZ

Description The allowed cross-origin domain URLs for the host application. Separate multiple values with a comma and
do not add a whitespace after the comma (see the value definition below). Do not add slash to the end of
the URL.

Note: The Teams integration uses the SharePoint web part, which is why the Teams domain
does not need to be listed in this setting.

Value For example:

https://mycompany.lightning.force.com,https://mycompany.sharepoint.com

Value name AllowedCrossFrameSites

Value type REG_SZ

Description The allowed cross-frame domains URLs for the host application when the PreventXFS setting is set to
true. Separate multiple values with a comma and do not add a whitespace after the comma (see the
value definition below).

Specify the URLs of your M-Files vNext server and SharePoint domain. Add the Teams domain as well to
use the Teams integration for cross-frame access. Do not add a subdirectory name (for example /vnext)
or a slash to the end of the URL.

Value For example:

https://cloudvault.mycompany.com,https://mycompany.lightning.force.com,https://mycompa
ny.lightning.force.com,https://mycompany.sharepoint.com,https://teams.microsoft.com

Page 19 of 22 M-Files Corporation | www.m-files.com | [email protected]

In the settings listed below, modify the suggested default values only if you have specific reason to do so.

Value name PreventXFS

Value type REG_SZ

Description Specifies whether to prevent access from cross-frame sites. If this is set to "false", there is no need to set
the AllowedCrossFrameSites setting, either. Only set this to "false" if you have specific reason to do
so.

Value true

Allowed • true
values • false

Value name AllowedMethods

Value type REG_SZ

Description The methods that need to be allowed in the response headers. Separate multiple values with a comma (,)
and do not add a whitespace after it (see the value definition below).

Value GET,OPTIONS,POST

Value name AllowedHeaders

Value type REG_SZ

Description The headers that need to be allowed in the response. Separate multiple values with a comma and do not
add a whitespace after it (see the value definition below).

Value Origin,X-Requested-With,Content-Type,Accept,M-Files-Vault,m-files-session,m-
files-extensions

Value name AllowCredentials

Value type REG_SZ

Description Indicates whether the user agent should send cookies from the other domain in the case of cross-origin
requests. This setting is required for embedded apps like M-Files Add-In for Teams and SharePoint Online
to be able to pass cookies for server requests.

Value true

Allowed • true
values • false

Page 20 of 22 M-Files Corporation | www.m-files.com | [email protected]

M-Files Web Specific Settings

Key HKEY_LOCAL_MACHINE\SOFTWARE\Motive\M-Files\<version>\Server\MFServer

Value name GRPCWEBPORT

Value type REG_DWORD

Description Make sure the server firewall allows inbound connections to the specified port. If the default port is
allocated to another service in your environment, you can change the port via this setting.

Default value 7767

Note: If you are defining the setting in Registry Editor, save the value with decimal base.

Note: If you have modified the setting to something else than 7767, use this port number when
configuring the vNext Backend server.

M-Files Server Firewall

To make your server more secure, filter HTTP traffic to the M-Files server machine that comes in through the gRPC port
specified with the GRPCWEBPORT registry key. For example, only let in traffic from the same machine if the IIS server is on the
same computer as the M-Files server, or from a specific IIS server if it runs on another machine.

Page 21 of 22 M-Files Corporation | www.m-files.com | [email protected]

Appendix B: Troubleshooting

vNext Backend Server Not Working After Updating M -Files Server to March '20 Update

Important: In on-premises environments where each vault has not been designated a VaultDNS value under
HKEY_LOCAL_MACHINE\SOFTWARE\Motive\M-Files\<version>\Server\Common\VaultDNSConfig, please first
upgrade to M-Files April '20 Update and then follow the instructions indicated below.

Your vNext deployment may stop working after your M-Files Server is updated to M-Files March '20 Update. If you
encounter this issue:

• In a script-based environment setup, run the ConfigurevNextServerUndervCurrent.ps1 script that is part

of the same multi-file document as this guide.
• In a configuration file-based environment setup, update your vNext.config file with the updated file that is part
of the same multi-file document as this guide and update your environment with instructions in section 5.
• In a manual setup, update your environment with instructions in sections 4.1 or 4.2, as well as in section 5.

Note: Once you have upgraded your environment successfully, remove the following CORS setting from the
Windows registry of the application server:
HKEY_LOCAL_MACHINE\SOFTWARE\Motive\M-Files\<version>\Server\MFServer\Http\AccessControl

In a multi-tenant environment, ensure that each vault contains their own configuration values (URLs configured)
in M-Files Admin under Configurations > Advanced Vault Settings > M-Files Add-In Settings.

Note: You can use the updated script with earlier M-Files Server versions as well.

vNext Backend Server Not Working After Updating M -Files Server to January '20 Update

Your vNext deployment may stop working after your M-Files Server is updated to M-Files January '20 Update. If you
encounter this issue, run the ConfigurevNextServerUndervCurrent.ps1 script that is part of the same multi-file document as
this guide. This updated version of the script fixes an issue related to the location of the M-Files installation directory.

Note: You can use the updated script with earlier M-Files Server versions as well

Page 22 of 22 M-Files Corporation | www.m-files.com | [email protected]