Skip to content

SAS Documentation

Jump to bottom
Dr. Paul Muntean edited this page Feb 9, 2023 · 48 revisions

Introduction

In order to integrate SAS authenticator in the customer signing flow you have to use it as iFrame. The wiki page documents a list of features which are supported by the SAS application. Please note that 4 of this features need work from implementator side and additional source code has to be added in his application such that the feature can be used. Finallu, note that the text below contains a note text describing this.

Available Features

The folloing SAS Features are supported and can be configured by using various URL parameters. The supported URL parameters are described in the next subsections.

GUI Customisation

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.

  1. WithLogo The withLogo parameter can be used to display the Swisscom logo or Custom logo (depending to the next parameter) 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): /images/iFrameGuide_1.png

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

/images/iFrameGuide_2.png

  1. WithLogoSrc The withLogoSrc parameter can be used together with the previous parameter to provide a link to your logo that appear in all SAS pages. The value is a url encoded link. 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&withLogoSrc=https%3A%2F%2F1000logos.net%2Fwp-content%2Fuploads%2F2021%2F09%2FSwisscom-Logo.jpg
  1. LogoWitdh The logoWidth parameter customize the width of the provided logo. It supports values from column E in the table: SAS GUI parameters. If no value set, 80px are used as default.

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&logoWidth=110
  1. LogoHeight The logoHeight parameter customize the height of the provided logo. It supportes values from column F in the table: SAS GUI parameters. If no value set, 76px is used as default.

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&logoHeight=90
  1. LogoMarginTop The logoMarginTop parameter customize the distance from the top of the iframe to the logo. It supports value from column G in the table: SAS GUI parameters. If no value is set, 0px is used by default.

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&logoMargintop=10
  1. LogoMarginBottom The logoMarginTop parameter customize the distance from the bottom ofthe logo to the text in iframe. It supports value from column H in the table: SAS GUI parameters. If no value is set, no value is used as default.

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&logoMarginBottom=-30
  1. BackgroundColor The backgroundColor parameter customize the background color of pages from SAS wizard. It supports value from column D in the table: SAS GUI parameters, descrbed also here CSS Colors.

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&backgroundColor=blue
  1. TextColor The textColor parameter customize the color of the text (except exception text) on all pages of the SAS wizzard. It supports value from column D in the table: SAS GUI parameters, descrbed also here CSS Colors.

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&textColor=blue
  1. ButtonBackgroundColor The buttonBackgroundColor parameter customize the color of button (primary buttons) on all pages of the SAS wizzard. It supports value from column D in the table: SAS GUI parameters, descrbed also here CSS Colors

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&buttonBackgroundColor=blue
  1. ButtonTextColor The buttonTextColor parameter customize the color of the text from button (primary buttons) on all pages of the SAS wizzard. It supports value from column D in the table: SAS GUI parameters, descrbed also here CSS Colors

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&buttontextColor=white
  1. SecondaryButtonBackgroundColor The secondaryButtonBackgroundColor parameter customize the color of the button (secondary buttons) on all pages of the SAS wizzard. It supports value from column D in the table: SAS GUI parameters, descrbed also here CSS Colors

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&secondaryButtonBackgroundColor=blue
  1. SecondaryButtonTextColor The secondaryButtonTextColor parameter customize the color of the text from button (secondary buttons) on all pages of the SAS wizzard. It supports value from column D in the table: SAS GUI parameters, descrbed also here CSS Font Family

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&secondaryButtonTextColor=black
  1. CustomFontFamily The customFontFamily parameter customize the color of the text from button (secondary buttons) on all pages of the SAS wizzard. It supports value from column C in the table: SAS GUI parameters, descrbed also here CSS Colors

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&customFontFamily=arial
  1. 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): /images/iFrameGuide_3.png

The following screenshot shows the SAS success page with withClose=false: /images/iFrameGuide_4.png

iFrame based Event Handling

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>

Note: the script from above needs to be implemented by customer that integrate SAS ifram, in order to use the provided SAS functionality

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 based Sandbox Usage

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>

Note: the script from above needs to be implemented by customer that integrate SAS ifram, in order to use the provided SAS functionality

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>

Note: the script from above needs to be implemented by customer that integrate SAS ifram, in order to use the provided SAS functionality

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 App Integration based on Post Messages

The SAS web application can be embedded in a mobile native app, via the use of an internal WebView. Both Android and iOS applications suport 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.

Note: the functionality described above needs to be implemented by the customer in his mobile application.

Conclusion

This is the current list of SAS features (GUI, flow, etc.). Additional features which will be developed in the future, will be documented on this GitHub wiki page.

Clone this wiki locally