Setting Up the Common Login Page (OIDC Gateway) for meshIQ GUI Applications – meshIQ

The content described in this article is available in meshIQ platform versions 12.1 and later.
For a quick overview of what's new or changed, visit the meshIQ Highlights page for a version-by-version breakdown.

The Common Login Page, also referred to as the Gateway, centralizes authentication for all GUI applications using OIDC (OpenID Connect). Applications redirect to the Gateway for login, simplifying user authentication and enforcing consistent security policies across the platform.

Gateway Configuration

The following parameters must be configured on the Gateway application to enable proper authentication and application-switching behavior:

gateway.external.url:
The external URL of the login Gateway, used by applications for redirection during authentication.
Example:
Important: Use a valid hostname or IP instead of "localhost" to enable external access.
```
gateway.external.url=https://localhost:8080/gateway
```
domain.auth.api.url:
The base URL of the domain authentication API. This API implements domain-specific authentication logic and handles token exchange via OIDC.
Example:
```
domain.auth.api.url=https://localhost:8018/auth/v2
```
appswitcher.manager.config:
Configuration for the application switcher manager, which allows users to switch between GUI applications post-login.
Example:
```
appswitcher.manager.config=$CATALINA_HOME/conf/appswitcher.xml
```

How to Set Parameters

You can configure the parameters in one of the following ways, depending on your deployment approach:

Option 1: `context.xml` (Using `<Parameter>`)

Tomcat allows you to set application-specific parameters in context.xml using the <Parameter> element. This helps separate configuration from application code.

Location:

$CATALINA_HOME/conf/context.xml

Example:

<Parameter name="gateway.external.url" value="https://localhost:8080"/>
<Parameter name="domain.auth.api.url" value="https://localhost:8018/auth/v2"/>
<Parameter name="appswitcher.manager.config" value="$CATALINA_HOME/conf/appswitcher.xml"/>

Option 2: Environment Variables (`CATALINA_OPTS`)

Set parameters as system properties by exporting them with CATALINA_OPTS before starting Tomcat:

export CATALINA_OPTS="$CATALINA_OPTS -Dgateway.external.url=https://localhost:8080"
export CATALINA_OPTS="$CATALINA_OPTS -Ddomain.auth.api.url=https://localhost:8018/auth/v2"
export CATALINA_OPTS="$CATALINA_OPTS -Dappswitcher.manager.config=$CATALINA_HOME/conf/appswitcher.xml"

Option 3: Java Command-Line Options

If launching the application manually or embedding it, you can pass parameters directly to the JVM:

-Dgateway.external.url=https://localhost:8080
-Ddomain.auth.api.url=https://localhost:8018/auth/v2
-Dappswitcher.manager.config=$CATALINA_HOME/conf/appswitcher.xml

Configuring GUI Applications for Login via Gateway

All GUI applications that delegate login to the Gateway must follow these configuration guidelines:

Remove App Switcher Configuration

Why: The App Switcher is centrally managed by the Gateway.
Action: Ensure the following property is not set in the application’s configuration:
```
appswitcher.manager.config
```

Remove SSO Configuration

Why: In versions 10.x and 11.x, each application managed its own SSO configuration. With the introduction of centralized authentication via the Gateway, local SSO settings are no longer needed and may cause conflicts.

Action: Ensure the following properties are not set in the application’s configuration:

samlsso.manager.config
wsm.samlsso.manager.config
track.samlsso.manager.config
apwmq.samlsso.manager.config

Set the Gateway URL Property

Why: Each GUI application must know where to route authentication requests.
Action: Set the following property in the application’s configuration:
```
meshiq.gateway.api.url = https://localhost:8080/gateway/api/v1/
```

Refer to the section How to Set Parameters for options on how to apply this setting.

After configuration, the Gateway login page may resemble the image below; the actual appearance may vary.

To learn how to sign in, see Log in to meshIQ GUI applications. After you log in, you can switch between meshIQ GUI applications. For instructions, see App Switcher.

SSO Configuration (Optional)

In addition to OIDC, the Gateway can also support SAML-based Single Sign-On (SSO). To enable this, the following system property must be set for the domain:

server.domain.samlsso.config.path

This property specifies the file path to the SAML SSO configuration for the domain. The configuration file defines the Identity Provider (IdP), Service Provider (SP) metadata, and other SAML-specific settings.