Portal configuration with multiple domains

[]

A complete overview of the available configuration options and instructions on how to perform the configuration can be found here. Below you will find general considerations about the current setup.

The application, as seen from the user perspective, is called a "portal". In the released code, there is exactly one such out-of-the-box "portal", and effectively there is no difference between "portal" and "application".

A setup with multiple portals - where a portal is not equal to the application - is not recommended and officially unsupported. "Multiple portals" would mean multiple web UIs with isolated functionalities but a shared infrastructure, e.g., users and other data.

Portal and domain(s)

It is further recommended that this one application - the portal - runs on a single portalDomain, i.e. there is one DNS hostname used as a base URL.

It is, however, possible (and supported) to have multiple domains for the same portal. This is useful for:

• aliases
• local development
• demo systems with dynamic hostnames

Security consideration for using multiple domains

Multiple domains are possible, but only with disabled or compromised security settings. For that reason, real production deployment should not use this option.

Apart from this, to avoid CORS problems and to share cookies, the HCMS is also expected to run on the same domain. This opens a potential attack vector called "Host Header Injection". It is crucial that when the multi-domain setup is allowed, the infrastructure (reverse proxy / balancer) correctly prevents such attacks!

Also, to be on the safe side, only the main official domain is allowed by default. Other domains must be allowed by a boolean property acceptAllDomains in the configuration, or by an environment variable ONLY_ONE_DOMAIN.

Multi-domain setup implementation

General notes

Having more than one domain is always a challenge.

The reason is that a portal can only have one configuration set. This configuration contains several absolute links that must use the proper domain to properly share cookies and to avoid CORS problems. As a consequence, this configuration cannot be directly used in a multi-domain setup.

As a solution, before the configuration is served to the frontend via /data/config.json, it must be patched. This is done in the following way:

• The InstanceManager class in the <code>InstanceManager.ts</code> script keeps all these patched configurations cached in memory, together with all the HTTP handlers.

• The lookup function is provided as a preparePortalForDomain lambda in the <code>ExpressAdapter.ts</code> script. This function calls injectClientModules, which handles the patching. It also does its own patching if the request domain is not the same as the official domain. This can be disabled using the environment variable ALL_DOMAINS_EQUAL if the correct CORS headers and cookie flags are guaranteed to be present.

Local middleware development

There is also a special support for the local middleware development.

When the request domain is not the same as the configured one and the application is not running inside docker (meaning that RUNNING_INSIDE_DOCKER is not set), some of the most important backend URLs (authApiUrl, managementApiUrl, middlewareUrl) are set to domain and protocol from the request. It is also possible to allow this behavior inside the docker container by setting the environment variable DYNAMIC_MIDDLEWARE_ENDPOINTS, but such a thing is rarely needed.

Warning using http protocol breaks some areas of the frontend/backend integration and there is no way around this in modern browsers. For a fully functional application, https is necessary.