Troubleshooting
Problem
Collecting data for problems with IBM WebSphere® Application Server versions 8.5 and 9.0 and Liberty using Web Single Sign-on (WebSSO). Gathering this MustGather information before you call IBM support can help you understand the problem and save time analyzing the data.
Resolving The Problem
The Web Single Sign-on components include:
- JWT Authentication
- OpenID Connect
- OpenID
- OAuth
- SAML Web Single Sign-on (SSO)
- SAML Web Inbound
For SSO issues involving 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.
- Read first and MustGathers
MustGather: Read first for WebSphere Application Server
Servlet engine and Web container problem Security problem
For a listing of all technotes, downloads, and educational materials specific to the Web Services Security component, search the WebSphere Application Server support site.
- 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 following methods to help speed problem diagnosis:
- Service Request (SR)
- FTP to the Enhanced Customer Data Repository (ECuRep)
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
OpenID Connect (OIDC), OpenID 2.0, and JWT authenticationEnter WebSphere traditional trace strings as one line with no breaks or spaces.
OAuth provider
SAML Web Single Sign On
SAML Web Single Sign On with WS-Security
SAML Web Inbound
Liberty
OpenID Connect (OIDC), OpenID 2.0, OAuth, and JWT authentication
SAML Web Single Sign Oncom.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.*=allAllcom.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
Enable browser trace
- Chrome™
- Click the three dots to the right of the address bar:
- Click
More Tools
>Developer Tools
- On the
Network
tab, check the box that is labeled "Preserve log
". - Re-create the login.
- When complete, go back to the
Network
tab. - In the Name/Status/Type/etc area, right-click any entry then select "
Save as HAR with content
". - Send the HAR file.
- Click the three dots to the right of the address bar:
- Firefox®
- In the Firefox menu bar, click
Tools
>Web Developer
>Network
.- If you don't have the menu bar, click the "
Open menu
" button on the upper right: - At the end of the page, click
Show / Hide Toolbars
>Menu bar
. - Close the menu setting screen by pressing
Esc
.
- If you don't have the menu bar, click the "
- Click the Gear icon in that window:
- Under
Common Preferences
, select "Enable persistent logs
". - Re-create the login.
- When complete, go to the
Network
tab. - In the Status/Method/File/etc area, right-click any entry, then select "
Save all as HAR
". - Send the HAR file.
- In the Firefox menu bar, click
- Internet Explorer™
- In the Internet Explorer menu bar, click Tools > F12 Developer Tools.
- If you don't have the menu bar, right-click the area around the address bar.
- Select
Menu bar
.
- Click the
Network
tab. - If the "
Clear entries on navigate
" button is selected, clear it: - Click the "
Enable network traffic capturing
" button: - Re-create the login.
- When complete, go back to the
Network
tab. - Click the "
Export captured traffic
" button: - Send this .xml file.
- In the Internet Explorer menu bar, click Tools > F12 Developer Tools.
- Safari®
In Safari, although you can preserve network logs of an SSO login, there is no way to export the data for you to send to IBM support. IBM support will add instructions to this section if they become available.
- Chrome™
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.Trace specifications
Enter WebSphere traditional trace strings as one line with no breaks or spaces.
OpenID Connect (OIDC), OpenID 2.0, and JWT authentication
OAuth provider
SAML Web Single Sign On
SAML Web Single Sign On with WS-Security
SAML Web Inbound
Step-by-step
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.
Item to collectComments / InstructionsProblem description Provide a clear, specific problem description, including specific usage information and error scenario. Diagnostic questions - When does the problem occur?
- How often does the problem occur?
- Did this work in the past? If so, did you make any changes to the system or SSO configuration? Explain.
Single Sign-on configuration
informationGather 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
Single Sign-on trace Enable the Web Single Sign-on tracing that you want and reproduce the problem.
Avoid delay: You must gather SSO traces from server startup to confirm that the components initialized without error.
1. Determine your trace specification- Expand the Trace specifications section earlier in this document.
- Note the trace specification that you need to use based on the TAI that you are using.
- Return to this step.
2. Enable trace- In the administrative console, expand Troubleshooting and select Logs and Trace.
- On the Logging and Tracing page, select your server and then Diagnostic Trace.
- 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.
- Click OK and save your configuration.
- Again expand Troubleshooting and select Logs and Trace.
- In the Logging and Tracing page, select your server and then Change Log Detail Levels.
- Enter the trace string that you chose earlier in the Determine your trace specification step.
- Click OK and save your configuration.
- Proceed to 'Reproduce the problem'
3. Reproduce the problemAvoid delay: You must gather SSO traces from application server startup.
- On your application server on which the TAI is configured, do the following:
- Stop the application server
- Restart the application server
- Start a browser trace
- See the 'Enable browser trace' section earlier in this document.
- 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 fileOn 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.Trace specifications
OpenID Connect (OIDC), OpenID 2.0, OAuth, and JWT authentication
SAML Web Single Sign Onorg.apache.xml.security.*=all:com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.*=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.*=allAllcom.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.*=allStep-by-step
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.
Item to collectComments / InstructionsProblem description Provide a clear, specific problem description, including specific usage information and error scenario. Diagnostic questions - When does the problem occur?
- How often does the problem occur?
- Did this work in the past? If so, did you make any changes to the system or SSO configuration? Explain.
Single Sign-on configuration
informationGather the following files:
- At a minimum, send in server.xml and idpMetadata.xml (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.
Single Sign-on trace Enable the Web Single Sign-on tracing and reproduce the problem.
Avoid delay: You must gather SSO traces from server startup to confirm that the components initialized without error.
1. Determine your trace specification- Expand the Trace specifications section earlier in this document.
- Note the trace specification that you need to use based on the feature that you are using.
- Return to this step.
2. Enable traceTo enable trace on Liberty: - Follow the instructions in the Enabling Trace on Liberty section in Setup trace and get a full dump for WebSphere Liberty.
- See the Liberty: Logging and Trace topic in the IBM Knowledge Center.
- Use the trace string that you chose earlier in the Determine your trace specification step.
- Proceed to 'Reproduce the problem'.
3. Reproduce the problemAvoid delay: You must gather SSO traces from application server startup.
- On your Liberty server on which the feature is configured, do the following:
- Stop the Liberty server.
- Restart the Liberty server.
- Start a browser trace:
- See the 'Enable browser trace' section earlier in this document.
- 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 filesOn Liberty, by default, you can find the trace in the following location:
- (wlp.install.dir)/usr/servers/(server_name)/logs
5. Recursive archive the logs directoryRecursive 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.
Note:
This document uses the term WebSphere traditional to refer to WebSphere Application Server v9.0 traditional, WebSphere Application Server v8.5 full profile, WebSphere Application Server v8.0 and earlier, WebSphere classic, traditional WebSphere, traditional WAS, and tWAS.
Related Information
Was this topic helpful?
Document Information
Modified date:
14 September 2021
UID
swg21971762