How to setup SAML authentication

SAML authentication involves two systems:

• Idp - identity provider, the one who perform the authentication

• SP - service provider, the one who ask for authentication

SAML authentication starts in the SP side, with a web page requiring the SSO checking

The communication between IdP and SP is performed by exchanging data in encripted XML; the encryption is based on certificates installed on both sides of the system.

In order to correctly setup the environment on the Platform side, a few global parameters in Platform must be configured in the SAML group:

1. The IdP should provide the SAML metadata, i.e. an XML file containing all settings regarding the IdP, including its certificate (in Base64 format), entity id, signin URL, encryption settings; these must be set in the following parameters:

Assertion signed - checkbox to set according to the agreement defined with the Identity Provider (SAML server provider)

Authentication request signed - checkbox to set according to the agreement defined with the Identity Provider (SAML server provider)

Assertion encripted - checkbox to set according to the agreement defined with the Identity Provider (SAML server provider)

Identity Service Provider Entity ID - to set according to the agreement defined with the Identity Provider (SAML server provider); e.g. https://samltest.id/saml/idp

Identity Service Provider Signin URL - to set according to the agreement defined with the Identity Provider (SAML server provider); e.g. https://samltest.id/idp/profile/SAML2/Redirect/SSO

Identity Service Provider Certificate - to set according to the agreement defined with the Identity Provider (SAML server provider)

Identity Service Provider Signature algorithm - to set according to the agreement defined with the Identity Provider (SAML server provider)

Enable SAML authentication - checkbox used to enable SAML authentication; if not selected, the SAML metadata web service and the SAML authentication will not work

2. Optionally, additional parameters can be filled in, related to the IdP:

Identity Service Provider Digest - to set according to the agreement defined with the Identity Provider (SAML server provider)

Identity Service Provider Fingerprint - to set according to the agreement defined with the Identity Provider (SAML server provider)

Identity Service Provider Signout URL - to set according to the agreement defined with the Identity Provider (SAML server provider); e.g. https://samltest.id/idp/profile/SAML2/POST/SLO

Identity Service Provider support for deprecated algorithms - to set according to the agreement defined with the Identity Provider (SAML server provider)

Identity Service Provider Fingerprint algorithm - to set according to the agreement defined with the Identity Provider (SAML server provider)

3. A certificate can also be defined on the SP side, if required by the agreements shared with the IdP; in such a case, the following parameters must be filled in:

Service Provider URL - a unique identifier for the Platform server (e.g. https://myhost/platformwebcontext/ )

Service Provider X509 Certificate - mandatory; the X509 certificate for Platform, espressed in Base64; it will be included in the XML metadata generated by the Platfmr metadata web service

Service Provider Private Key - mandatory; related to the X509 certificate for Platform

4. Additional parameters that could be defined for the SP are:

Service Provider language - e.g. IT

Service Provider Name - e.g. Sinesy

Service Provider display name - e.g. Sinesy

Service Provider support name - optional

Service Provider support email - optional

Service Provider technician name - optional

Service Provider technician email - optional

5. Once done that, it is possible to generate the SAML metadata to pass to the IdP, containing all settings related to the SP, so that they can be correctly configured on the server; after that, the two systems are ready to communicate with each other; the SAML metadata can be generated using a Platform web service:

https://myhost/platformwebcontext/saml/metadata?appId=DESIGNERmyhost

The user must be logged on the App Designer; the XML content provided by this web service (SAML metadata) can also be read by the IdP if needed, so it can update the SP certificate over time automatically; in order to get the content of this protected web service, credentials must be provided. This can be done either:

• using any user having role 1

• using a special user named SAML_METADATA (to create within the App Designer)

6. The SSO checking is carried out by the end user through the following URL:

https://myhost/platformwebcontext/4ws/saml/index.jsp?appId=MYAPPIDmyhost

7. In any case, an server-side js action be configured in order to receive the callback invoked by the IdP after a correct authentication (ACP event). This action must be configured through the following global parameter in the SAML group:

List of appId,actionId for authentication management - list of couples applicationId,actionId where each couple is separated by a semicolon ; the server-side js action is invoked each time the SAML authentication is valid and the ACP Platform web service has been invoked; the action can read the request body (vo) and request headers (reqHeaders) and use them to retrieve the real Platform user to logon.

The returned JSON must have the following format:

{ 
  success: true, 
  companyId: "...", 
  siteId: ..., 
  username: "...", 
  password: "..", 
  languageId: "..." 
} 

In case the user is not recognized a JSON having this format should be returned:

{ 
  success: false, 
  message: "..." 
}