Preparations

Installation
The following steps must be performed before installing Intrexx 19.03 or when updating an older version of Intrexx to ensure that Intrexx 19.03 functions optimally.

1. Web server configuration

Every Intrexx portal needs to be accessible via HTTP, or rather every productive portal needs to be encrypted and accessible via HTTPS. For this reason, a web connector (an embedded Apache Tomcat) runs in every portal instance that provides the HTTP interface. There are different options for providing a portal available with HTTP(S). Multiple portals can be operated with the same protocol, host name and port but a different path or virtual directory, such as:

https://host.example.org/portal1/
https://host.example.org/portal2/

This option is prone to errors and raises security issues. It is therefore not recommended.

Depending on the operating system and user account, which the portal service is operated with, the portal's web connector can use the HTTP default port (443, unencrypted 80). By default, Intrexx suggests non-privileged ports (> 1024).

1.1. Standalone

Standalone means that clients connect to the portal directly via the portal's web connector. To run multiple standalone portals on one server, there are various configuration options available: An additional IP address is configured on the operating system, the assignment of the host name via DNS (A or AAAA record).

1.2. Portal with an upstream reverse proxy or load balancer

Nginx, Microsoft IIS with ARR, HAProxy, Apache Traffic Server, or similar, come into question as an upstream proxy. With an upstream front-end, any number of portals can be hosted virtually (with the standard port). The server only requires an IP address as well as an A, AAAA or CNAME record in the DMS for each virtual host, such as

https://portal1.example.org/
https://portal2.example.org/

2. Embedded Tomcat

Tomcat is included in the portal service in Intrexx Version 18.09 or higher and is automatically started when the portal service is started. Typically, you can access your portal in the browser via the base URL https://localhost:1337. Each portal has its own Tomcat configuration. An upstream web server is not absolutely necessary.

3. Intrexx on Microsoft Server 2016 / 2012 / Integrated authentication

If you want to use integrated Windows authentication or Kerberos authentication on a server that operates multiple portals, the Microsoft Internet Information Server needs to be implemented as a reverse proxy. This is the only way to implement the required authentication. The following guide shows you how you can operate multiple portals on one server while continuing to use integrated authentication.

3.1. Install ASP.Net

To install ASP.Net / ARR, please activate Windows Features / Internet Information Services / World Wide Web Services / Application Development Features / ASP.NET 4.5 (or higher) before creating a portal. Apply all suggested additional features such as ISAPI Extensions, ISAPI Filters and the .NET Extensibility. Please proceed as follows:



Open the server manager and click on the "Manage" menu item. From there, select "Add Roles and Features".



In the following dialog, select "Role-based or feature-based installation".



Select your server.



Select the role "Web Server (IIS)".



As an option, you can now install the IIS Administration Console (recommended).



Confirm the following dialog by clicking on Next, without selecting any features.



Confirm this dialog with Next.



Select the Role services as shown in the image.



Complete the installation.

3.2. Install the ARR module

Click here to download the IIS Web Platform Installer (WebPI 5.0 or higher) and execute the installation.



Once the installation is completed, start the Internet Information Services Manager. Select your server and start the Web Platform Installer that is now available in the administration.



Search for "routing" and install the module "Application Request Routing 3.0".

Please make sure not to install the older version (2.5).




3.3. Activate reverse proxy




Select "Application Request Routing" at the server level in the IIS Manager.



On the right-hand side, select "Server Proxy Settings".



Activate the setting "Enable proxy". In addition, the option "Reverse rewrite host in response headers" needs to be deactivated. Otherwise the Intrexx OAuth2 SSO redirect will no longer work because the IIS automatically writes the IIS host name in the location header instead of the external host. Save the changes by clicking on "Apply" on the right.

3.4. Install portal with IIS support

If the internal Tomcat is set to port 1337 (default for new installations), the portal should be accessible in the browser as usual after the portal installation with IIS support. The Internet Information Server can be selected as the front-end web server at a later point in the portal properties.

3.5. Automatic transfer during update

During an update, the Windows authentication is automatically activated or transferred if the portal was already run with Windows authentication. In this case, the Service Principal Names for the Connectors are automatically transferred.

3.6. Settings for file uploads and downloads

Open the Server Manager and select the menu item "Internet Information Services (IIS) Manager" from the Tools menu.



Limits for the file size of uploads and downloads are defined in "Request Filtering".



Click on "Edit Feature Settings" on the right-hand side.



By default, the IIS can process files that are up to 28.6 MB in size. If you want to be able to process larger files, such as when uploading files to the portal, the "Maximum allowed content length" needs to be adjusted. The value of 2147483646 (bytes) corresponds to about 2 GB and is the maximum value for the IIS.

3.7. Opening the portal in the browser

If documents cannot be downloaded or uploaded regardless of their size, please check the permissions. The user or the IIS may not have the permissions required for the directories. This subject is also handled in the respective installation guides. The permissions should therefore already be defined. Directories: If you are using Intrexx Authentication, the following users/groups need write access to these directories:

3.8. Authorization structure

If you are using Integrated Authentication (Windows Authentication / SSO), the user currently logged in in the web requires write access to the portal directory internal/uploadfiles (i.e. via the domain users group).

3.9. Configuring IIS for using HTTPS

Create and bind a new certificate




In the IIS, select the server and then select "Server Certificates".



Here, click on "Create Self-Signed Certificate".



Enter the friendly name and then click on "OK".

Create binding

Under "Default Web Site", create a new binding.



Assign the certificate by clicking on "Add". Select "https" as the type. Enter the other details accordingly and select the certificate by clicking on "Select". The binding is created when you click on "OK". If you want to completely remove the option of connecting via normal HTTP, you need to remove it here.

Base-URL for the Intrexx portal

The Base-URL for the portal needs to be adjusted in the Portal properties in the portal manager. If you are using an official certificate, this must also be stored in the Manager's Certificate Store, as this is required for providing web services, for example.

3.10. Troubleshooting

It is not always the case that a completely trouble-free installation of the Internet Information Server connector is guaranteed. The following provides a description of the most common causes of error and potential solutions.

3.10.1. Switch portal to Windows authentication after installing Intrexx without IIS support

Because the manual integration of the IIS connector is very complex and prone to errors, we recommend the following approach:
  1. Export the existing portal
  2. Install ASP.Net and the ARR module
  3. Remove the previous installation
  4. Reinstall with IIS support (automatically preselected)
  5. Import the portal
  6. Switch the authentication

3.10.2. Port is already in use

Check the port allocation. A portal can only be accessed when it is accessible via the default port 443 (for HTTPS). When setting up the ARR module in the IIS, this connection is defined accordingly. If this port is already in use from a different software product or set-up website, then a connection to the portal is not possible. To check whether another product is using the port, proceed as follows:
  1. Open the command line.
  2. Enter the command
    c:\> netstat –anop tcp
  3. If you receive an entry in the format
    Local Address: "0.0.0.0:443"  State:"LISTENING"
    then you know that the port is already in use. To find out which program is using this port, you need to search for the process with a suitable tool (e.g. Process Explorer from Sysinternals). This process is stated in the PID column in the results of the netstat command.

3.10.3. Incorrectly configured application pool for the virtual website

In the IIS Manager, check the used application pool for your portal. Proceed as follows:
  1. Open the IIS Manager
  2. Open the entry "Default Website" in the tree
  3. Right click on the entry for your portal and select "Manage Application / Advanced Settings"



    Note the name of the defined application pool (e.g. "DefaultAppPool" in this case)
  4. Open the "Application Pools" node in the tree

  5. Check the following settings:
    • .Net CLR Version: At least version "v4.0" should be defined here.
    • Managed Pipeline Mode: The option "integrated" should be defined here.

3.10.4. Windows authentication: Tomcat filter not yet activated

To use Windows authentication in the portal as well as for Single Sign On for the connectors, a filter must be activated in the web.xml file. This can be found in the portal directory external/htmlroot/WEB-INF. This filter is usually activated automatically as soon as Windows authentication has been activated.
  1. Open the file with a suitable editor (e.g. Notepad++)
  2. Search for the term "External Authentication Filter".
    <filter-name>External Authentication Filter</filter-name>
            <filter-class>de.uplanet.lucy.server.connector.servlet.ExternalAuthenticationFilter</filter-class>
            <init-param>
                <description>
                    This property is used to enable or disable the filter.
                    IMPORTANT: For compatibility reasons the default value of this property
                    is true for the External Authentication Filter.
                    Values: true (default) or false.
                </description>
                <param-name>enabled</param-name>
                <param-value>false</param-value> 
            </init-param>
    		
  3. Modify the line
    <param-value>false</param-value>
    to
    <param-value>true</param-value>
  4. Save the file.
  5. Restart the portal service.

3.10.5. Kerberos authentication for connectors: Tomcat filter not yet activated

When using connectors with the Kerberos authentication, an additional filter is required that in some cases needs to be added to the web.xml file manually like in the step above:
  1. Open the file with a suitable editor (e.g. Notepad++)
  2. Search for the term "connector.portalserver.additionalHeaders"
    <init-param>
    	<param-name>connector.portalserver.additionalHeaders</param-name>
    	<param-value>X-Header-1 X-Header-2</param-value>
    </init-param>
  3. Copy the entire entry into the subsequent, not-commented-out area. Edit the entry as follows:
    <init-param>
    	<param-name>connector.portalserver.additionalHeaders</param-name>
    	<param-value>X-AccountName X-KrbTicket</param-value>
    </init-param>
  4. Remove the characters "--" at </filter-mapping-->
  5. Save the file.
  6. Restart the portal service.

4. Portals with NGINX

If you want to operate Intrexx portals with NGINX as the reverse proxy, a virtual host name needs to be configured for each portal. Click here for more information.



Configuration files for NGINX can be generated in the portal properties via the front-end web server setting "Write configuration to file". These generated files should be seen as templates / suggestions. The created file is similar to the templates available in the installation directory samples/web-tls-configuration/nginx, but the values that are known from the installation dialog are already filled in. Normally, the administrator will need to adjust the file (i.e. paths to SSL certificates or encryption and other parameters that need to be optimized) before they can deploy it in the system. To make this easier, the file contains corresponding comments with links to the relevant NGINX documentation. Once the configuration is completed, it is deployed and tested in NGINX by the administrator.