Embedding in an iFrame

Prerequisites

In some contexts it may be necessary to embed the signing environment inside a host page, using an iframe, for example.

This can be achieved using the fUrl provided in the signature creation API call.

Creating the host page

The following example is a host HTML page template that allows you to generate the final HTML page once you have obtained the fUrl.

We used Handlebars for templating, but you can use whatever you want.

Example
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>

<h1 style="text-align: center; color: #aaa;"> This text is in the host page</h1>

<!-- This is a full screen iframe -->
<iframe src="{{fUrl}}" style="position:fixed; top:0; left:0; width:100%; height:100%; border:none; margin:0; padding:0; overflow:hidden; z-index:999999;">
    Your browser doesn't support iframes
</iframe>
</body>
</html>

As you can see, the src of the iframe is set to a string containing {{fUrl}} that, which indicates the template variable to be replaced once we obtain the respective fUrl.

The following code makes the API call to create the signature and precompiles the HTML template that should then be served to the signer.

Example
import {readFile} from "fs/promises";
import handlebars from "handlebars";

async function getPrecompiledHTML(): Promise<string> {

    // Create the signature
    const res = await fetch("https://api.webtrust.kopjra.com/v1/signatures", {
        headers: {
            "Content-Type": "application/json",
            "Accept": "application/json",
            "Authorization": "Basic NjhiOTkxMjEtYWIxNC00YzUwLWFlMzItNDgzZmQ4MWVkNWJkOnlBRG1YTDZ6IzNjVm4tWURPNmJsTWkybGY0MEpNMEdUcFpLVH5+Ujc1eUNEN3ZZVGU2fmJTdTJEOUZwNHFEVjl4RWhtVmRZSw==",
        },
        method: "POST",
        body: JSON.stringify({
            "signerFullname": "Luke Skywalker",
            "signatureType": "graphic",
            "isForensic": true,
            "locale": "en",
            "documents": [
                {
                    "name": "Death_Star_Self-Certification.pdf",
                    "contentBase64": "PDF_IN_BASE64",
                    "failSignature": "BOTTOM_RIGHT"
                }
            ]
        }),
    });

    if (res.ok) {
        // Read the fUrl
        const fUrl: string = (await res.json()).fUrl;

        // Read the handlebars HTML template containing the fUrl placeholder
        const htmlTemplate = await readFile("./templates/signature.html", "utf-8");

        // Precompile the HTML with the fUrl using handlebars
        const template = handlebars.compile(htmlTemplate);
        return template({ fUrl });
    } else {
        throw new Error(`Failed to create signature: ${res.status} ${res.statusText}`);
    }
}

Once the precompiled HTML is served, the signer should see this

As you can see, the signer sees the signing environment opened inside the host web page.

AES support (or lack thereof)

Due to technical constraints regarding the identification of the signer using CIE or SPID, AES signatures don’t support being opened inside IFRAMEs.

This is because the identity providers always respond with the header: X-Frame-Options: DENY.

Therefore, the first step of the AES signature, the authentication of the signer, won't work, and thus the signature won’t work either.