Troubleshooting
Problem
Use this document to troubleshoot Liberty SAML web SSO. This document contains troubleshooting information for SAML web Single Sign-on (SSO) feature in WebSphere® Application Server Liberty. This document can help address common issues with this component before you call IBM support and save you time.
Resolving The Problem
Component: Runtime: Overview
This topic contains error messages and common issues that require a SAML web SSO trace to determine the root cause of the problem. The instructions to obtain a SAML web SSO trace are in the 'Collecting data manually' section of the Collect data tab. If a trace string required for a specific problem is different than what is shown on the Collect data tab, the trace string is noted in the steps to diagnose the problem. In the rest of this document, 'SAML web SSO trace' is referred to as 'SAML trace'.
How do I find the custom properties for the SAML web SSO feature?
The custom properties for SAML web SSO feature can be found in the IBM Documentation. Start with the page for Liberty Core:
| SAML web SSO 2.0 Authentication (samlWebSso20) for WebSphere Application Server Liberty |
If you are not using WebSphere Application Server Liberty 16.0.0.x, use the drop-down at the beginning of the page to select the edition that you are using.
How can I tell if my trace is from server startup?
IBM support requires that traces be gathered from server startup. If you want to make sure that your traces are gathered from server startup, check for the following string in your trace:
|
Search string
|
Full message
|
| smarter planet | CWWKF0011I: The server {0} is ready to run a smarter planet. |
How can I tell if the SAML web SSO feature is installed?
If you see a statement like the following in a SAML trace, the SAML Web SSO feature is installed:
| [17/01/19 18:08:34:847 JST] 00000030 sso20 1 BundleEvent INSTALLED |
How can I tell if the SAML web SSO feature is configured?
To tell if the SAML web SSO feature is configured, search the trace for the string:
| samlWebSso20 |
Find a statement that looks like this:
| [17/01/19 18:08:45:561 CST] 00000026 sso20 1 ServiceEvent REGISTERED ServiceRef:[com.ibm.ws.security.saml.SsoSamlService](id=629, pid=com.ibm.ws.security.saml.sso20_114) Event:org.osgi.framework.ServiceEvent[source={com.ibm.ws.security.saml.SsoSamlService}={includeTokenInSubject=true, nameIDFormat=transient, wantAssertionsSigned=true, sessionNotOnOrAfter=7200000, component.id=502, tokenReplayTimeout=1800000, authFilterRef=com.ibm.ws.security.authentication.filter_112, config.displayId=samlWebSso20[barbjaAppDev01], authnRequestTime=600000, component.name=com.ibm.ws.security.saml.sso20, clockSkew=300000, allowCustomCacheKey=true, enabled=true, mapToUserRegistry=No, idpMetadata=/usr/IBM/WebSphere/Liberty/usr/servers/server1/resources/security/idpMetadata.xml, spHostAndPort=http://server.ibm.com:80, config.source=file, authnContextComparisonType=exact, id=barbjaAppDev01, config.id=com.ibm.ws.security.saml.sso20[barbjaAppDev01], httpsRequired=false, createSession=true, service.factoryPid=com.ibm.ws.security.saml.sso20, service.pid=com.ibm.ws.security.saml.sso20_114, service.vendor=IBM, signatureMethodAlgorithm=SHA1, authnRequestsSigned=true, config.overrides=true, forceAuthn=false, isPassive=false, disableLtpaCookie=true, service.id=629, service.bundleid=261, service.scope=bundle}] |
How do I find my SAML web SSO feature properties in a trace?
To find the SAML web SSO feature properties in a trace, you do the same search that you did previously:
| samlWebSso20 |
Again, find a statement that looks like this:
| [17/01/19 18:08:45:561 CST] 00000026 sso20 1 ServiceEvent REGISTERED ServiceRef:[com.ibm.ws.security.saml.SsoSamlService](id=629, pid=com.ibm.ws.security.saml.sso20_114) Event:org.osgi.framework.ServiceEvent[source={com.ibm.ws.security.saml.SsoSamlService}={includeTokenInSubject=true, nameIDFormat=transient, wantAssertionsSigned=true, sessionNotOnOrAfter=7200000, component.id=502, tokenReplayTimeout=1800000, authFilterRef=com.ibm.ws.security.authentication.filter_112, config.displayId=samlWebSso20[barbjaAppDev01], authnRequestTime=600000, component.name=com.ibm.ws.security.saml.sso20, clockSkew=300000, allowCustomCacheKey=true, enabled=true, mapToUserRegistry=No, idpMetadata=/usr/IBM/WebSphere/Liberty/usr/servers/server1/resources/security/idpMetadata.xml, spHostAndPort=http://server.ibm.com:80, config.source=file, authnContextComparisonType=exact, id=barbjaAppDev01, config.id=com.ibm.ws.security.saml.sso20[barbjaAppDev01], httpsRequired=false, createSession=true, service.factoryPid=com.ibm.ws.security.saml.sso20, service.pid=com.ibm.ws.security.saml.sso20_114, service.vendor=IBM, signatureMethodAlgorithm=SHA1, authnRequestsSigned=true, config.overrides=true, forceAuthn=false, isPassive=false, disableLtpaCookie=true, service.id=629, service.bundleid=261, service.scope=bundle}] |
That configuration corresponds to this entry in the server.xml file:
| <samlWebSso20 id="barbjaAppDev01" spHostAndPort="http://server.ibm.com:80" httpsRequired="false" forceAuthn="false" mapToUserRegistry="No" nameIDFormat="transient" authFilterRef="johsAuthFilter" signatureMethodAlgorithm="SHA1" sessionNotOnOrAfter="2h" disableLtpaCookie="true"/> |
There is one of these trace entries for each SAML config instance that you have in your server.xml file. For instance, here is a copy of the defaultSP config from the same trace:
| [17/01/19 18:08:45:674 CST] 00000026 sso20 1 ServiceEvent REGISTERED ServiceRef:[com.ibm.ws.security.saml.SsoSamlService](id=631, pid=com.ibm.ws.security.saml.sso20_113) Event:org.osgi.framework.ServiceEvent[source={com.ibm.ws.security.saml.SsoSamlService}={includeTokenInSubject=true, nameIDFormat=email, wantAssertionsSigned=true, sessionNotOnOrAfter=7200000, component.id=503, tokenReplayTimeout=1800000, config.displayId=samlWebSso20[defaultSP], authnRequestTime=600000, component.name=com.ibm.ws.security.saml.sso20, clockSkew=300000, allowCustomCacheKey=true, enabled=false, mapToUserRegistry=No, idpMetadata=/usr/IBM/WebSphere/Liberty/usr/servers/server1/resources/security/idpMetadata.xml, config.source=file, authnContextComparisonType=exact, config.id=com.ibm.ws.security.saml.sso20[defaultSP], httpsRequired=true, createSession=true, service.factoryPid=com.ibm.ws.security.saml.sso20, id=defaultSP, service.pid=com.ibm.ws.security.saml.sso20_113, signatureMethodAlgorithm=SHA256, authnRequestsSigned=true, service.vendor=IBM, config.overrides=true, forceAuthn=false, isPassive=false, disableLtpaCookie=true, service.id=631, service.bundleid=261, service.scope=bundle}] |
How do I find the SAMLResponse in a trace?
To find a SAMLResponse that was received from an IdP, search a SAML trace for:
| decoded saml response: |
Find the decoded SAML response directly attached to that statement:
| [17/01/19 18:11:14:729 CST] 000000cc Saml20HTTPPos 3 decoded saml response:<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="s203ee2a51fcd0a80eced675ccb715dc3fb04662e5" InResponseTo="_8NbegX5bOjfcDoAfELdoRTMsODHC2fOz" Version="2.0" IssueInstant="2017-01-19T09:11:14Z" Destination=" <samlp:StatusCode xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Value="urn:oasis:names:tc:SAML:2.0:status:Success"> </samlp:StatusCode> </samlp:Status><saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="s280d9ffd5c9a54911244f6d1c8fe704cec8f1d278" IssueInstant="2017-01-19T09:11:14Z" Version="2.0"> <saml:Issuer> .... </saml:Assertion></samlp:Response> |
Cannot provide requested name identifier with format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress for the given subject
The nameIDFormat property for the samlWebSso20 feature defaults to email. SSO tells the IdP that it wants the NameID in this format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. If the IdP does not support that format, you get an error message in the SAMLResponse that looks something like this:
| <samlp:Status> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester"> <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy"/> </samlp:StatusCode> <samlp:StatusMessage>Cannot provide requested name identifier with format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress for the given subject</samlp:StatusMessage> </samlp:Status> |
Setting the nameIDFormat property to unspecified usually fixes this issue. You can see the list of supported values for the nameIDFormat property on the custom properties page for SAML web SSO 2.0 Authentication (samlWebSso20) for WebSphere Application Server Liberty 16.0.0.x.
CWWKS5048E: There is an error while verifying the SAML assertion Signature
In the most obvious terms, this message means that there was an error validating the signature of a SAML assertion. What it most likely means is that you set wantAssertionsSigned=true (the default), but your SAML assertion does not contain a Signature element.
Unlike WebSphere traditional, where wantAssertionsSigned=true means that either the SAMLResponse -or- the SAML assertion must be signed, in Liberty, wantAssertionsSigned=true means that the SAML assertion must be signed. This error means that the SAML assertion must contain a Signature element.
If your SAML assertions does not contain a Signature element, make sure that you set wantAssertionsSigned=false.
If the SAML assertion in the SAMLResponse contains a Signature element and the signature validation or certificate trust evaluation fails, you get a CWWKS5049E error like the following, not a CWWKS5048E:
| CWWKS5049E: The SAML assertion Signature is not trusted or is not valid. [reason] |
Does Liberty SAML SSO require session affinity?
If application servers are cluster members, and you use a router or reverse proxy server to route your requests, then the router and proxy server must be configured to support session affinity. See Configuring SAML web Browser SSO in Liberty for additional information about setting up Liberty SAML SSO in a cluster.
Cookie “WASSamlSP_12345678” does not have a proper “SameSite” attribute value.
In the Firefox browser, you might encounter a warning that is similar to this one for the WASSamlSP* cookie:
|
Some cookies are misusing the recommended “SameSite“ attribute:
- Cookie “WASSamlSP_12345678” does not have a proper “SameSite” attribute value. Soon, cookies without the “SameSite” attribute or with an invalid value will be treated as “Lax”. This means that the cookie will no longer be sent in third-party contexts. If your application depends on this cookie being available in such contexts, please add the “SameSite=None“ attribute to it. To know more about the “SameSite“ attribute, read https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite for navigator request
|
Action:
- To prevent this warning, set the sameSiteCookie attribute in the webAppSecurity element in your server.xml file to Lax. See Setting the SameSite attribute on cookies with Open Liberty.
- Example:
<webAppSecurity sameSiteCookie="Lax"/>
Is HTTP-Redirect binding supported?
The SAML SSO feature in Liberty does not support HTTP-Redirect binding; it supports HTTP-POST binding only.
The following is a common error that is received from Azure when it is configured for HTTP-Redirect binding. If you get this error, your Azure IdP needs to be reconfigured to allow for HTTP-POST binding in order to interoperate with Liberty.
| AADSTS750054: SAMLRequest or SAMLResponse must be present as query string parameters in HTTP request for SAML Redirect binding. |
Note: This document uses the term full profile 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
[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Component":"Security","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":"18.0.0.x;19.0.0.x","Edition":"Liberty","Line of Business":{"code":"LOB45","label":"Automation"}}]
Was this topic helpful?
Document Information
Modified date:
09 January 2024
UID
swg21994412