Background

Users that access the INTERGATOR web-interface directly are authenticated by intergator either using single-sign-on (SSO) or username and password.

When INTERGATOR is integrated into Confluence, users are already authenticated by Confluence. The Confluence Plugin then sends search requests to INTERGATOR on behalf of the user and visualizes the results.

In this scenario Confluence is located in between the user and intergaor but it does not have the user credentials (like password or SSO information) to authenticate the user with INTERGATOR.

For such use cases there is an INTERGATOR authentication mode called PreAuth. When this mode is configured, INTERGATOR relies on the upstream compunent (e.g. Confluence) to authenticate the user. The upstream application then sends the username to INTERGATOR in an HTTP header (typicallly X-User) or cookie and INTERGATOR accepts it without further checking.

Security considerations

Without PreAuth, all INTERGATOR APIs require authentication. With PreAuth mode enabled all INTERGATOR APIs have to support this mode. That means that any user that can talk to these APIs can impersonate any other user and e.g. donwnload documents from connected data sources.

To prevent this you have to make sure that only legitimate users and machines can access the INTERGATOR server and API proxy API. This can be done e.g. by a local firewall on the INTERGATOR machine(s) or by putting INTERGATOR into a separate network with restricted access.

The INTERGATOR webinterface can be configured in a way that only a dedicated IP address can use PreAuth mode. Requests from all other IP addresses have to be authenticated with username and password or SSO.

PreAuth configuration

PreAuth mode has to be enabled in the INTERGATOR server and the web-interface. The API proxy just passes it through.

This article assumes that your INTERGATOR is already connected to a Microsoft Active Direcory.

INTERGATOR server configuration

The server allows to configure a list of authentication providers. When a user logs in all authentication providers are invoked sequentially until the user is authenticated. Now we configure the PreAuth povider before the existing Active Directory provider.

Open the INTERGATOR Management Center and go to XML mode → Server Sicherheitskonfiguration

Inside the <providers> XML element you find an <item> with a <factoryId>active-directory-auth-provider-factory</factoryId> inside. This configures your Active Directory connection. Keep this! Do not change it!

Put the following <item>-element and descendants directly before the item of your Active Directory item:

PreAuth provider snippet to insert

<item>
  <factoryId>pre-auth-auth-factory</factoryId>
  <properties>
    <item>
      <key>principalType</key>
      <value>user-principal-name</value>
    </item>
  </properties>
</item>

The result should be similar to this:

Server Sicherheitskonfiguration (server security configuration)

<configuration xsi:type="serverSecuritySettings" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <label>Server-Sicherheitskonfiguration</label>
    <customAuthChain>
        <providers>
            <item>
                <factoryId>pre-auth-auth-factory</factoryId>
                <properties>
                    <item>
                        <key>principalType</key>
                        <value>user-principal-name</value>
                    </item>
                </properties>
            </item>
            <item>
                <factoryId>active-directory-auth-provider-factory</factoryId>
                <properties>
                    <item>
                        <key>java.naming.security.principal</key>
                        <value>aUser@yourDomain</value>
                    </item>
                    <item>
                        <key>java.naming.security.credentials</key>
                        <value>...some_encrypted_password...</value>
                    </item>
                    <!-- further item-elements can follow, this is environment specific -->
                </properties>
            </item>
        </providers>
... 
<!-- don't touch the resolver -->

That's all for the server side - no restart needed. Check if normal authentication via AD still works and make sure the INTERGATOR server and API proxy API can not be accesed by unauthorized users (see Security considerations above).

Web-interface configuration

Add PREAUTH properties

Create a file web-interface/intergator/WEB-INF/properties/intergator.confluence-preauth.properties with the following content:

intergator.auth.modes.default=PREAUTH
intergator.auth.modes.default.embedded=PREAUTH
intergator.auth.trusted.header=X-PREAUTH-301238

Restrict access to specific hosts

Edit web-interface/intergator/WEB-INF/intergator.xconf and add a similar match rule:

Replace the IP address in the fixed-string-attribute with the IP of your Confluence server

<intergator xml:space="preserve">
	<properties name="ig-properties">
	
	...

		<!-- Allow PREAUTH only from specific host -->
		<match>
			<match fixed-string="192.0.2.0" value="{request:remote-addr}">
				<url expand="static" optional="true" path="/WEB-INF/properties/intergator.confluence-preauth.properties" />
			</match>
		</match>

    ....

Restart the INTERGATOR web-interface

This depends on the operating system. It is necessary to load the new configuration.

Add a custom authentication resolver

The custom resolver is only needed if your intergator is not connected to an Active Directory.

Create file server/lib/groovy/de/ifbus/intergator/authsystems/custom/ConfluencePreauthResolver.groovy with the following content:

/*
 * Copyright (c) 2020 interface projects GmbH
 *  All rights reserved. This code is property of interface projects GmbH.
 *  Modification and/or further distribution without permission of
 *  interface projects GmbH is prohibited.
 */
package de.ifbus.intergator.authsystems.custom;

import de.ifbus.intergator.core.security.NoSuchPrincipalException
import de.ifbus.intergator.core.security.ScAuthResolver
import de.ifbus.intergator.core.security.ScId
import de.ifbus.intergator.core.security.ScPrincipal
import de.ifbus.intergator.core.security.ScPrincipalBuilder
import de.ifbus.intergator.core.security.ScPrincipalType
import de.ifbus.intergator.core.security.ScQualifier

import java.util.logging.Level
import java.util.logging.Logger

class ConfluencePreauthResolver implements ScAuthResolver {
    private static final Logger log = Logger.getLogger(MyAuthResolver.class.getName())

    private static final String DIRECTORY = "customexampledirectory"
    private static final String IDTYPE_ID = "user"

    MyAuthResolver() { log.log(Level.FINE, "MyAuthResolver instantiated") }

    List<ScPrincipal> resolve(ScId securityId) throws Exception, NoSuchPrincipalException {
        log.log(Level.FINE, "MyAuthResolver resolving $securityId")

        // anonymous logon
        if (securityId == null) {
            List<ScPrincipal> principals = new ArrayList<>(); return principals
        }

        // get userPrincipalName from SecId [value=user@example.com, qualifiers=[userprincipal-name]]
        String userPrincipalName = securityId.getValue()

        List<ScPrincipal> principals = new ArrayList<>()

        // Add the user name princpial
        principals.add(createUserPrincipal(userPrincipalName))

        log.log(Level.FINE, "ConfluencePreauthResolver resolved $securityId to $principals")

        return principals
    }

    // custom code that creates the user principal
    ScPrincipal createUserPrincipal(String userPrincipalName) {        // the unique user identifier
        String id = userPrincipalName
        return new ScPrincipalBuilder()
                .setType(ScPrincipalType.USER)
                .setDirectory(DIRECTORY)
                .setSystemId(DIRECTORY + ":" + IDTYPE_ID + ":" + id)  //restart server on change
                .setDisplayName(userPrincipalName != null ? userPrincipalName : id)
                .addId(userPrincipalName, ScQualifier.USERNAME)
                .addId(userPrincipalName, ScQualifier.DISPLAY_NAME).build()
    }
}