Skip to content

SAS Documentation

Jump to bottom
ionut-vacariu-mindit edited this page Apr 9, 2024 · 48 revisions

Introduction

In order to integrate the SAS authenticator with the customer signing flow, the customer has to integrate his application with the iFrame based GUI of SAS. This wiki page documents the list of features which are supported by the SAS authenticator. Please note that 4 of these features need work from implementator/customer side and additional source code has to be added in the customer application such that the feature can be used. Finally, note that the text below contains a note text describing this requirement.

The SAs based signing flow GUI screens are available here. https://github.com/SwisscomTrustServices/AIS/blob/master/SAS%20based%20signing%20flow.pdf

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 Customization

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. With progress bar The progress bar used in the SAS GUI to display the remaining time until the session time in SAS expires should be made visible or not. There are use cases where customers do not want to see the progress bar.

Configuration:

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

The withProgressBar parameter can be set to true (which is also default value, so seting it to true is optional) than the progress bar will be displayed and for false the progress bar will be not displayed.

  1. Progress bar line color The progress bar used in the SAS GUI to display the remaining time until the session time in SAS expired should be customizable. There are use cases where customers want to display the progress bar in a certain combination color. There are two parameters that can be set for progress line color and progress background color, mentioned at point 1 and 2. The list of supported colors is the same as the list for text colors. https://www.w3schools.com/cssref/css_colors.php

Configuration:

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

The progressBarLineColor can be set to blue or any other supported color. The set of colors to customize the

  1. Progress bar background color The progress bar used in the SAS GUI to display the remaining time until the session time in SAS expired should be customizable. There are use cases where customers want to display the progress bar in a certain combination color. There are two parameters that can be set for progress line color and progress background color. The list of supported colors is the same as the list for text colors. https://www.w3schools.com/cssref/css_colors.php

Configuration:

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

The progressBarLineColor can be set to blue or any other supported color. The set of colors to customize the

  1. With logo 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. With logo src 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. Logo witdh 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. Logo height 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. Logo margin top 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. Logo margin bottom The logoMarginBottom 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. Background color 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. Text color 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. Button background color 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. Button text color 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. Secondary button background color 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. Secondary button text color 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. Custom font family 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. Custom hyperlink color The customHyperlinkColor parameter customize the color of hyperlink text (re-send SMS). It supports value from column D in the table: SAS GUI parameters, descrbed also here

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&customHyperlinkColor=black
  1. With close 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

  1. withAutofill

The autofill parameter enables the automatically completion of code and submit of "code" page. This flag needs to be set on true/false if you want to enable this feature. If you are using this page as an iframe, you should also take into consideration the point 20. If you open it as a separate page, just set it on true and it will work. 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&withAutofill=true
  1. autofillDomain

! Only for iFrame case.

In order for autofill to work, the domain is needed to be part of SMS. In order to set the domain of the application that is using iframe, please set autofillDomain property in 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&withAutofill=true&autofillDomain=yourDomain.com

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 the user in his application, 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"
        ></iframe> 
    </div> 
</body>

Note: the script from above needs to be implemented by the user in his application, 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

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.

For this, client needs to add one of the following CSP Headers (PROD or PREPROD) depending on what iframe is using:

frame-src 'self' https://ais-sas.swisscom.com https://ais-sas.pre.swissdigicert.ch

! PLEASE DO NOT USE:_ allow-scripts_ and allow-same-origin in the same time, since this will allow atacker to run JavaScript in iframe sandbox

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 the user in his application, 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:

Be aware that the postmessages in the list below mention the status of the authentication application (SAS) and do not comunicate the status of the signature service!

Code Description
sas-success Authentication flow finished successfully. Authentication status was successfully sent back to the signing service.
sas-error-authentication-failed Authentication flow error, authentication of the user failed because there were more than 3 wrong password/SMS Code (OTP) entering attempts.
sas-error-invalid-transaction-token Authentication flow error, invalid transaction token/URL. Reason 1: The user waited more than 8 minutes to enter the password/SMS code and the transaction expired. Reason 2: An invalid token was provided in the consent URL.
sas-error-user-cancelled Authentication flow error, user decided to actively cancel the transaction by pressing the cancel button.
sas-error-general Authentication flow error. Any other error goes here, the reason is 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 user in his mobile application in oder to inform the mobile app Webview how to navigate between different GUI screens.

Conclusion

This is the current list of SAS (GUI, flow, event handling, post messages, etc.) features . Additional features which will be developed in the future, will be documented on this GitHub wiki page. Lastly, we will provide in future a SAS reference guide which will document all SAS features and explain how to use these.

Clone this wiki locally