Iframe Support For Trust Web
Introduction
For customers who wish to embed TrustX in an iframe this guide will describe the necessary steps to follow.
Iframe Permissions
In accordance with security best practices TrustX does not allow iframes to embed the web application. Embedding within an iframe is forbidden to prevent bad actors from appearing to host TrustX in their own websites.
In order for TrustX to be embedded in an iframe an update must be made to TrustX's Content Security Policy.
As TrustX is a multi-tenant system, support for iFrame is configured on a tenant by tenant basis. That is, TrustX's Content Security Policies must be altered to enable iframe support. This Content Security Policy generated on a per tenant basis to add only specific hosts as requested by a tenant.
To enable iframe support, set set the trusted iframes from the System Management Settings.
For more information, see the Self Service System Management guide.
A Content Security Policy (CSP) is a security feature that helps prevent a variety of attacks, including Cross-Site Scripting (XSS) and data injection attacks. It is implemented via a special HTTP header that the server sends to the client.
The CSP defines which resources the user agent (typically a web browser) is allowed to load for a given page. This could include scripts, stylesheets, images, and more. By restricting the resources that a user agent can load, the CSP can help to prevent malicious content from being loaded and executed.
For example, a CSP can specify that all scripts on a page must be loaded from the same domain as the page itself, or from a specific list of trusted domains. If an attacker tries to inject a script that loads from a different domain, the user agent will refuse to load it.
For more information please see https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html#content-security-policy-csp
Embedding TrustWeb in an Iframe
This section will demonstrate the correct configuration required to embed TrustWeb within an iframe.
The first requirement for integration is the Process Token URL. This can be achieved from the Process Definition page in the Backoffice.
- Find the Process Definition and expand the the options to add a new token.
- Click on the 'key' icon to generate a token to be used within the iFrame. The token can also be generated programmatically using the APIs, see: Process Definition Tokens Guide.
- Copy the Process Token URL. This will be used to embed TrustWeb in an iframe.
- In the HTML file of your application, add a new <iframe> element and set the src to the Process Token URL.
- The
allow = "camera"permission ensures that camera permissions required to complete an ID&V flow in Trust Web is granted within the iframe. Note, if your process definition does not perform document or face capture thenallow "camera"permission is not required.
<iframe src="{token-url}” allow="camera" width="600" height="800" title="Basic Trust Web Integration"> </iframe>Example:
<iframe src="https://skydev1.oak.trustx-dev.com/web/trustweb/?pt=LXRVXOXA3PZF4APG3GB3TH3IPU" allow="camera" width="600" height="800" title="Basic Trust Web Integration"> </iframe>When using face capture v2 or document capture v4, it is also required to allow gyroscope and accelerometer permissions.
Example:
<iframe src="https://qcm.oak.trustx-qc.com/web/trustweb/?pt=TCTJ64A3U5XWXEJ7GMGVEVJVNI" allow="camera; microphone; gyroscope; accelerometer" width="600" height="800"> </iframe>If the Process Token URL is not correct passed inside the iframe, Trust Web will not appear.
Handling Events
When embedding TrustWeb in an iframe, TrustX will communicate to the parent frame via window messages where each message will have an event and data. These events will occur at the end of the Process Instance.
Possible event types include the following:
| Event | Description |
|---|---|
| webCompleted | Indicates the completion of the TrustX flow. |
| webTimeout | Indicates that an activity has expired during the TrustX flow. |
| error | Indicates an error has occurred. |
The example below demonstrates the alerts that are shown when TrustX sends a message to the enclosing iframe.
Example:
<html><body><script>window.addEventListener('message', (event) => { if (!event.data || !event.data.event) return switch (event.data.event) { case 'webCompleted': if (event.message) { alert('Review') } else alert('Process ended successfully') break case 'webTimeout': alert('Session expired') break case 'error': alert('Process ended with an error') break default: console.log(event.data) }})</script><iframe width="500px" height="500px" src=”{token-url}” allow="camera"/></body></html>The code sample above uses a Javascript switch statement to handle each possible event. For the webCompleted case, the presence of a message indicates that the completed process is in the 'Review' status. Otherwise, webCompleted will not return a message.