SAML Troubleshooting Guidelines


SAML Troubleshooting Guidelines

This section provides some troubleshooting tips and information about the SAML error codes.

For an overview of using SAML, see About SAML.

For instructions on configuring SAML, see How do I configure SAML?

Browser Settings

This section describes the common issues faced due to incorrect browser settings.

A user’s browser displays the error "Can't display the webpage."

This error can be due to any of the following reasons:

  • The connection is redirected to Zscaler.
  • The user's workstation cannot connect to the URL.

To avoid this issue, do the following:

  1. Check whether an exception is present in your PAC file to make the connection to the server direct (bypassing Zscaler). You can use the default PAC file with the following exception:
if shExpMatch(host, "*.company.tld") return "DIRECT";
  1. Check whether the workstation can connect to the remote server with the following command line in a DOS shell: > telnet <hostname> 443. If you get a black screen, it means that the connection has been established.

A user’s browser is stuck on the redirection page.

If you are seeing the redirection for more than 10 seconds, it means that SAML redirection is looping. This is often due to your explicit proxy configuration. (Note that the connection to the server must be direct and not redirected to Zscaler.)

To avoid this issue, add an exception to your PAC file. You can use the default PAC file with the following exception:

if shExpMatch(host, "*.company.tld") return "DIRECT";

I am getting a basic Login pop-up; authentication is not transparent.

This issue arises because of two reasons:

  • User is not authenticated on the organization’s Federation Identity. Check the following:
    • If the user's computer is registered in Active Directory.
    • If the user is logged in to the Windows Domain.
  • The browser is not configured to forward the user token to this SAML server: By default, Firefox and Chrome browsers do not relay NTLM tokens to the SAML server.  To enable this, do the following:
    • In Firefox: Insert about:config in the address bar, and add the SAML server domain name to the network.automatic-ntlm-auth.trusted-uris option. This allows Firefox to trust the proxy and use NTLM authentication with it.
    • In Chrome: Specify this parameter on the command line: google-chrome --auth-server-whitelist="*.clientdomain.tld"
      By default, Chrome uses the same parameters as IE, so the above setting should not be required in a Windows environment. See http://dev.chromium.org/developers/design-documents/http-authentication for more information.
    • In Internet Explorer: Add the SAML server domain name to Local Intranet security zone.

SAML Error Codes

SAML error codes are displayed when SAML authentication request fails. The following table lists the SAML error codes and troubleshooting tips. Note that a live HTTP header dump will be helpful in all cases.

Error Code Description What to Do

E5501

Relay state not present in response, or an invalid relay state.

Check that the relay state is being sent in the response (sometimes, this happens when REDIRECT binding is configured, instead of POST binding), or check that the response that was sent through Zscaler did not send the request.

E5502

Invalid SAML response received.

IdP issue, or the response is corrupted.

E5503

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5504

SAML response contains more than 20 public certs.

Modify IDP configuration.

E5505

Invalid SAML response received.

IdP response has to be fixed. SAML standard needs XML exc-c14n transform.

E5506

Invalid SAML response received.

IdP issue, or the response is corrupted.

E5507

Invalid SAML response received.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5508

Invalid SAML response received.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5509

Response has been tampered with.

IdP issue, or the response is corrupted.

E550A

If the IdP supports passing a RelayState arguments as part of the sign on URI, this error code appears when the URI that the IdP is using to obtain the SAML assertion does not point to the correct SAML context on the Customer Assertion Service (which is the Zscaler Central Authority).

Check that the relay state is being sent in the response (sometimes, this happens when REDIRECT binding is configured, instead of POST binding. Also, check the relying party SAML 2.0 SSO service URI. Ensure that the URI points to the respective organization’s Org-ID on the sso_upd page as shown in the example below:

https://login.zscalerbeta.net/sso_upd/3817660

(In the example above, 3817660 is the Org-ID of safemarch.net on the zscalerbeta.net cloud. To see the organization ID, log into the admin portal and go to Administration > Settings > Company Profile.)

E5610

Indicates SSL error.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5611

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5612

Response is not a valid SAML response.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5613, E5638

Digital signature mismatch. The certificate issued by the IdP to sign the response is not the same as in the certificate uploaded to Zscaler.

Upload the new certificate to the Zscaler admin portal, and then save and activate the change. If you need help retrieving the SSL certificate, please contact Zscaler support and send the HTML error page that appears during SAML authentication.

E5614

Organization ID does not exist in the response or the organization is disabled.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5615

SAML Portal returned non-success error to us.

User could not authenticate successfully, or SAML IDP is having problems. Check IdP logs.

E5616

Unknown user being sent in SAML response.

User does not already exist (and SAML Auto-Provisioning is not enabled). Create the user first.

E5617

Login attribute is configured as "NameID" but Name ID is not found in the SAML response.

Check the mapping of LDAP attribute to SAML login attribute, or change the SAML configuration on Zscaler.

E5618

Login attribute that is configured (not the 'NameID') is not found in the SAML response.

Check the mapping of LDAP attribute to SAML login attribute, or change the SAML configuration on Zscaler.

E5619

Out of memory or SSL internal errors.

Retry after a few seconds; if the error persists, contact Zscaler Support.

E5620

Authenticated user is not yet synchronized via LDAP.

Wait for the sync to complete.

E5621

User may have been added via LDAP sync, but activation was not performed.

Activate inactivated changes in the UI portal; if the error persists, contact Zscaler Support.

E5622

Unused

Unused

E5623

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

5624

Unknown user being sent in the SAML response.

User does not already exist (and SAML Auto-Provisioning is not enabled). Create the user first.

5625

Error with Login-name.

Contact Zscaler Support.

5626

Unused

Unused

5627

Organization ID does not exist in response or the organization is disabled.

Retry after a few seconds; if the error persists, contact Zscaler Support.

5628

User may have been added via LDAP sync, but activation was not performed.

Activate inactivated changes in the UI portal; if the error persists, contact Zscaler Support.

5629

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

5630

Error with Login-name.

Contact Zscaler Support.

A001

Response format incorrect.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A002

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A003

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A005

Malformed response.

IDP issue or the response is corrupted.

A007

Malformed response.

IDP issue or the response is corrupted.

A008

Malformed response.

IDP issue or the response is corrupted.

A009

Malformed response.

IDP issue or the response is corrupted.

A00A

Malformed response.

IDP issue or the response is corrupted.

A00B

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A00C

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A00D

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A00E

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A00F

Error with Login-name.

Contact Zscaler Support.

A010

User not found.

User might have been deleted. Re-add the user.

A011

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A012

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A013

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A014

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A015

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A016

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A017

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A018

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A019

Error with Login-name.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A020

Domain name is not registered to the organization.

If your IdP passes a full qualified identifier with the SAML assertion, ensure that all your organization's domains are registered with your Zscaler account. This is required to allow all your users to access the service.

If you prefer to pass the sAMAccountName attribute and a non-qualified identifier with the SAML assertion, ensure that only one domain name is associated with your Zscaler account.

A021

Invalid Login-name.

Login-name is not a valid email address.

A022

Response format incorrect.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A023

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A024

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A025

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A026

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A027

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A028

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A029

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A02A

Transient cloud issue.

Retry after a few seconds; if the error persists, contact Zscaler Support.

A02B

Login-name in the response is too big.

Fix the Login-name or the Login attribute.