SAML protocol tracing - SSO

Owned by ubisebastian
2022-01-16

To help solving problems with SAML protocol issues, it is possible to activate protocol tracing with UAS (as an IDP or IDP Proxy) and with SAML SP for Java.

Protocol tracing is disabled by default.

Please note that various third party browser plugins are available to record and display SAML messages sent between a user's browser and the SAML SP or IDP services. These browser plugins cannot decrypt the message traffic and cannot display messages sent and received directly between an SP and IDP or SP and Attribute Authority using back channel techniques.

Protocol tracing is a diagnostic tool that can expose user and message information in both encrypted and unencrypted format. Access to the protocol tracing URL could compromise system security and therefore should be restricted by the environment firewall and/or application server. Do not use in production environments. Always deactivate protocol tracing after the problem has been solved.

This page describes how to enable protocol tracing on UAS and how to enable tracing using SAML SP for Java.

Enable Protocol Tracing on UAS

To enable recording of the SAML protocol messages on UAS:

  1. Enable Protocol Trace on UAS. Set enabled to true to view through a web browser only. Set file-output to true to additionally record all individual messages to the file system (tomcat\temp). 

    C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\uas\WEB-INF\web.xml
<servlet>
<servlet-name>com.ubisecure.saml2.trace.TraceServlet</servlet-name>
<servlet-class>com.ubisecure.saml2.trace.TraceServlet</servlet-class>
    <init-param>
        <param-name>enabled</param-name>
        <param-value>true</param-value>
    </init-param>
    <init-param>
        <param-name>file-output</param-name>
        <param-value>true</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>


  2. Activate the change by running update: 

    C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\config\tomcat> update.cmd

  3. Do an authentication request:

    1. Check that SAML requests are viewable with web browser at the address
      https://{sso-server address}/uas/trace

      Figure 1. Example of a trace

    2. Check that requests are recorded to the filesystem:
      C:\Program Files\Ubisecure\ubilogin-sso\tomcat\temp\Trace\uas


If log files are not generated, check that in Windows the LOCAL SERVICE account has write-privileges to the application server's temp directory.

Figure 2: Checking LOCAL SERVICE Write permission in Windows environment


 To disable recording of the SAML protocol messages on UAS:

  1. Disable Protocol Trace on UAS. Set enabled to false to view through a web browser only. Set file-output to false to additionally prevent recording of all individual messages to the file system (tomcat\temp). 
    C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\webapps\uas\WEB-INF\web.xml

    <servlet>
<servlet-name>com.ubisecure.saml2.trace.TraceServlet</servlet-name>
<servlet-class>com.ubisecure.saml2.trace.TraceServlet</servlet-class>
    <init-param>
        <param-name>enabled</param-name>
        <param-value>false</param-value>
    </init-param>
    <init-param>
        <param-name>file-output</param-name>
        <param-value>false</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

  2. Activate the change by running update:
    C:\Program Files\Ubisecure\ubilogin-sso\ubilogin\config\tomcat> update.cmd

  3. Do an authentication request:

    1. Check that SAML requests are not viewable with web browser at the address
      https://{sso-server address}/uas/trace
  4. Check that requests are not recorded to the filesystem:
    C:\Program Files\Ubisecure\ubilogin-sso\tomcat\temp\Trace\uas

Enable Tracing on SAML SP for Java

To enable the recording of the SAML protocol messages on SAML SP for Java:

  1. Add the following to the web.xml configuration of the application protected by the SP. Set enabled to true to view through a web browser only. Set file-output to true to additionally record all individual messages to the file system (temporary directory of application server).

    <!-- Protocol Tracing -->
    
    <filter>			
        <filter-name>com.ubisecure.saml2.trace.TraceServlet</filter-name>
        <filter-class>com.ubisecure.saml2.trace.TraceServlet</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>com.ubisecure.saml2.trace.TraceServlet</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping> 
    <servlet>
        <servlet-name>com.ubisecure.saml2.trace.TraceServlet</servlet-name>
        <servlet-class>com.ubisecure.saml2.trace.TraceServlet</servlet-class>
        <init-param>
            <param-name>enabled</param-name>
            <param-value>true</param-value>
        </init-param>
        <init-param>
            <param-name>file-output</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>com.ubisecure.saml2.trace.TraceServlet</servlet-name>
        <url-pattern>/trace/*</url-pattern>
    </servlet-mapping>

  2. Do an authentication request:

    1. Check that SAML request are viewable with web browser on address /{application context root}/trace (e.g ., http://localhost:8080/palvelu/trace).
    2. Check that requests are recorded to the application server's temp directory.


Ubisecure Privacy Policy & Cookie Statement