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)
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.
Example:
server.domain.samlsso.config.path=$CATALINA_HOME/conf/meshiq-samlsso.xml