IBM Support

MustGather: Web Single Sign-on problems with WebSphere Application Server

Troubleshooting


Problem

Collecting data for Web Single Sign-on (WebSSO) problems with IBM WebSphere® Application Server versions 8.5 and 9.0 and Liberty. Gathering this MustGather information before you call IBM support can help you understand the problem and save time analyzing the data.

Resolving The Problem

This document describes how to obtain the following troubleshooting data for the SSO components:
image-20240205123623-6 Trace from server startup (trace.log files)
image-20240205123623-6 Browser trace (HAR files)
image-20240205123623-6 Configuration information
image-20240205123623-6 Diagnostic questions
The Web Single Sign-on (SSO) components include:
  • JWT Authentication
  • OpenID Connect
  • OpenID
  • OAuth
  • SAML Web Single Sign-on (SSO)
  • SAML Web Inbound
For SSO issues that involve a component that is not in this list, such as LTPA or Kerberos, see MustGather: Security problems for WebSphere Application Server. For SPNEGO, see MustGather: SPNEGO problems on WebSphere traditional.
  • SSO trace specifications
    Avoid delay: The SSO runtimes emit configuration data in the trace only during server startup. Therefore, you must gather traces to send to IBM support from server startup.
    • WebSphere traditional

      Enter WebSphere traditional trace strings as one line with no breaks or spaces.

      image-20240205123623-6All
      This trace specification is for all SSOs together.  Use this one if you're unsure of what you should choose.
      *=info:com.ibm.ws.security.web.*=all:com.ibm.ws.security.oidc.*=all:com.ibm.ws.security.openidconnect.*=all:com.ibm.ws.security.openid20.*=all:com.ibm.ws.security.saml.*=all:com.ibm.websphere.wssecurity.*=all:com.ibm.ws.wssecurity.*=all:com.ibm.ws.wssecurity.platform.audit.*=off:SamlCommandProviderImpl=all:com.ibm.ws.security.oauth20.*=all:com.ibm.oauth.*=all
      OpenID Connect (OIDC), OpenID 2.0, and JWT authentication
      *=info:com.ibm.ws.security.oidc.*=all:com.ibm.ws.security.openidconnect.*=all:com.ibm.ws.security.openid20.*=all:com.ibm.ws.security.web.*=all

      OAuth provider
      *=info:com.ibm.ws.security.oauth20.*=all:com.ibm.oauth.*=all:com.ibm.ws.security.web.*=all

      SAML Web Single Sign On
      *=info:com.ibm.ws.security.web.*=all:com.ibm.ws.security.saml.*=all:com.ibm.websphere.wssecurity.*=all:com.ibm.ws.wssecurity.*=all:com.ibm.ws.wssecurity.platform.audit.*=off:SamlCommandProviderImpl=all

      SAML Web Single Sign On with WS-Security
      image-20240206153715-2 Do not use this trace specification unless you are directed to do so by support.
      *=info:com.ibm.ws.security.web.*=all:com.ibm.ws.security.saml.*=all:com.ibm.websphere.wssecurity.*=all:com.ibm.ws.wssecurity.*=all:com.ibm.ws.wssecurity.platform.audit.*=off:com.ibm.ws.webservices.multiprotocol.AgnosticService=all:com.ibm.ws.webservices.trace.*=all:com.ibm.ws.webservices.wssecurity.*=all:com.ibm.ws.websvcs.trace.*=all:com.ibm.ws.websvcs.utils.SecurityContextMigrator=all:com.ibm.wsspi.wssecurity.*=all:com.ibm.xml.soapsec.*=all

      SAML Web Inbound
      *=info:com.ibm.ws.security.web.*=all:com.ibm.websphere.wssecurity.*=all:com.ibm.ws.wssecurity.*=all:com.ibm.ws.wssecurity.platform.audit.*=off
    • Liberty
      OpenID Connect (OIDC), OpenID 2.0, OAuth, and JWT authentication
      com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all:com.ibm.wsspi.security.oauth20.*=all:org.openid4java.*=all:org.apache.http.client.*=all:io.openliberty.security.*=all

      SAML Web Single Sign On
      com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.*=all:org.apache.xml.security.*=all:com.ibm.ws.http.*=all:com.ibm.ws.ssl.*=all:com.ibm.ws.channel.ssl.*=all:com.ibm.ws.transport.http.*=all:com.ibm.websphere.channelfw.ChannelUtils=all:org.opensaml.*=all:io.openliberty.security.*=all
      All
      com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all:com.ibm.wsspi.security.oauth20.*=all:org.openid4java.*=all:org.apache.http.client.*=all:org.apache.xml.security.*=all:com.ibm.ws.http.*=all:com.ibm.ws.ssl.*=all:com.ibm.ws.channel.ssl.*=all:com.ibm.ws.transport.http.*=all:com.ibm.websphere.channelfw.ChannelUtils=all:org.opensaml.*=all:io.openliberty.security.*=all
  •  Collect data for WebSphere traditional
    This section is for collecting data for WebSphere traditional. If you want to collect data for Liberty, see the Collect data for Liberty section later in this document.

    To troubleshoot an SSO problem in WebSphere traditional, collect the information listed in the step-by-step instructions in this section.

    When all the information for your issue is ready, follow the instructions on Exchanging information with IBM Technical Support for problem determination to send the information and files that you collected.

    Avoid delay: The WebSphere SSO runtimes emit configuration data in the trace only during server startup. Therefore, you must gather traces to send to IBM support from server startup.
    Items to collect
    Comments / Instructions
    1. Problem description Provide a clear, specific problem description, including specific usage information and error scenario.
    2. Diagnostic questions
    1. When does the problem occur?
    2. How often does the problem occur?
    3. Did this work in the past? If so, did you make any changes to the system or SSO configuration? Explain.
    3. Single Sign-on configuration
    information    		 Gather the following files:
    • (was_profile_root)/config/cells/(cell_name)/security.xml
    • For OAuth issues only:
      • A recursive archive file of (was_profile_root)/config/cells/(cell_name)/oauth20
      4. Single Sign-on trace Enable the Web Single Sign-on tracing that you want and reproduce the problem.

      image-20240206152439-1 Avoid delay: You must gather SSO traces from server startup to confirm that the components initialized without error.

      1. Determine your trace specification
      1. Expand the Trace specifications section earlier in this document.
      2. Note the trace specification that you need to use based on the TAI that you are using.
      3. Return to this step.

        2. Enable trace
        1. In the administrative console, expand Troubleshooting and select Logs and Trace.
        2. On the Logging and Tracing page, select your server and then Diagnostic Trace.
        3. Under Trace Output, select File.
          • The default values for Maximum File Size and Maximum Number of Historical Files are sufficient if you can re-create the problem with one request. However, if the problem is intermittent, it is necessary to increase the File Size to 50 MB and set an appropriate number of historical files.
        4. Click OK and save your configuration.
        5. Again expand Troubleshooting and select Logs and Trace.
        6. In the Logging and Tracing page, select your server and then Change Log Detail Levels.
        7. Enter the trace string that you chose earlier in the Determine your trace specification step.
        8. Click OK and save your configuration.
        9. Proceed to 'Reproduce the problem'

          3. Reproduce the problem
          image-20240206152439-1 Avoid delay: You must gather SSO traces from application server startup.
          1. On your application server on which the TAI is configured, do the following:
            1. Stop the application server
            2. Restart the application server
          2. Start a browser trace
          3. Reproduce the problem, taking note of any relevant user and group names used, exact URL strings accessed, and general time stamps.

            4. Locate the trace file
            On a WebSphere traditional server, you can find the trace in the following location:
            • (was_profile_root)/logs/(server_name)/trace*.log

            Follow instructions to send diagnostic information to IBM support to send the files mentioned in the preceding steps.
             
          • Collect data for Liberty
            This section is for collecting data for Liberty. If you want to collect data for WebSphere traditional, see the Collect data for WebSphere traditional section earlier in this document.

            To troubleshoot an SSO problem in Liberty, collect the information listed in the step-by-step instructions in this section.

            When all the information for your issue is ready, follow the instructions on Exchanging information with IBM Technical Support for problem determination to send the information and files that you collected.

            Avoid delay: The Liberty SSO runtimes emit configuration data in the trace only during server startup. Therefore, you must gather traces to send to IBM support from server startup.
            Items to collect
            Comments / Instructions
            1. Problem description Provide a clear, specific problem description, including specific usage information and error scenario.
            2. Diagnostic questions
            1. When does the problem occur?
            2. How often does the problem occur?
            3. Did this work in the past? If so, did you make any changes to the system or SSO configuration? Explain.
            3. Single Sign-on configuration
            information            		 Gather the following files:
             
            • At a minimum, send the server.xml file and idpMetadata.xml file (for SAML).
            • If you can obtain a recursive archive file of your Liberty installation, and that archive file is 500 mb or smaller, send a compressed, recursive archive file of your Liberty installation directory.
            4. Single Sign-on trace Enable the Web Single Sign-on tracing and reproduce the problem.

            image-20240206152439-1 Avoid delay: You must gather SSO traces from server startup to confirm that the components initialized without error.

            1. Determine your trace specification
            1. Expand the Trace specifications section earlier in this document.
            2. Note the trace specification that you need to use based on the feature that you are using.
            3. Return to this step.

              2. Enable trace
              1. Follow the instructions in the Enabling Trace on Liberty section in Setup trace and get a full dump for WebSphere Liberty.
              2. Use the trace string that you chose earlier in the Determine your trace specification step.
              3. Proceed to 'Reproduce the problem'.

                3. Reproduce the problem
                image-20240206152439-1 Avoid delay: You must gather SSO traces from application server startup.
                1. On your Liberty server on which the feature is configured, do the following:
                  1. Stop the Liberty server.
                  2. Restart the Liberty server.
                2. Start a browser trace:
                3. Reproduce the problem, taking note of any relevant user and group names used, exact URL strings accessed, and general time stamps.

                  4. Locate the trace and log files
                  On Liberty, by default, you can find the trace in the following location:
                   
                  • (wlp.install.dir)/usr/servers/(server_name)/logs
                  If you do not see your trace in that directory, find the log directory configured on the logDirectory attribute in your server.xml file.

                    5. Recursive archive the logs directory
                    Recursive archive the directory that you identified in the previous step and send in the file. This action gathers the following files:
                    • console.log
                    • messages.log
                    • trace.log
                    • ffdc/*

                    Follow instructions on Exchanging information with IBM Technical Support for problem determination to send the files mentioned in the preceding steps.

                  • Exchange data with IBM Support

                    To diagnose or identify a problem, it is sometimes necessary to provide Technical Support with data and information from your system. In addition, Technical Support might also need to provide you with tools or utilities for you to use during problem determination. You can submit files by using one of the following methods to help speed problem diagnosis:

                    • Service Request (SR)
                    • Email
                    • FTP to the Enhanced Customer Data Repository (ECuRep)

                    Exchanging information with IBM Technical Support for problem determination

                  [{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m50000000Ccx5AAC","label":"Security-\u003ESSO"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5.5;9.0.0;9.0.5;CD0","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"}}]

                  Document Information

                  Modified date:
                  06 February 2024

                  UID

                  swg21971762

                  Page Feedback