Single Sign-on Functionality

Note: We are currently enhancing our SSO set up process. The process explained here is outdated and will soon be replaced. If you wish to enable SSO for your account, please contact our support team for the latest instructions and assistance.

SSO is a company add-on and is subject to payment. If the client company does not have the add-on, then the SSO option will not be available in the Web Options page for a survey (refer to the Authoring User Guide), and the External Username field will not be available on the User Details page (go to User Details for more information).

The Single Sign-on (SSO) functionality enables clients to use their own company authentication infrastructure when logging on to the Authoring environment, Reportal (designers and report viewers) and limited surveys. If a respondent has already logged on to the company system, they will be able to access the survey without the requirement for additional in-logging.

For a client to be able to use SSO, the client must provide Forsta with a 256-bit AES key for establishment of the trust, and this should be done over a secure file transfer channel. This key is supplied in the Company Details page (go to Company Details Overview for more information). This key will be used when decrypting the tokens that are presented by the users during login. The SSO company add-on must also be enabled for the client.

The External Username field in the User Details page (go to User Details for more information) should contain a combination of <company>_<username>, where company is a constant configured in SSO and username is the username the user has in the external system and which is also provided through SSO.

Authentication

1. SSO authentication is performed by sending a clear-text company identifier (“co”) and an encrypted token (“key”) via HTTP(S) POST or GET to a Single Sign-on enabled login page in Forsta Plus .
• The “co” parameter should contain the client company id.
• The “key” query parameter should have a value equal to the base 64 encoding of the encrypted value of the string composed of semi-colon delimited key value pairs for id, timestamp, and in some cases destination URL:
• id – Forsta Plus user id
• ts - UTC timestamp of the form “2007-01-10 23:39:39”
• url - Destination URL

Sample decrypted “key” value: id=abc123;ts=2007-01-10 23:39:39

2. The value for the “key” parameter must be encrypted by the client using the same 256-bit AES key that was sent to Forsta previously when enabling SSO. ECB blocking and PKCS5 padding must be utilized.
3. Forsta Plus will attempt to decrypt the “key” parameter using the key associated with the client identified by the “co” parameter. If this fails, the authentication request will be rejected. Otherwise authentication will be successful as long as the timestamp parameter is not older than a predefined (but configurable) number of seconds. This leeway is used to address lack of systematic clock synchronization across client and Forsta systems. Every effort should be made to reference a common time source and narrow the timestamp timeout period. After a successful authentication, authorization is performed using the decrypted “id” value.

Surveys

Generic SSO can be used to access open surveys. If it is used, when returning to an already started interview via the use of “__sid__” or “r” and “s”, if “co” and “key” are also supplied, the “username” field is updated with the value of “id” from the “key” parameter.

To use Generic SSO when logging on to a limited survey, the survey must be deployed as “Single Sign On survey". This option is selected under Survey Settings > Web Options > Survey type, which is available if the user's company has the SSO add-on. Note that SSO requires respondents to be uploaded with a "username" column.

The survey can then be accessed using two different endpoints:

1. Normal survey link: <deployment server url>/wix/<project id>.aspx.
2. SSO survey link: <deployment server url>/wix/sso.aspx. In this case the Destination URL parameter should be used, and given a value that equals the normal survey link. The user will be redirected to this URL after successful authentication.

The “co” and “key” parameters must of course be included to enable the authentication.

If SSO is used to access an interview, after the respondent is located by “__sid__”, the “username” value is matched against the “id” value in the “key” parameter. If the values do not match, the interview will not start.