SSO troubleshooting

This topic describes some common problems and solutions that you might encounter when configuring API Manager SSO. It also describes how to enable traces for SSO.

Logging in both as administrator and SSO user

Problem: API Manager does not work properly when logging in both as administrator and SSO user.

Solution: If an administrator wants to log in to API Manager both as an API administrator and an SSO user, it is recommended that the administrator uses separate browsers to do this. Using separate tabs in the same browser is not enough, because the tabs share the same session.

Cannot access API Manager after successful login

Problem: You cannot access API Manager after a successful login using SSO.

Solution: Verify that there are no errors in the SSO agent log file due to a misconfiguration. Additionally, make sure you are accessing API Manager using the same host name or IP address as the one specified in the API Manager IdP metadata (idp.xml file) used by the Identity Provider:

  • Do not use localhost because some browsers cannot create cookies for this host name.
  • Do not mix host name and IP address. Because cookies are linked to the string used in the URL for the host, there is no IP address resolution.

IdP site cannot be reached

Problem: You attempt to log in to API Manager using SSO and the following message appears in your browser:

This site can’t be reached

<HostName> refused to connect.
ERR_CONNECTION_REFUSED

The URL in the browser address bar contains the address of the IdP, for example, https://keycloak.example.com:8086/idp/profile/SAML2/POST/SSO.

Solution: In this case, the Identity Provider (for example, Shibboleth, KeyCloak, Active Directory Federation Services, and so on) is either not running or not reachable. Contact your system administrator for support. The system administrator should confirm that the service is running and that there are no firewall restrictions preventing access to the service.

Internal error if API Gateway and IdP clocks out of sync

Problem: When attempting to log in to API Manager using SSO, an Internal Error appers if the clock of your API Gateway server and your IdP server are not correctly synchronized.

To confirm the cause of the error, check the trace file:

ERROR   15/sept./2016:14:41:02.018 [3942:dd96da570400a4392aa28808] verifier: io.axway.commons.sso.agent.verifiers.ResponseValidityPeriodVerifier@2edb5d28
ERROR   15/sept./2016:14:41:02.019 [3942:dd96da570400a4392aa28808] Internal error: 
io.axway.commons.sso.agent.ServiceProviderValidationException: Received response not valid. See log for details.

Solution: Ensure that the time on the API Gateway server is synchronized with the IdP.

LDAP response timeout during login

Problem: When attempting to log in to API Manager using SSO, you see a message similar to:

Login Failure: javax.naming.NamingException: LDAP response read timed out, timeout used:3000ms.

Solution: This is due to a problem between the IdP and the LDAP service. Contact your network administrator.

Invalid user or password error after successful login

Problem: When attempting to log in to API Manager using SSO, you see the following message:

Invalid user or password

To confirm the cause of the error, check the trace file:

ERROR   07/Sep/2016:17:11:32.804 [23b8:343cd0572c036c31ecc3f2f7] SSO - The user's organization could not be located. 
Check your service-provider.xml file to see if an OutputAttribute of type 'organization' has been setup. 
Also check the organization has already been setup in API Manager
ERROR   07/Sep/2016:17:11:32.805 [23b8:343cd0572c036c31ecc3f2f7] SSO - Unexpected exception authenticating :
javax.ws.rs.WebApplicationException: HTTP 401 Unauthorized

In this scenario, you have logged in successfully using SSO, but the organization associated with your login is not set up. Either the organization is not configured correctly in the service-provider.xml file or the organization does not exist in API Manager.

The following message appears in the browser page if the organization does not exist in API Manager:

{"errors":[{"code":403,"message":"User was logged in using SSO but failed on permission checks"}]}

Solution: Ensure that the organization is configured correctly in the service.provider.xml file and that the organization exists in API Manager.

For example, the service-provider.xml file contains the following FilterMapping section:

<FilterMapping>
   <Filter>(name=RD Admin)</Filter>
   <OutputAttribute name="role">administrator</OutputAttribute>
   <OutputAttribute name="organization">Research</OutputAttribute>
</FilterMapping>

In this example the organization name is Research.

Log in to API Manager as the apiadmin user (using the non-SSO login URL), and select Client Registry > Organizations. If the organization called Research does not exist, you must add it.

Shibboleth IdP logout failure

Problem: You are using Shibboleth as an IdP and a logout attempt fails with a message similar to the following:

2016-08-30 12:40:23,678 - INFO [org.opensaml.saml.common.binding.security.impl.SAMLProtocolMessageXMLSignatureSecurityHandler:134] 
- Message Handler:  Validation of protocol message signature succeeded, message type: {urn:oasis:names:tc:SAML:2.0:protocol}LogoutRequest
2016-08-30 12:40:23,688 - INFO [net.shibboleth.idp.saml.saml2.profile.impl.ProcessLogoutRequest:315] 
- Profile Action ProcessLogoutRequest: No active session(s) found matching LogoutRequest
2016-08-30 12:40:23,689 - WARN [org.opensaml.profile.action.impl.LogEvent:76] 
- An error event occurred while processing the request: SessionNotFound

Solution: Set the following options for your Shibboleth IDP (as detailed in the sample file INSTALL_DIR/apigateway/samples/sso/ShibbolethIDP/conf/idp.properties.forlogout):

idp.cookie.secure = true
idp.cookie.path = "/"

idp.errors.detailed = true
idp.errors.signed = true
idp.session.enabled = true
idp.session.StorageService = shibboleth.ClientSessionStorageService
idp.session.trackSPSessions = true
idp.logout.elaboration = true
idp.logout.authenticated = false
idp.storage.htmlLocalStorage = true

# for troubleshooting
idp.loglevel.idp=DEBUG
idp.loglevel.ldap=DEBUG
idp.loglevel.messages=DEBUG
idp.loglevel.opensaml=DEBUG

Logout issues with Active Directory Federation Services

Problem: If your SAML IDP is Active Directory Federation Services (AD FS), you may have issues with the SSO logout.

Solution: You must add the a claim rule to enable SSO logout:

  1. In AD FS management, click Trust Relationships > Relying Party Trusts > Edit Claim Rules, and select Add Rule.
  2. Set the Claim Rule Template Type to Send Claims Using a Custom Rule.
  3. Give the claim rule a name, and add the following rule:
  4. c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
     => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, 
    ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-
    format:emailAddress", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "<your SAML Relying Party Trust>", 
    Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "http://<your Active Directory server host>/adfs/services/trust");

    Replace <your SAML Relying Party Trust> with the name of your SAML Relying Party Trust, and <your Active Directory server host> with the value of your Federation Service Identifier. To get the value of your Federation Service Identifier, click AD FS > Edit Federation Service Properties.

Signature validation error

Problem: The API Gateway trace contains the text:

ERROR Could not validate signature on provided assertion
ERROR Assertion identity provider name: '<Identity Provider Name>' format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:entity' 
does not match any allowed identity provider.

Solution: Consider adding the format attribute (as described in the trace text) to the SamlIdentityProvider tag in your service-provider.xml file.

For example:

<IdentityProviders>
  <SamlIdentityProvider
    entityId="<Identity Provider Name>"
    format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
    …
  </SamlIdentityProvider>
</IdentityProviders>

Ensure that you restart API Gateway after saving the file.

SAML assertion validation fails

Problem: There are several possible reasons why the SAML assertion validation fails. To get more detailed information on this error, temporarily enable traces for SSO and restart API Gateway.

If the detailed trace indicates that validation failed because the SAML assertion has expired, there is a conflict in server time between the IdP server and API Gateway, and the SAML assertion is deemed to have expired.

Solution: Synchronize the IdP server time with API Gateway. On UNIX/Linux, check that the NTP service is running.

Alternatively, open the service-provider.xml file, in the SamlIdentityProvider section, set verifyAssertionExpiration to false, and save and redeploy service-provider.xml to API Gateway.

After you have fixed the issue, disable the traces for SSO, and restart API Gateway.

Invalid requester in Keycloak page

Problem: On IdP's side in Events, the following LOGIN_ERROR event could be found:

invalid signature error

Solution: The key in sso.jks and the public key stored in Keycloak’s SAML keys for the application do not match as a keypair. Check the SAML keys in the IdP client, and import the correct certificate.

Error on signing assertions

Problem: After the user enters the credentials on the Keycloak page, the following error is seen:

ERROR   14/Feb/2017:15:08:18.850 [22a1:621da358040092586aa13729] Assertion MUST be signed
ERROR   14/Feb/2017:15:08:18.852 [22a1:621da358040092586aa13729] An error occurred during SSO processing: 
io.axway.commons.sso.agent.ServiceProviderValidationException: Received response not valid. See log for details.
	at io.axway.commons.sso.agent.builders.AuthenticationResponseBuilder.verifyResponse(AuthenticationResponseBuilder.java:94)

Solution: The Sign Assertions setting in Keycloak is switched off. Ensure that the setting is switched on.

Keycloak fails to authenticate the user

Problem: After the user enters the credentials on the Keycloak page, Keycloak fails to authenticate the user with a message similar to the following:

ERROR   13/Feb/2017:17:39:23.346 [6831:4befa158040021d4ae09eee1] SSO - The user's organization could not be located. Check your service-provider.xml file to see if an OutputAttribute of type 'organization' has been setup. Also check the organization has already been setup in API Manager
ERROR   13/Feb/2017:17:39:23.349 [6831:4befa158040021d4ae09eee1] SSO - Failed to authenticate user : [G-fb7c839b-a879-4231-bae9-1c05e3ba6f04]. Exception: : 
javax.ws.rs.WebApplicationException: HTTP 401 Unauthorized

Solution: The username G-fb7c839b-a879-4231-bae9-1c05e3ba6f04 does not correspond to a real username, because the SAML response is not parsed correctly. This happens because the mappings are not set up in the IdP. Ensure the mappings are set correctly in Keycloak. The following shows shows an example on the mappings in Keycloak:

Screenshot showing a sample mapping in Keycloak

Enable traces for SSO

To enable the traces for SSO, change the log level for the org.opensaml logger and for the axway.io logger in the INSTALL_DIR/apigateway/system/conf/log4j2.xml file:

# Logging for SSO
<Logger name="io.axway" level="debug" additivity="false">
<AppenderRef ref="VordelTrace"/>
</Logger>

# Logging for OpenSAML library <Logger name="org.opensaml" level="debug" additivity="false"> <AppenderRef ref="VordelTrace"/> </Logger>

You must also activate the traces in the API Gateway configuration in Policy Studio:

  1. Navigate to Environment Configuration > Server Settings in the Policy Studio tree.
  2. Click General and select the DEBUG level from the Tracing level field.
  3. Deploy the changes.

Finally, you must restart the API Gateway instance to enable the changes in log4j2.xml to be applied.

Related Links