Skip to content

SAS iFrame Embedding Guide

Bogdan Mocanu edited this page Jul 12, 2019 · 10 revisions

URL Parameters

Upon request from Swisscom’s All-In Signing service (AIS), the Signature Activation Service (SAS) generates an URL where the browser should be sent to, in order to authenticate the end user and create the final signature. The overall experience and behaviour of SAS can be customized using a set of request parameters that can be added to the generated SAS URL. The following sections describe each of these parameters, their usage and the resulting behaviour.

WithLogo

The withLogo parameter can be used to display the Swisscom logo on each page of the SAS authentication wizard. The value is a boolean (“true”/”false”) and if omitted is “false”. An initial SAS URL such as

http://sas.swisscom.com/sas-server/web/tk9bb15fb8144b4618a2fa3feab428e989tx/pass?lang=en

can be customized with this parameter as it follows:

http://sas.swisscom.com/sas-server/web/tk9bb15fb8144b4618a2fa3feab428e989tx/pass?lang=en&withLogo=true

The following screenshot shows the SAS page with withLogo=false (or missing):

The following screenshot shows the SAS page with withLogo=true:

WithClose

The withClose parameter customizes the handling of the final step in the SAS authentication and signature flow, either for error cases or the successful authentication and signature case. Since the SAS web application can be emdedded in an iFrame, for example, the client might need to customize the way SAS is behaving with regards to closing the window and notifying the embedding client about the finish of the SAS flow. The withClose parameter is a boolean parameter, with values “true”/”false” and, if omitted, “true”. The following behaviour is implemented by SAS, based on the value of this parameter:

  • “true” or missing: SAS displays the “Close” and “Continue” buttons, in case of error and, respectively, authentication and signature success. When the user clicks on either of these buttons, if SAS is running as standalone web page (in its own window or tab), SAS attempts at closing the current window or tab. If SAS detects that it is running in an iFrame, then it sends a Post Message to the embedding client and does not attempt to close the current window (as it is normally impossible to do it). See the Post Message API section below for more details on the communication with an embedding client.
  • “false”: SAS does not display the “Close” nor the “Continue” buttons, in case of error and, respectively, authentication and signature success. When the user reaches the final error or success pages, upon rendering the page, SAS checks whether it is running as standalone web application or embedded in an iFrame/custom window. If running as standalone web application, SAS does nothing. If running as embedded web application, SAS sends a Post Message to the embedding client. See the Post Message API section below for more details on the communication with an embedding client.

An initial SAS URL such as

http://sas.swisscom.com/sas-server/web/tk9bb15fb8144b4618a2fa3feab428e989tx/pass?lang=en

can be customized with this parameter as it follows:

http://sas.swisscom.com/sas-server/web/ tk9bb15fb8144b4618a2fa3feab428e989tx/pass?lang=en&withClose=false

The following screenshot shows the SAS success page with withClose=true (or missing):

The following screenshot shows the SAS success page with withClose=false:

iFrame

The SAS web application can be either called in a standalone window/tab or can be invoked in an embedded iFrame. The latter option is more suitable for clients that want to show SAS in a particular area of their website, maintaining this way the overall look and feel and not disrupting the client’s web application flow too much. SAS is perfectly capable of running in an iFrame, in almost any size combination. Moreover, SAS is compatible and supports any 3rd party content blocking policy, therefore running fine in any browser configuration (i.e. with or without session cookies). To embed SAS in an iFrame, a client needs first to obtain the SAS URL, by calling AIS and requesting a new user authentication (nothing special here, this is the same initial step as with running SAS in a standalone window/tab). Once the URL is obtained, a client can use the HTML and JavaScript code below to embed SAS in an iFrame:

<html lang="en">
<head>
    <script type="text/javascript">
        window.addEventListener('message', function (event) {
            alert('Received message from SAS: ' + event.data);
            console.log('Message received: ' + event.data,event);
            if (event.data === "sas-success") {
                // handle success case
            } else {
                // handle error case; here there are also some possible reasons, see below
            }
        }, false);
    </script>
</head>
<body>
    <div class="iframe-container">
        <iframe name="sas-iframe" src="${sasUrl}" class="sas-iframe"></iframe>
    </div>
</body>

The JavaScript code above registers an event listener for messages sent by SAS (see the Post Message API section below for more information). This part is entirely optional. No JavaScript error is raised if this part is omitted. The actual handling of a SAS event is up to the client (e.g. navigate to some Success/Error page, display a message to the user, close the windows, etc). The actual embedding of SAS in an iFrame is pretty simple. The client can use CSS to customize how the iFrame looks and what dimensions it has.

iFrame sandbox

The iFrame element that embeds SAS can be configured to run SAS in a sandboxed environment. For this, SAS requires a special sandbox policy configuration, with the following value:

<body> 
    <div class="iframe-container"> 
        <iframe name="sas-iframe"  
                src="${sasUrl}"  
                class="sas-iframe" 
                sandbox="allow-forms allow-scripts allow-same-origin"
        ></iframe> 
    </div> 
</body>

The policy is required in this form because:

  • "allow-form": SAS uses forms to transfer data from one step to another
  • "allow-scripts": SAS uses JavaScript to perform client-side validation (there is also server-side validation) and to move the user to the next step
  • "allow-same-origin": SAS loads JavaScript files and other resources from its own domain, which will, in most cases, be different than the domain of the application that is embedding SAS.

Post Message API

For cases when the SAS web application is embedded in an iFrame or managed window, the SAS web application makes use of the Post Message JavaScript API to communicate with the embedding client and notify it when the SAS flow has finished with success or error. In case of an error, there is also some info on the reason why the flow finished with error. The embedding client has the chance to listen to these messages and act on them: resume its internal flow and/or close the managed window, close the iFrame or take the user to some different page. The following JavaScript sample code show how an embedding client can register itself to Post Messages sent by SAS:

<script type="text/javascript">
    window.addEventListener('message', function (event) {
        alert('Received message from iFrame: ' + event.data);
        console.log('Message received: ' + event.data,event);
        if (event.data === "sas-success") {
            // handle success case
        } else {
            // handle error case; here there are also some possible reasons, see below
        }
    }, false);
</script>

The following table lists all the possible codes sent by SAS, as part of the event.data field:

Code Description
sas-success SAS flow finished successfully. The signature has been communicated back to AIS and then back to the client’s backend.
sas-error-authentication-failed SAS flow error, authentication of the user failed (too many wrong password attemps, too many wrong OTP attempts).
sas-error-invalid-transaction-token SAS flow error, invalid transaction token/URL. The user might have waited too long and the transaction expired.
sas-error-user-cancelled SAS flow error, user decided to actively cancel the transaction.
sas-error-general SAS flow error. Any other error goes here, reason might be known or unknown (e.g. internal server error).

Note: the Post Message API makes use of a domain under which the messages are sent. The sending client (in our case SAS) should set a domain, and the receiving party (in our case the embedding client) should check the domain. Since SAS can be embedded under any domain, the Post Messages sent by SAS have a wildcard domain ("*"), and the receiving party is not required to validate it.

Mobile native app embed

The SAS web application can be embedded in a mobile native app, via the use of an internal WebView. Both Android and iOS applications sport a similar component, which allows the native application to open the SAS web app inside its own running context.

While there are a couple of ways in which the internal WebView of a native app can learn and control the web app, the following approach is recommended for the native app to learn what the SAS web application is actually doing in the internal WebView:

  1. Make the native app register as a listener of the WebView's URL changing events

  2. When the URL changes it means the SAS web app has moved one step. This step could be one intermediate or could be a final step: success (the user was authenticated successfully), cancel (the user cancelled the transaction) or some error case.

  3. To learn what the SAS web app is doing, the native app follows the URLs as they are changing, looking for slices of text that indicate various steps in which the SAS web app is currently.

    a. Search for "postCode=sas-success" in the URL. If this slice of text is found, the transaction is finished and the WebView can be closed

    b. Search for "postCode=sas-error-user-cancelled" in the URL. If this slice of text is found, the user cancelled the transaction.

    c. Search for "postCode=sas-error" in the URL. If this slice of text is found (and it is not the case above, #b) then some other error occurred (e.g. timeout)

    d. None of the cases above happens: the transaction is not yet finished

Check also the chapter above (PostMessage API) for a description of all the values that the postCode URL parameter can take.

Clone this wiki locally
You can’t perform that action at this time.