How the Security Portal Works#

The Critical Manufacturing Security Portal is the identity management system of Critical Manufacturing MES and its installed applications. It authenticates users against one or more authentication sources and issues the tokens that client applications use to access MES services.

This page describes:

• How tenants and OAuth clients define security boundaries.
• The authentication flows that client applications use to obtain tokens.
• How access tokens carry OAuth Roles that control application access.
• How HTTP and Message Bus requests validate tokens.
• How the Security Portal connects to authentication sources through strategies.

Tenants and OAuth Clients#

A tenant is an authentication and authorization boundary in the Security Portal. It groups the authentication strategies, user source, enrollment rules, and OAuth clients that belong to one security context. Every token issued by a tenant identifies that tenant, and the MES runtime services use it to scope authorization and Message Bus sessions.

• Base tenant - the tenant configured for the MES deployment, typically named MES. It always exists, provides the MES sign-in experience with its configured strategies and user source, and holds the OAuth clients used by MES, including a client registration for each installed application.
• Application tenant - a tenant generated automatically for each installed application. It contains an OpenID Connect strategy that delegates authentication to the base tenant, an OAuth client for the application, and signing keys and redirect URIs specific to the application. It gives the application its own identity and token context while reusing the sign-in experience of the base tenant. Enrollment is enabled in the application tenant, so a user is enrolled in the application on the first sign-in.

An application (app) is a package that extends Critical Manufacturing MES with additional features and integrations. Installed applications are listed in the Apps page. For the available applications, see the Critical Manufacturing Apps ↗ catalog.

An OAuth client is an application or service registration within a tenant. It defines the scopes that a token can request and the scopes always included in the token.

Scopes#

A scope is a permission included in a token. Components and routes can require specific scopes. The Security Portal includes a scope in the token only when its condition is met:

Table: Scope types

Tenants are provided by an ordered list of tenant stores in config.json. The administrator configures the base tenant and its clients, while application tenants are derived from the applications registered in the MES database. For details, see Tenant Stores.

Authentication Flows#

Client applications, such as the MES user interface, obtain tokens from the Security Portal using OAuth 2.0 ↗. The Security Portal supports the following grant types:

• Authorization Code - users sign in to MES and installed applications through the browser. See Browser Sign-In.
• Client Credentials - services without a user obtain their own token. See Service Access.
• JWT Bearer - clients authenticate as a user with a registered key pair. See Public Key Authentication.
• Refresh Token - clients renew an access token without signing in again. The Security Portal also uses this grant to exchange a Personal Access Token (PAT) for an access token.
• Password - clients send the user's credentials directly to the Security Portal.
• Token Exchange - a trusted client obtains a token on behalf of a user.

Browser Sign-In (Authorization Code)#

Browser access to MES and to installed applications is protected by the Security Portal Forward Auth service, a Traefik middleware that validates every HTTP request. When a browser request arrives without a valid token, Forward Auth starts the Authorization Code flow against the tenant of the deployment and keeps the resulting tokens in a cookie-based session.

Base Tenant Sign-In#

Forward Auth redirects the browser to the base tenant, where the user signs in with one of the configured strategies. Forward Auth then exchanges the authorization code for tokens, creates the session cookie, and redirects the browser back to the requested page.

sequenceDiagram
    participant User as Browser
    participant FA as Forward Auth
    participant SP as Security Portal (base tenant)
    participant Strategy as Authentication strategy
    participant Host as MES Host

    User->>FA: Open MES
    FA-->>User: Redirect to tenant authorization endpoint
    User->>SP: Sign-in page
    SP->>Strategy: Authenticate user
    Strategy-->>SP: User authenticated
    SP->>SP: Resolve or enroll user
    SP-->>User: Redirect to Forward Auth callback with code
    User->>FA: Callback with code
    FA->>SP: Exchange code at token endpoint
    SP-->>FA: Access, refresh, and ID tokens
    FA-->>User: Set session cookie, redirect to original URL
    User->>FA: Next request with session cookie
    FA->>FA: Validate token with cached JWKS
    FA->>Host: Forward request with access token
    Host-->>User: Result according to MES authorization

Application Tenant Sign-In#

An application follows the same flow against its own application tenant. The application tenant delegates authentication to the base tenant through OpenID Connect, requesting the application's OAuth Role as scope, so the user must hold that OAuth Role in MES to sign in.

sequenceDiagram
    participant User as Browser
    participant FA as Forward Auth (application)
    participant AppTenant as Application tenant
    participant Base as Base tenant
    participant Strategy as Authentication strategy

    User->>FA: Open application
    FA-->>User: Redirect to application tenant authorization endpoint
    User->>AppTenant: Start sign-in
    AppTenant-->>User: Redirect to base tenant (OpenID Connect, scope = application)
    User->>Base: Sign-in page
    Base->>Strategy: Authenticate user
    Strategy-->>Base: User authenticated
    Base-->>User: Redirect to application tenant callback with code
    User->>AppTenant: Callback with code
    AppTenant->>AppTenant: Resolve or enroll user and issue application code
    AppTenant-->>User: Redirect to Forward Auth callback with code
    User->>FA: Callback with code
    FA->>AppTenant: Exchange code at token endpoint
    FA-->>User: Set session cookie, redirect to original URL

Service Access (Client Credentials)#

Services such as CLIs, daemons, or backend services that communicate without a user use the Client Credentials flow. The service requests an access token with its client ID and client secret. The tenant's user source must contain an enabled user whose account matches the client ID, and the token scopes are resolved from that user. When the service acts for a specific user, use a PAT ↗ instead.

Tokens are tenant-bound. Request the token from the tenant whose services the client calls. For endpoint discovery, request construction, and response handling, see Authentication ↗ in the Developer Portal.

Public Key Authentication#

The Security Portal also supports authentication with a private/public key pair through the OAuth 2.0 JSON Web Token (JWT) Bearer grant type. The user registers the public key in the MES User page, and the client authenticates by sending a JWT assertion signed with the private key. Use this flow when a client needs to authenticate without a password or client secret and can securely manage an asymmetric key pair.

Registered public keys can have an expiration date and can be revoked. RSA keys must be at least 4096 bits, and Elliptic Curve Cryptography (ECC) keys at least 256 bits.

For supported algorithms, assertion claims, and request construction, see Public-Key Authentication ↗ in the Developer Portal.

Access Tokens and OAuth Roles#

The Security Portal authenticates users, while OAuth Roles assigned in MES determine which applications each user can access.

After authenticating a user, the Security Portal issues a time-limited access token that identifies the user to MES and to installed applications. The Security Portal is the only issuer of valid tokens. It signs them with a private key that never leaves the Security Portal, and services validate them with the corresponding public key.

The scope of an access token contains all the OAuth Roles assigned to the user in MES. When an application is installed, its OAuth Role is generated automatically, and an administrator must assign it to the users who need access to the application. For more information, see Roles. OAuth Role names must not contain whitespace, because the access token separates multiple scope values with spaces.

Token Validation#

How a token is validated depends on where the request enters the system. In both paths the tenant identified in the token sets the context, and the final authorization result also depends on MES roles, services, features, and Data Groups.

HTTP Requests#

HTTP routes are protected by the Forward Auth middleware. Forward Auth validates the token locally with the tenant's signing keys (JWKS), which it fetches from the Security Portal and caches, so it does not call the Security Portal for every request. It accepts a bearer token, the session cookie, or a PAT sent through Basic authentication. When validation fails:

• API requests receive 401 Unauthorized or 403 Forbidden.
• Browser requests are redirected to sign in page.

sequenceDiagram
    participant Client as HTTP client
    participant FA as Forward Auth
    participant SP as Security Portal
    participant Service as HTTP service

    Client->>FA: HTTP request with bearer token
    FA->>FA: Validate token with cached JWKS
    FA->>SP: Fetch or refresh JWKS when needed
    FA->>Service: Forward request with user identity
    Service-->>Client: Response

For the forwarded headers and the response for each failure, see ForwardAuth ↗ in the Developer Portal.

Message Bus Connections#

The Message Bus uses WebSockets and does not go through Forward Auth. When a client opens a session, the Message Bus gateway calls the Security Portal token introspection endpoint to confirm the token is active and to read its user and tenant. It then requests the user information to obtain the caller's Data Groups and administrator status, and uses this context to enforce which tenants and Data Groups the caller can publish to or receive from.

sequenceDiagram
    participant Client as Message Bus client
    participant Bus as Message Bus gateway
    participant SP as Security Portal

    Client->>Bus: Open WebSocket with access token
    Bus->>SP: Introspect access token
    SP-->>Bus: Token status, user, and tenant
    Bus->>SP: Request user info
    SP-->>Bus: Data Groups and administrator status
    Bus-->>Client: Session established with tenant context

When the Message Bus rejects a session, the reason is not returned to the caller. The Security Portal log shows it as Token Introspection resulted in inactive token because: <reason>. For the introspection contract, see Token Introspection ↗ in the Developer Portal.

Authentication Sources and Strategies#

The Security Portal connects to authentication sources, such as Microsoft Entra ID, an OpenID Connect provider, or the MES database, through strategies. A strategy is a passport.js ↗ plugin that handles the sign-in protocol of one source. Each tenant can have several strategies configured at the same time.

For the available strategies and their configuration, see Strategies. To implement a custom strategy, see Authentication Strategies ↗ in the Developer Portal.