S-360 as IDP

S-360 can serve as an Identity Provider (IDP) using SAML protocol.

Interface	Version	Downloadables
SSO Interface	1.0	S-360 SSO public certificate PHP helper SAML Request example (Base64 encoded)

1. Introduction

This document details the various technical components of the Single Sign-On (SSO) system provided by Secutix for the website of an organization that uses PHP.

1.1 Audience

This document is for developers responsible for the integration of the SSO in PHP on the organization's website.

1.2 Functional scope

This document describes the various interfaces provided for the integration of the SSO:

• SSO architecture
• The standard used (SAML).
• The configuration of points of sale.
• The PHP API made available through the SAML library provided.
• Authentication cookies available and the use and lifetime thereof.

1.3 Non Functional consideration

Remember call rate limitation explained in API Terms and Conditions.

2. Architecture

The Single Sign-On (SSO) solution provided by Secutix resolves three issues:

• Centralising user data in Secutix and ensuring a single login on the organization's website and Secutix purchase funnel.
• Synchronise user sessions on the organization's website and Secutix.
• Allow information on the authenticated user to be displayed on the organization's website.

These issues are resolved by means of two solutions provided by the purchase funnel:

• The use of the purchase funnel as an identity provider, or IDP, with the organization's website acting as a consumer of this IDP, which is called the service provider (SP). Information is exchanged between the organization's website and the user using the SAML 2.0 standard.
• The provision of two cookies relating to the authenticated user and the cart contents in the purchase funnel.

The SAML 2.0 standard used is made available via a PHP library that makes it possible to easily manage the creation and interpretation of the requests associated with user authentication. Authentication gives access to the user's contact number, which then makes it possible to retrieve the related information via Secutix's web services (see the documentation on the website interfaces).

2.1 Authentication scenario

The authentication scenario on the purchase funnel remains unchanged. The various authentication scenarios on the corporate website are described below, based on the user's authentication status on the purchase funnel.

Determining authentication status

This status is determined by the presence or lack of the cookie containing the user's contact information. The domain to which this cookie is attached is the domain common to the organization's website and the purchase funnel, and its name follows the following schema:

stx_contact_{Institution code}_{Sales channel code}_v1

This cookie is a session cookie, and contains data about the user and the current session, particularly the cookie's expiry date.

If the cookie is not present, the user has not been authenticated on the sales channel.

If the cookie is present, but the expiry date precedes the current date, the user session on the purchase funnel has terminated and, therefore, the user is not authenticated.

The presence or absence of a contact cookie is verified for each page to synchronise the two sessions in the event in which the user is already authenticated on the sales funnel.

If a session is opened on the organization's website, and the cookie is not present or there is a cookie relating to a channel that does not correspond to the channel of the current session, then the session on the organization's site must be terminated.

SAML queries

Authentication is made using a SAML request that is verified by the IDP to ensure the identity of the SP. In return, the IDP resends an SAML response so as to ensure the identity of the IDP, which contains the authentication status.

If the user has never been recognised, the response also contains a contact number in order to retrieve the related information.

The request and response are both linked by an ID that is encoded in the SAML message: verifying the ID makes it possible to verify that the response received matches the request sent.

If the user is not authenticated on the sales channel

Authentication can be done in two ways: with a form on the organization's website or by using the purchase funnel's form. The choice of the method used is made by means of the parameter embedded defined in the SAML request: if a value is specified (true), the first method is used, otherwise the second is used.

Authentication with the login form on the organization's website

Authentication occurs upon a user action, and interaction between the organization's website and purchase funnel is as follows:

The URL called with the SAML request is the URL defined in the API of the purchase funnel. The URL called back with the SAML response is a parameter contained in the SAML request and in the configuration of the point of sale.

Authentication with the login page of the purchase funnel

The interaction schema is very similar, although the organization's website does not have to manage the creation of the form.

Authentication via social networks

SSO supports the use of social networks instead of authentication by using the user's login and password : the authentication with the social network is done directly on the corporate website, then transmitting the ID obtained and network name during authentication, instead of the login/password (see API below).

If the user does not have an account associated with the social network receiving the request, then authentication fails, and the corporate website should prompt the user to link their account to a Secutix account existing on the purchase funnel or to create one (via the redirection API).

Link an account

An account can be linked in two ways:

• Via the redirection API
• Following an attempted login via social networks, using a SAML request where the username, password and provider to be used are required. The provider must be the same as the provider used in the first request.

If the user is authenticated on the sales channel

For each page, if the user is authenticated on the purchase funnel but not on the organization's website, synchronisation must be performed and the organization's website must perform user authentication. The interaction schema is as follows:

The behaviour is similar, except that the user does not provide its identifiers as it is already authenticated on the purchase funnel, and no action by the user is required.

"Remember me"

The same interaction schema is used in the case of "remember me". When authenticating on the purchase funnel via the SSO, a cookie is created so that the user can be automatically connected for three months. One of the following cases will then take place on the organization's website:

• Having a session with the same duration. When the user returns to the purchase funnel, it will be automatically authenticated.

• Verify the presence of the cookie stx_rememberMe_{Institution code}_{Sales channel code}, then use the mechanism introduced in 2.1.4 to retrieve the user's contact number.

2.2 User logoff

A user logs off simultaneously on the organization's website and purchase funnel when triggered by the user.

In the event the logoff is triggered from the organization's website, it must be performed through the API made available by the purchase funnel, which then redirects the user back to the organization's website.

In the event the logoff is triggered from the purchase funnel and the user has previously been authenticated via the SSO, the purchase funnel redirects to the logout URL of the organization's website before redirecting to the purchase funnel.

A counter on each redirect is used to determine the status of the application (see API). The principle is to be able to determine when to redirect to another entity, and when the user can continue browsing on the site.

The following example describes the case of a logoff from the purchase funnel after a login via SSO. Logging off from the organization's website is symmetrical.

The IDP also shows an API making it possible to specify a specific return URL for more complex cases.

2.3 End of session on purchase funnel due to timeout

If a session is opened on the organization's website, and the cookie is not present or there is a cookie relating to a channel that does not correspond to the channel of the current session, then the session on the organization's site must be terminated.

Session duration

The session on the purchase funnel now lasts 30 minutes, so it is recommended to adopt the same period on the organization's website. This, coupled with the systematic verification of the contact cookie expiry, ensures a synchronisation of the two accounts.

3. Implementation

3.1 Interactions in an iframe

In both cases, the interaction between the organization's website and the purchase funnel can only be performed in the browser or in an iframe to limit the number of page changes.

In order to perform integration in an iframe, the URLs of the API provided by the purchase funnel are not protected via a header X-Frame-Option, unlike the other pages of the purchase funnel. These pages are only usable with a valid SAML request and, accordingly, the security of the purchase funnel is not understood in the absence of this header.

3.2 API of the purchase funnel

/api/1/sso/saml/login

This API is the entry point for user authentication, should be called with the HTTPS protocol (sensitive data such as a user's password are transferred) and only supports the HTTP POST method. The POST parameters are:

POST parameter	Usage
SAMLRequest	SAML authentication request generated using the library provided or built by custom code. The SAML request must be Base64 encoded.
RelayState	Application status. This is a string, which is returned as is to the service provider, which makes it possible to restore the application status after redirecting to the return URL to the organization's website.
embedded	Indicates that the authentication form is hosted on the organization's website.
username	User login in the case described in 2.1.3. Use also to provide the user ID in the case of a login via a social network to the corporate website.
password	User password in the case described in 2.1.3.
structureCode	Contact number used in agency and B2B logins
provider	Code of the social network to be used, if necessary.
rememberMe	Indicates that the "Remember Me" cookie should be created.
spAccountCreationUrl	Optional parameter that specifies a URL for the creation of the account on the SP side. The domain of this URL must match the domain registered for login

/api/1/sso/saml/logout

This API enables user logoff. It is called with the GET HTTP method and the protocol can be http or https. The parameters are:

GET parameter	Usage
count	Step in the logoff loop. If this variable is specified and equal to 0, the logout loop ends. Otherwise, the purchase funnel calls the logout URL associated with the most recent SP recorded.
redirectUrl	Makes it possible to manually specify a return URL.

3.3 PHP library for the generation and interpretation of SAML requests

S-360 provides a library for generating SAML requests used during authentication. It is downloadable from this link of from link PHP helpers in the top box of this document.

SAMLRequest.class

The SAMLRequest class makes it possible to easily generate authentication requests. This class provides the following static method:

Method name	build
Parameters	Name	Description
	forceAuth	Used to force user authentication, even if already authenticated.
	consumerServiceUrl	Specifies a return URL for this SAML request. The URL must be exactly the same as that specified in the configuration of the point of sale.
	issuer	Unique ID of the service provider. Must match the ID specified for the point of sale.
	passPhrase	Password of the private key (see below).
	privKeyPath	Path of the private key used to sign outgoing messages from the directory of certificates specified in the construction of the SAML request.
	certicatePath	Path to the public certificate relating to the private key.
Returns	Parameter Name	Description
	requestEncoded64	Contains the authentication request signed and encrypted in Base64. This request is inserted as a hidden field on the form that is sent to the IDP.
	id	Identifier of the request. This identifier will be present in the response and must be verified to ensure the validity of the IDP's return.

SAMLResponse.class

The PHP class SAMLResponse is used to decode the SAML response returned by the IDP. It provides the following static method:

Method name	decode
Parameters	Name	Description
	requestID	The identifier of the related request.
	samlResponseEncoded	The SAML response encoded in Base64, directly retrieved from the POST parameters of the call made by the IDP
	consumerServiceUrl	Specifies the return URL expected for the SAML response. The URL must be exactly the same as that specified in the configuration of the point of sale.
	issuer	Unique identifier of the service provider.
	SAMLSchemaPath	Path to the SAML XML schema used for validation, from root. This scheme is available here in the directory schema of the zip containing the php library.
	idPCertPath	Path of the IDP's certificate to verify incoming messages.
Returns	Parameter Name	Description
	error	True if an error occurred during authentication.
	msg	Error message if an error occurred.
	contact_number	Null if authentication failed, or the user contact number.

Note that the errors returned by this method relate only to technical errors. Incorrect identifiers will not cause an error, although the user's contact number will be blank and, therefore, the user must be informed of the error and re-requested to provide their identifier.

Technical errors returned are explicit. They are mainly related to exchanges between the SAML library and the IDP, and do not impact integration.

Full usage example can be found here:

Login form on platform website

4. SSO Configuration

4.1 Certificates

SSO uses two X509 certificates for signing SAML messages:

• A certificate used by the IDP to sign SAML responses whose public key is provided to the service provider so that it can check the validity of the SAML responses. The public key alone of this certificate is retained by the organization's website.
• A certificate used by the SP to sign requests. This certificate is thus necessary for signing messages leaving the organization's website and must be specified when using the API made available by the PHP library provided. The public key of this certificate is specified in the configuration of the point of sale of the channel to verify the validity of the SAML requests. This certificate is managed by the organization's website.

4.2 Configuring points of sale

The SSO is set up when setting up a point of sale of a sales channel under the Social Networks tab. The type relating to the configuration of the ticket shop as an IDP is SECUTIX. The following parameters must be entered:

• Internal name and code
• The Application ID, which is the identifier of the customer's service provider. It must be unique for all IDPs at the same point of sale, and must match the identifier entered in the SAML identification request.
• The application's Secret, which is the content of the public certificate relating to the private key used for signing messages used by the service provider, without the tags -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
• Login URL, which is the URL returned by the IDP with the response to the authentication attempt. It must exactly match the URL indicated in the SAML identification request.
• Logout URL, which is the URL returned by the IDP after a de-authentication performed at the ticket shop or service provider. A 10-minute cache of this configuration is kept at the IDP, and changes in these various parameters are not immediately taken into account.

Here is a page detailing those configuration steps with screen capture.

Error code following configuration

The authentication page returns an error code in case of incorrect configuration. Error codes relating to an authentication request that does not match the configuration are as follows:

Code	Meaning
SSO_01	There is no SAML request
SSO_02, SSO_03	An error occurred while reading the SAML request
SSO_04	The SAML object is not an authentication request
SSO_05	There is no identifier for this request.
SSO_06	The identifier of this request is invalid, or there is no identifier specified in the configuration.
SSO_07, SSO_08	The signature of the request is invalid.
SSO_09	The login Url of the request does not match the login Url specified for this identifier. The particular protocol must be the same.
SSO_10	The username or password is missing.
SSO_11	The account creation URL does not have the same domain as the login URL.

5. Cookies provided by the purchase funnel

These two cookies are not HTTP-only, they are accessible via JavaScript.

5.1 Contact cookie

This cookie contains user-related information. The domain to which this cookie is attached is the domain common to the organization's website and the purchase funnel, and its name follows the following schema:

stx_contact_{Institution code}_{Sales channel code}_v1

The contents of this cookie is a JSON object encoded as a URI component. The JSON encoded object contains the following parameters:

Parameter	Contents
individualTitle	User title
individualFirstname	User first name
individualLastname	User last name
nickname	User nickname
lang	User language
timestamp	Login date, not used
expires	Session expiration date, in ISO 8601 format.
additionalData	Additional Data They are encrypted and are not used as part of the SSO.

Check this documentation page for more info.

5.2 Cart integration

The purchase funnel provides the organization's website with a cookie indicating the cart's current status. The domain to which this cookie is attached is the domain common to the organization's website and the purchase funnel. The name of the cookie follows the following naming convention:

stx_cartSummary_{Institution code}_{Sales channel code}

The contents of this cookie are encoded as a URI component. Once decoded, the following information is contained in the cookie, separated by the character |:

• Number of items in the cart.
• Total price.
• Currency used.
• Expiration date, in ISO 8601 format. This date is used to determine the validity of the cart for integration onto the customer website.