Skip to content

MAS Proxy

With the switch to MAS, it is no longer possible to use the MAS Manage application inside an iframe. CORS settings for MAS Manage and the authentication flow block this use case. To work around this, we provide a proxy that must run alongside Insight.

The MAS Proxy is an NGINX HTTP server configured to proxy the MAS Manage application under a different domain/hostname so it can be embedded in the Insight Control Panel through an iframe. The proxy handles headers, cookies, and content before they are sent to the browser.

This concept is documented by IBM here.

Our configuration only allows access to hostnames listed in Hostname Mapping.

Hostname Mapping (Single Source of Truth)

Use placeholders in all examples:

  • <instance> (for example masdev)
  • Insight base domain: insight.app.company.tld
  • MAS base domain: mas.app.company.tld
Purpose Proxy hostname (used by browser/Insight) Upstream MAS hostname (behind proxy)
MAS Manage UI <instance>.manage.insight.app.company.tld <instance>.manage.mas.app.company.tld
MAS API api.insight.app.company.tld api.mas.app.company.tld
MAS Auth/OIDC auth.insight.app.company.tld auth.mas.app.company.tld

All DNS entries, TLS certificates, and ingress routes must exist for the proxy hostnames.

Goal

The goal is to make the MAS Manage application available under the same domain as the Insight application.

Example

All further documentation is based on this example.

  • Domain/Hostname used for Insight: insight.app.company.tld

  • Domain/Hostname used for MAS Manage: masdev.manage.mas.app.company.tld

  • Proxy must be:

    • masdev.manage.insight.app.company.tld -> masdev.manage.mas.app.company.tld

Example .yaml-file with deployment, service and ingress here.

Example Image

Configuration

Pod/Container

Image: rodias.azurecr.io/mas-proxy:latest

ENV Required Description
MAS_DOMAIN ✅ the basic domain/hostname of the MAS environment (1)
MAS_INSTANCE ✅ the instance name of your manage application (2)
PROXY_DOMAIN ✅ the basic domain/hostname of your Insight environment (3)
DNS entries and valid certificates for the following domain/hostnames:

Create DNS entries and valid certificates for all proxy hostnames listed in Hostname Mapping.

Routes for the following hostnames pointing to the mas-proxy service-port

See example here.

Configure ingress routes for all proxy hostnames listed in Hostname Mapping so they point to the mas-proxy service port.

insight.properties (oidc.server)

When using the MAS proxy, oidc.server must point to the auth endpoint exposed by the MAS proxy (for example https://auth.<proxy-domain>/...), not to the original auth server behind the proxy.

If oidc.server points to the backend auth server, cookie domains do not match and authentication/session cookies are not sent correctly.

Example:

# Correct (MAS Proxy endpoint)
oidc.server=https://auth.insight.app.company.tld/<oidc-path>

# Wrong (backend auth server behind MAS Proxy)
oidc.server=https://auth.mas.app.company.tld/<oidc-path>

Tests

  • Open https://masdev.manage.insight.app.company.tld/maximo/ in your browser.
    • You should be redirected to https://auth.insight.app.company.tld.
  • Log in with your MAS credentials.
    • After successful login, you should be redirected back to https://masdev.manage.insight.app.company.tld/maximo/ and the MAS Manage UI should load.

Client Configuration

When the MAS Proxy is configured and tested, continue by configuring config.json:

{
  "maximoUi": "https://<instance>.manage.insight.app.company.tld/maximo",
}