IBM Support

TroubleShoot: SAML Web SSO, WebSphere traditional

Troubleshooting


Problem

This document contains troubleshooting information for SAML Web Single Sign-on (SSO) Trust Association Interceptor (TAI) problems in the WebSphere® Application Server traditional.  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'.
 

On earlier fix packs of WebSphere traditional, problem determination of configuration errors was exceedingly difficult. Because of this problem, serviceability updates were put into 7.0.0.45, 8.0.0.14, 8.5.5.13 and 9.0.0.5. If you have a SAML Web SSO issue and the SAML feature was never operational on that system before, be sure to try one of those fix packs (or later). Doing so can greatly reduce your time to resolution.

 

Where can I find the custom properties for the WebSphere SAML Web SSO TAI?

The custom properties for SAML Web SSO can be found in the IBM Documentation. See:

SAML web single sign-on (SSO) trust association interceptor (TAI) custom properties for v8.5.5

If you want to see the custom properties for a version other than 8.5.5, use the Version drop-down at the top of the IBM Documentation page.




 

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
e-business WSVR0001I: Server {0} open for e-business



 

Can the SAML TAI do SP-Initiated SSO with an AuthnRequest?

If you read the IBM Documentation article SAML single sign-on scenarios, features, and limitations, you will find a description of a "bookmark style" login flow at the end of the document. The bookmark style login flow emulates, but does not fully implement, a more traditional SP-initiated flow. This is the only SP-initiated login flow that the SAML TAI supports out-of-box.

 

In WebSphere 7.0.0.39, 8.0.0.11, 8.5.5.7, 9.0.0.0 and later, you can achieve a traditional SP-Initiated login flow with custom code by implementing the com.ibm.wsspi.security.web.saml.AuthnRequestProvider interface. The custom code that you provide builds the AuthnRequest to send to the IdP. Information on how to implement an AuthnRequestProvider for use by the SAML TAI can be found in the Enabling SAML SP-Initiated web single sign-on (SSO) IBM Docs article.



 

Is HTTP-Redirect binding supported?

The SAML SSO feature in WebSphere traditional does not support HTTP-Redirect binding; it only supports HTTP-POST binding.

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 WebSphere.

AADSTS750054: SAMLRequest or SAMLResponse must be present as query string parameters in HTTP request for SAML Redirect binding.



 

How can I tell if trust association is enabled?

In order for SAML Web SSO to work, trust association must be enabled. If trust association is not enabled, the SAML TAI does not load and process requests.

If trust association is enabled, you will see this entry in the trace:
[6/04/16 15:30:29:681 CEST] 00000000 TrustAssociat 3 Trust Association enabled: Trying to load the interceptors

If trust association is not enabled, you will see this entry in the trace:
[6/04/16 15:30:29:681 CEST] 00000000 TrustAssociat 3 Trust Association not enabled

For step to enable trust association, see the second bullet of step number 2 in the document https://www.ibm.com/support/knowledgecenter/SSAW57_9.0.0/com.ibm.websphere.nd.multiplatform.doc/ae/twbs_enablesamlsso.html">Enabling your system to use the SAML web single sign-on (SSO) feature



 

How can I tell if the SAML TAI is configured?

If trust association is enabled and the SAML TAI is configured, you will see the following entry in the trace:

[6/04/16 15:30:29:681 CEST] 00000000 TrustAssociat > loadInterceptor Entry
com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor

If you don't see this entry in the trace, first see the previous section to ensure trust association is enabled. If trust association is enabled, see the second bullet of step number 2 in https://www.ibm.com/support/knowledgecenter/SSAW57_9.0.0/com.ibm.websphere.nd.multiplatform.doc/ae/twbs_enablesamlsso.html">Enabling your system to use the SAML web single sign-on (SSO) feature to use the administrative console to check your TAI configuration.



 

How do I find my SAML TAI custom properties in a trace?

You can find your SAML TAI custom properties in a trace by searching for the string sso_1.sp.acsUrl. Your first hit should look something like this (all on one line):

{sso_1.sp.filter=request-url%=citizenportal, sso_1.sp.acsUrl=https://handicare.sogeti.be/samlsps/citizenportal?user_type=EXTERNAL, sso_1.sp.retryOnceAfterTrustFailure=true, sso_1.sp.targetUrl=https://handicare.sogeti.be/citizenportal, sso_1.sp.EntityID=https://handicare.sogeti.be, sso_1.sp.trustStore=IdPTrustStore, sso_1.sp.wantAssertionsSigned=true, sso_1.idp_1.SingleSignOnUrl=https://wwwint.socialsecurity.be/authenticate/ssaas/loginRequestListener, sso_1.sp.trustedAlias=ssaas-int, alternate.db.url=jdbc:db2://10.227.42.97:50000/HANDIC3, alternate.db.j2c.alias=PRDCuramCellManager01/s_Curam_DB2ADMIN, sso_1.sp.acsErrorPage=https://handicare.sogeti.be/HCSAMLProcessingError.html, alternate.db.driver=com.ibm.db2.jcc.DB2Driver, sso_1.sp.principalName=urn:be:fgov:person:ssin, sso_1.sp.uniqueId=urn:be:fgov:person:ssin, sso_1.sp.idMap=idAssertion, sso_1.sp.userMapImpl=be.handicare.ws.security.web.saml.SSINUserMappingImpl, sso_1.sp.login.error.page=be.handicare.ws.security.web.saml.GenSAMLAuthnRequest}

After that, you will see the properties parsed by the ACSTrustAssociationInterceptor:
ACSTrustAssoc > initialize Entry
ACSTrustAssoc 3 sso_1.sp.filter=request-url%=citizenportal
ACSTrustAssoc 3 sso_1.sp.acsUrl=https://handicare.sogeti.be/samlsps/citizenportal?user_type=EXTERNAL
ACSTrustAssoc 3 sso_1.sp.retryOnceAfterTrustFailure=true
ACSTrustAssoc 3 sso_1.sp.targetUrl=https://handicare.sogeti.be/citizenportal
ACSTrustAssoc 3 sso_1.sp.EntityID=https://handicare.sogeti.be
ACSTrustAssoc 3 sso_1.sp.trustStore=IdPTrustStore
ACSTrustAssoc 3 sso_1.sp.wantAssertionsSigned=true
ACSTrustAssoc 3 sso_1.idp_1.SingleSignOnUrl=https://wwwint.socialsecurity.be/authenticate/ssaas/loginRequestListener
ACSTrustAssoc 3 sso_1.sp.trustedAlias=ssaas-int
ACSTrustAssoc 3 alternate.db.url=jdbc:db2://10.227.42.97:50000/HANDIC3
ACSTrustAssoc 3 alternate.db.j2c.alias=PRDCuramCellManager01/s_Curam_DB2ADMIN
ACSTrustAssoc 3 sso_1.sp.acsErrorPage=https://handicare.sogeti.be/HCSAMLProcessingError.html
ACSTrustAssoc 3 alternate.db.driver=com.ibm.db2.jcc.DB2Driver
ACSTrustAssoc 3 sso_1.sp.principalName=urn:be:fgov:person:ssin
ACSTrustAssoc 3 sso_1.sp.uniqueId=urn:be:fgov:person:ssin
ACSTrustAssoc 3 sso_1.sp.idMap=idAssertion
ACSTrustAssoc 3 sso_1.sp.userMapImpl=be.handicare.ws.security.web.saml.SSINUserMappingImpl
ACSTrustAssoc 3 sso_1.sp.login.error.page=be.handicare.ws.security.web.saml.GenSAMLAuthnRequest



 

SAMLResponse could not be verified.com.ibm.wsspi.wssecurity.core.SoapSecurityException: Fail to decrypt EncryptedKey -or- CWWSS7074E: The key is not retrieved. The exception is: Fail to decrypt EncryptedKey

The WS-Security runtime is used to validate SAML Assertions for the SAML Web Single Sign-on TAI component. The WS-Security trace entries required to debug this error are included in the SAML WSSO trace spec. When you get this error, do the following:
  1. Check the trace for this entry:
    EncryptedData 3 Fail to decrypt EncryptedKey:null
    • If you find this entry, it means that the following property is not specified for the decrypting key:
      sso_<id>.sp.keyName
    • Resolution: Set the sso_<id>.sp.keyName SAML TAI custom property to the value of the alias of your decrypting key in your keystore.
  2. If you do not find EncryptedKey:null, check the trace for an entry similar to this one:
    KeyInfoUtil 3 KeyInfo does not match Key defined in Bindings for
    CN=hostname,O=domain,ST=state,C=com
    • If you find this, the most likely cause is that the partner is Microsoft Windows with ADFS:
      • The Java implementation used by WebSphere Application Server differs from Microsoft Windows in the representation of the "StateOrProvinceName" field of a certificate distinguished name.
      • The WebSphere WS-Security run time is unable to process a certificate sent by ADFS 2.0.  If the issuer's distinguished name contains any "StateOrProvinceName" value and the KeyInfo type for the certificate is X509Data/X509IssuerSerial.
      • The StateOrProvinceName field shows up as S=state from ADFS, whereas the Java implementation used by WebSphere requires it as ST=state, which does not explicitly match, thus causing the failure.
    • Resolution: To work around this interoperability issue, one of the following approaches can be used:
      • Do not include "StateOrProvinceName" in certificate DN's.
      • Do not enable/require the encryption on the operation.
      • Configure the ADFS to identify certificates via X509SubjectKeyIdentifier (KeyId), or Thumbprint. If SAML tokens are affected, X509Data with X509Certificate or X509SKI can also be used. Contact Microsoft ADFS support for information on how to make this change.
Both of these "Fail to decrypt EncryptedKey" errors can also be associated with a web service:
 
  • If you get a "com.ibm.wsspi.wssecurity.core.SoapSecurityException: Fail to decrypt EncryptedKey" error associated with a web service, also check the trace for "EncryptedKey:null". If you find this, then the key name in the callback handler of the token consumer associated with decryption (your inbound encryption part) does not have a value.
  • In the other case, the issue is resolved the same as for SAML WSSO.



 

CWWSS8010E: The SAML response Destination https://mycompany1.com/samlsps/wps/ is not for the service provider https://mycompany2.com/samlsps/wps/

This error generally occurs when there is a conflict between the values two or more acsUrl custom properties. The value for each service provider's acsUrl must be unique. Here is a description of the requirements for the acsUrl custom property:

The value for each sso_<id>.sp.acsUrl property must have a unique URL path. A URL path does not include the protocol and <hostname>:<port> parts of a URL string. For instance, https://here.com/samlsps/app/go and https://elsewhere.com/samlsps/app/go have the same URL path (/samlsps/app/go) so only one of them can be configured as an acsUrl entry.

In the CWWSS8010E message in the problem statement, both of the acsUrl entries shown in the message have the same URL path (samlsps/wps), so they do not meet the requirements.

If you get this message, check the acsUrl settings for each of your service providers to make sure each one of them has a unique URL path.


 

SAMLResponse could not be verified.com.ibm.wsspi.wssecurity.core.SoapSecurityException: unable to find valid certification path to requested target

This error will only appear in a SAML TAI trace. When you experience this problem without trace enabled, you will get at least one ffdc entry that contains the following string:

com.ibm.websphere.security.WebTrustAssociationFailedException: com.ibm.wsspi.wssecurity.core.SoapSecurityException: unable to find valid certification path to requested target
 

If you are getting SAML login failures due to trust validation errors, you will see ffdc entries from the SAML TAI similar to the following:

[3/13/19 19:19:19:513 IST] FFDC Exception:com.ibm.websphere.security.WebTrustAssociationFailedException SourceId:com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor.invokeTAIbeforeSSO ProbeId:552
com.ibm.websphere.security.WebTrustAssociationFailedException: com.ibm.wsspi.wssecurity.core.SoapSecurityException: unable to find valid certification path to requested target
   at com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor.processSAMLResponseContext(ACSTrustAssociationInterceptor.java:867)
   at com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor.invokeTAIbeforeSSO(ACSTrustAssociationInterceptor.java:536)
.....
 

This error is logged at several code points, so the exact stack isn't as important as that it is from the SAML TAI and that the error is unable to find valid certification path to requested target.

What this error means is that you have a truststore configured for the SAML TAI and that the TAI is unable to establish trust for the certificate that signed the SAML Assertion. The SAML TAI uses Java security to establish trust, therefore the rules for the Java runtime that you have installed are enforced. When you get this error, you most likely have one of the following issues:

  • The signing certificate is self-signed, the certificate is not in the truststore.
  • The signing certificate is issued by a root CA, neither the certificate, nor the root CA certificate is in the truststore.
  • The signing certificate is issued by an intermediate CA and the root certificate is in the truststore, neither the certificate, nor the intermediate CA certificate is in the truststore.

As you can see, just from the perspective of fixing a trust validation problem, there are various issues that can be causing the validation problem and each issue can have one or more solutions. However, your specific problem at hand is that the certificate that your SAML IdP used to sign a SAML Assertion is somehow not trusted; this isn't a "general client using a general service" issue. The easiest way to solve this problem is to place the IdP's certificate into the truststore that the SAML TAI is using. To do this, you can do one of the following:

  • Get a file that contains the IdP's signer certificate, then import it into the SAML TAI's truststore.
    1. Import the file that you receive from your IdP administrator into your SAML truststore. To do this with the admin console, see Adding a certificate to a keystore. Alternatively, you can use keytool:
      keytool -import -keystore (trustStoreName) -storepass (trustStorePassword) -file idp.crt -storetype (trustStoreType)
    2. Restart your application server
    3. Retest

  • Extract the IdP's signer certificate from a WebSphere trace, then import it into the SAML TAI's truststore.
    You can only use this method if the idP's X509 Certificate is contained within the SAML Assertion. If you have the sso_<id>.sp.trustedAlias SAML TAI property configured, then you cannot use this method.
     
    1. Gather a SAML SSO trace to catch the error. See MustGather: Web Single Sign-on problems with WebSphere Application Server for the SAML SSO trace specification.
    2. Open the trace.log file in an editor.
    3. To find the SAMLResponse, search the trace for ':Response'.  You will see something like this:
      [3/13/19 19:19:19:201 IST] 0000014d SAMLResponseC 3 > <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_b3f2dd89-7fb3-4716-ab0b-87a88ebc8269" Version="2.0" IssueInstant="2019-03-13T13:50:54.545Z" Destination="https://knowledge.negd.co.in:443/samlsps/wps/" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"><Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://company.com/services/trust</Issuer><samlp:Status><samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"></samlp:StatusCode></samlp:Status><Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="123456789-abcd-dcdc-bfbf-0987654321" IssueInstant="2019-04-09T12:59:54.545Z" Version="2.0"><Issuer>http://company.com/services/trust</Issuer> ...
    4. Within the SAML Response, search for the string X509Certificate You will see something like this:
      <ds:X509Certificate>MIIJBTCCB+2gAwIBAgIQApyyGiSmoUNKs0mEHfv...snip...D3sjPFH1kOXT</ds:X509Certificate>
    5. With an editor, create a new file called idp.crt that contains the following two lines:
      ---- BEGIN CERTIFICATE----
      ----END CERTIFICATE----
    6. From the trace, paste the string between the <ds:X509Certificate> and </ds:X509Certificate> between the BEGIN and END lines in your idp.crt file. It will look something like this:
      ---- BEGIN CERTIFICATE----
      MIIJBTCCB+2gAwIBAgIQApyyGiSmoUNKs0mEHfv...snip...D3sjPFH1kOXT
      ----END CERTIFICATE----
    7. Save the file
    8. Before you import the certificate into your truststore, make sure that you want to trust the certificate. Do one of the following:
      • If you are running on a Windows system, view the certificate via File Explorer:
        1. Start File Explorer.
        2. Open the directory that contains idp.crt.
        3. Double-click on idp.crt, then click Open.
        4. View the certificate information and verify that you want to trust it.
      • Use an online certificate checker tool, such as Certificate Decoder from sslshopper.com, to view the certificate:
        1. Open your certificate decoder.
        2. From the trace, copy the string between the <ds:X509Certificate> and </ds:X509Certificate> tags.
        3. Paste the text into the decoder window.
        4. View the certification information and verify that you want to trust it.
    9. Import the file into your SAML truststore. To do this with the admin console, see Adding a certificate to a keystore. Alternatively, you can use keytool:
      keytool -import -keystore (trustStoreName) -storepass (trustStorePassword) -file idp.crt -storetype (trustStoreType)
    10. Restart your application server
    11. Retest


 

My SAML logins are in a redirect loop

Consider the following scenario:

  1. You direct your browser to a protected resource on WebSphere
  2. WebSphere SAML SSO redirects the request to the IdP for authentication
  3. The IdP redirects back to WebSphere with a valid SAMLResponse
  4. WebSphere validates the SAMLResponse and redirects the request to a target on a server in a different cell
  5. The request is redirected back to the IdP for authentication

Two likely causes of this problem are:
  • You have not exchanged LTPA keys between the two servers
  • You do not have security attribute propagation turned on for both servers (it defaults on)
This apparent login looping is occurring because the target server is rejecting the request for some reason. The best way to debug this issue is to review the logs or trace the target server in the other cell.

When users receive an LtpaToken2 cookie as a result of a Web SSO login, and then use that LTPA cookie to authenticate to a different WebSphere cell than the one which created it, the server that receives the cookie will need to make a SOAP request back to the server where the cookie originated so that it can retrieve the full security attributes for the user. This process is called security attribute propagation. If you intend to use LTPA cookies in this manner, ensure that the network on which your WebSphere cells are hosted is able to facilitate a connection between the two of them so that this process can succeed. For more information about security attribute propagation see the Security attribute propagation topic in the IBM Documentation.

 

How can I retrieve attributes from the SAML token?

After a successful login, the SAML Assertion that was received from the IdP is marshaled into a SAMLToken object and placed onto the WebSphere runAs subject. You can obtain this SAMLToken object and use methods to obtain its attributes and other settings.


In v9.0, and starting in fixpacks 7.0.0.43, 8.0.0.13 and 8.5.5.10, you can use WSSUtilFactory methods that were added with APAR PI62148 to obtain the SAMLToken object from the runAs subject.

Here is some sample code:
import javax.xml.namespace.QName;
import javax.security.auth.Subject;
import com.ibm.websphere.wssecurity.wssapi.WSSUtilFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLTokenFactory;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute;
import com.ibm.wsspi.wssecurity.saml.data.SAMLNameID;
import com.ibm.websphere.security.WSSecurityException;

public class SAMLTest1 {
  SAMLNameID sameNameID;
  String attrName;

  void retrieveSAMLTokens() throws WSSecurityException {
    WSSUtilFactory wssuf = WSSUtilFactory.getInstance()
    SAMLToken samlToken = wssuf.getSaml20Token();
    samlNameID = samlToken.getSAMLNameID();

    for (SAMLAttribute samlAttribute : samlToken.getSAMLAttributes()) {
      attrName = samlAttribute.getName();
    }
  }

 

If you are running on a fixpack that does not include the WSSUtilFactory.getSaml20Token method, you can use the following sample code:
import java.util.Set;
import javax.security.auth.Subject;

import com.ibm.websphere.security.WSSecurityException;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.wsspi.wssecurity.saml.data.SAMLAttribute;
import com.ibm.wsspi.wssecurity.saml.data.SAMLNameID;

public class SAMLTest2 {

  SAMLNameID sameNameID;
  String attrName;

  void retrieveSAMLTokens() throws WSSecurityException{

    Subject callerSubject = com.ibm.websphere.security.auth.WSSubject.getRunAsSubject();
    Set<SAMLToken> privateCredentials =  callerSubject.getPrivateCredentials(com.ibm.websphere.wssecurity.wssapi.token.SAMLToken.class);

    for (SAMLToken samlToken : privateCredentials) {
      samlNameID = samlToken.getSAMLNameID();
      for (SAMLAttribute samlAttribute : samlToken.getSAMLAttributes()) {
        attrName = samlAttribute.getName();
      }
    }
  }  
}



 

Common Issues

Issue 1

When performing bookmark-style SP-initiated SSO, the host name of your initial request URL from the browser must be the same as your acsUrl. The acsUrl is configured on the [sso_<id>.sp.acsUrl] TAI custom property.

When WebSphere redirects the request to the Identity Provider (IdP), the browser will associate the WasSamlSpReqUrl cookie that WebSphere creates with the host name associated with the request URL. The IdP must redirect the request back to the ACS URL. If the request URL host name is not the same as the ACS URL host name, the browser will not send the cookie with the redirected request. If the cookie is not present on the redirected request, the request cannot be redirected to the original URL after authentication.

Things to think about:
  • This can be an issue when the endpoint is invoked with a short hostname or an IP address, but the IdP is configured to send to the WebSphere server with a fully-qualified host name or an IP address.
  • Make sure that these values are all the same:
    1. Host name that users use in the URL of your endpoint
    2. Host name of the load balancer through which your users access the application
    3. Host name in the IdP's acsUrl definition


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.
 

[{"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":"PF012","label":"IBM i"},{"code":"PF013","label":"Inspur K-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"9.0;8.5","Edition":"Advanced;Base;Network Deployment;Single Server","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
03 November 2021

UID

swg21982431