Application

TwinCAT HMI in an IFrame

To be able to use a TwinCAT HMI server in an IFrame, several settings are required on the server. A web server blocks the integration in another web interface from a security point of view. Deactivating or restricting this function must be evaluated by the user in terms of safety.

1. Open the server configuration page.
2. Go to the TcHmiSrv / Security tab.
3. Adjust the SameSite attribute entry to your rating. (None disables all functionality)
4. Adjust the entry Permitted origins to your evaluation.
5. Confirm the change by clicking on the Accept button.
The server now allows embedding in an IFrame from a third-party site.

Message:

If you want to display the page of another TwinCAT HMI server in the IFrame, you have the option of sending information to the client via messages. This can be useful for disabling the Splash Screen or changing the theme or language.

Attributes

Description

'System.hideSplashScreen'

The Splash Screen is hidden with System.hideSplashScreen. This means that the embedded TwinCAT HMI does not appear to be a foreign element.

'Theme.set'

Theme.set is used to change the theme in the embedded TwinCAT HMI to the specified value. This allows the TwinCAT HMI to be displayed in a theme corresponding to the main page and not just the default.

'Locale.set'

Local.set is used to change the language in the embedded TwinCAT HMI to the specified value. This allows the TwinCAT HMI to be customized to the language of the main visualization.

Example:

// get the iframe control
let someControl = TcHmi.Controls.get('TcHmiIFrame');
if (someControl !== undefined) {
    // get the iframe element
    let iFrameElement = someControl.getElement()[0].querySelector("iframe");
    if (iFrameElement) {
        const postMessageSender = (event) => {
            if (!event.data?.messageType) {
                return; // No tchmi answer. perhaps react devtools?
            }
            // hide splash screen
            iFrameElement.contentWindow.postMessage(
                {
                    messageType: 'System.hideSplashScreen',
                },
                "*",
            );
            // set theme with the active theme
            iFrameElement.contentWindow.postMessage(
                {
                    messageType: 'Theme.set',
                    themename: TcHmi.Theme.get()
                },
                '*'
            ); 
            // set locale with the active locale
            iFrameElement.contentWindow.postMessage(
                {
                    messageType: 'Locale.set',
                    locale: TcHmi.Locale.get()
                },
                '*'
            );
            // remove event
            window.removeEventListener("message", postMessageSender);
        };
        // add event on message, checked the state of the other side
        window.addEventListener("message", postMessageSender);
    }
}

User management:

If a human-machine interface is used in an IFrame, it must be authenticated. By default, the login page opens here or the auto-login user is logged in. In this case, the users can be different between the main human-machine interface and the subordinate human-machine interface. To circumvent this, it is possible to use the OAuth extension in connection with SSO. The same user is logged in to both HMIs with the corresponding authorizations. In order for the endpoints of the authentication server to run in an IFrame, the corresponding server adjustments must also be made here.

Keycloak:

Adjust the server's Content-Security-Policy setting and add the corresponding IP or host name of the remote system via which the human-machine interface is called to the frame-ancestors entry.

The setting must be evaluated from a security perspective, as it allows external access to the system.