Configuring Security Assertion Markup Language 2.0 Single Sign-on

This feature is available since YSoft SafeQ 5 MU26 and does not require any special license.

This article describes the steps that have to be performed in order to set up the Security Assertion Markup Language 2.0 (SAML 2.0) Single Sign-on (SSO) to YSoft SafeQ 5 web interface. The configuration of SSO requires advanced knowledge of system configuration and working with the configuration files.

Article also expects that you are familiar with Security Assertion Markup Language 2.0 (SAML 2.0) and you are able to set it up as its configuration is out of scope of this document.

Prerequisites

Identity Provider metadata

  • The URL with metadata with information about SAML Identity Provider providing user authentication must be accessible by the YSoft SafeQ server. The URL response must be formatted according to the SAML specification and contain information about Identity Provider (locations of authentication endpoints, keys used for verification of incoming messages, etc) which YSoft SafeQ will use during authentication process. In case when metadata are not hosted on URL it is possible to copy the metadata XML file manually to the YSoft SafeQ configuration directory under the name SamlIdentityProvider.xml. The system configuration property useSamlHttpMetadataProvider must be disable in order to use the file without any error in the system logs.

  • Identity Provider must be configured to return username of YSoft SafeQ users either as NameIDparameter or one of the assertion attributes. All requests must be configured as (possibly) encrypted and signed. Identity Provider must return values that can be matched against usernames of YSoft SafeQ users.

In case when SAML Identity Provider metadata URL is used and the metadata are hosted on HTTPS endpoint encrypted by self signed certificate it is necessary to import public certificate into the YSoft SafeQ trust store (SAFEQ/conf/ssl-truststore). Use following command to do it (the keytool utility is located at SAFEQ/java/bin/keytool.exe):

keytool -server -import -alias [SERVER_ALIAS_NAME] -file [PEM_CERTIFICATE_FILE_NAME] -keystore [SAFEQ_DIR]\conf\ssl-truststore

YSoft SafeQ user with administrator rights

  • Choose one user in YSoft SafeQ, who will be able to authenticate via SAML (e.g. user replicated via LDAP) and assign him role " safeq admins " . It is necessary in order to retain access to the YSoft SafeQ Web interface with admin rights, because "Username and password" authentication method will not be available when SAML SSO is enabled.
    Default YSoft SafeQ "admin" user cannot be used, unless user with username "admin" exists in the database that SAML is using as source of users to authenticate.

Setup YSoft SafeQ

  1. Log in to YSoft SafeQ web interface with administrator rights

  2. Go to System > System settings page and set following properties.

    1. ssoAuthenticationType to Security Assertion Markup Language 2.0 (SAML 2.0).

    2. samlSsoAuthenticationBindingType to either HTTP Redirect or HTTP POST based on the desired binding or target SAML Identity Provider requirements. The HTTP Redirect is the default and preferred option as it is more secure. The sensitive information about logged user is exchanged via direct SOAP back channel with SAML Identity Provider and not via browser as it is the case with HTTP POST.

    3. allowUnsolicitedSamlResponses to Enabled in case when you want to use Identity Provider initiated SSO. Default mode is Service Provider initiated SSO where authentication request originates at the SafeQ server and is then send to the Identity Provider where it is authorized and returned response is then compared with the original authentication request. When unsolicited responses are allowed it is possible to authenticate users without starting in the YSoft SafeQ for example by crafting special Identity Provider URL that will point users to Identity Provider where the user authentication is resolved and authentication response is then forwarded to the YSoft SafeQ which will create new user session. Note that this way of authentication is less secure as there could not be as many validation checks performed because authentication request did not originated at the Service Provider.

    4. samlSsoAssertionUsernameSource to NameID parameter value or Assertion attribute value, this setting depends on how SAML Identity Provider will serve usernames of authenticated YSoft SafeQ users.

    5. samlSsoAssertionUsernameNameIdFormat, if NameID parameter value was set in previous step b.
      or
      samlSsoAssertionUsernameAttribute to name of the attribute with YSoft SafeQ username.

    6. samlSsoIdentityProviderMetadata to URL that hosts Identity Provider metadata in XML format or disable useSamlHttpMetadataProvider property and copy Identity Provider metadata file manually to the YSoft SafeQ /conf directory manually under the SamlIdentityProvider.xml name.

    7. samlSsoIdentityProviderMetadataUsername to Basic Authentication username if metadata URL requires authentication, otherwise leave the value empty.

    8. samlSsoIdentityProviderMetadataPassword to Basic Authentication password if metadata URL requires authentication, otherwise leave the value empty.

    9. samlSsoIdentityProviderMetadataConnectionTimeout to time in milliseconds after which connection to the SAML server timeouts in case when SAML server does not respond, for example in case when SAML server is down or metadata URL is not correct or inaccessible.

    10. samlSsoIdentityProviderMetadataSocketTimeout to different time in milliseconds after which connection to the SAML server timeouts in case when no response has been received.

    11. allowedSamlResponseAgeInMilliseconds to different time in milliseconds after which will be the authentication response from the SAML server deemed expired. This settings is used to prevent possible replay attacks against the server.

    12. enableSamlSsoLogout to enable, if you want to have logout button available in YSoft SafeQ web interface.

    13. samlAuthenticationRequestIssuer to any string in case when you want YSoft SafeQ Service Provider to have different name. The YSoft SafeQ Service Provider is named and registered in the SAML server by the URL of metadata provider by default when value is empty.

  3. Save changes and restart SafeQ services

  4. Register YSoft SafeQ servers as remote Service Provider in the SAML server (see Setup SAML server below for details). That applies also for CML servers and all ORS servers, where you want to use YSoft Mobile Print Server.

  5. Now SAML Single Sign-On should should work for YSoft SafeQ web interface, YSoft Mobile Print Server web interface as well for YSoft SafeQ Client web interface for managing VIP Shared Queues.
    If one of the mentioned interfaces are accessed, user is redirected to SAML login page, where he will enter credentials. In case authentication to SAML was successful, user is redirected back to fully working session of requested Y Soft application.

Y Soft applications have to be accessed under the hostname that was used for registration of the YSoft SafeQ Service Provider into the SAML server. If authentication requests do not match the registered hostname, the authentication will fail for security reasons

The metadata downloaded from the URL specified in samlSsoIdentityProviderMetadata are cached into the <safeq_home>/conf/SamlIdentityProvider.xml file. In case when URL is not accessible, these backup data are used.

Setup SAML server

The exact configuration of the SAML server is beyond the scope of this document as it depends on vendor of the solution.

  • YSoft SafeQ server has to be registered as remote Service Provider in the SAML server. This is done via metadata served by the YSoft SafeQ at https://<safeq_hostname>/saml-service-provider (exact URL can be found in description of ssoAuthenticationType property in YSoft SafeQ System settings). The YSoft SafeQ Service Provider name is by default set to the metadata URL endpoint mentioned in this paragraph. In case you need to change the name for any reason use samlAuthenticationRequestIssuer configuration property.
    YSoft SafeQ should be registered under its hostname, not IP address as there could be problems with the cookies used for session tracking. Used protocol depends on the YSoft SafeQ settings but HTTPS should be always used, even if everything works with HTTP as well.

  • Each CML server has to be registered as remote Service Provider in SAML server. The metadata URL address of each server where the web SSO will be used for the registration task.

Depending on the SAML server vendor some Service Provider settings must be set manually such as support for encryption and signing of the authentication and logout requests, assertions, NameID and attributes.

Troubleshooting

The logging of authentication communication can be enabled by adding following statement to the <safeq_home>/tomcat/cmlweb/WEB-INF/classes/log4j.xml file, before <root> tag on one of the last lines. For the new installations the logging section can be already found commented out in the log4j.xml file - if that is the case it is enough to just uncomment the section. The CML Web interface system service must be restarted in order to apply changes to the logging.

Trace logging of the SAML communication
<category name="authentication.methods.saml" additivity="false">
<level value="trace" />
<appender-ref ref="log_app"/>
<appender-ref ref="console_app"/>
</category>

Recovery scenario in case of an invalid SAML configuration

It is possible that invalid SAML SSO System configuration will lead to inaccessible system by any user, including administrator.

In such cases, the only possible solution is to run following SQL query on primary YSoft SafeQ database. It will disable SAML SSO and set authentication method back to the default value "Username and password".

Recovery SQL statement
UPDATE safeq_config SET conf_value = 'USERNAME_AND_PASSWORD' WHERE conf_key = 'ssoAuthenticationType'

images/s/-3eliqb/8502/404359a7d2ab19c9c7c58d12013124a386b28257/_/images/icons/emoticons/lightbulb_on.svg NOTE: Manipulation with database can end up with disastrous consequences. You should always ask YSoft Customer Support for the assistance.