SAML 2.0 troubleshooting

  • Release version: Zurich
  • Updated July 31, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of SAML 2.0 troubleshooting

    This guidance helps ServiceNow customers troubleshoot common SAML 2.0 single sign-on (SSO) issues in the Zurich release. It focuses on typical errors, authentication challenges with CMS pages, redirection problems after login, and verification of relay state handling during SAML authentication flows.

    Show full answer Show less

    Common Issues and Solutions

    • Error message "is not a function": This occurs in multi-node environments when the SAML plugin is not activated on all nodes, causing missing code errors. The resolution is to contact Technical Support to restart any nodes missing the plugin to ensure the .jar file loads properly.
    • SAML not authenticating CMS pages: By default, CMS pages are public and do not require authentication. To enable SAML authentication on CMS pages, change the viewcontent.do public page setting from active=true to active=false.
    • Inability to redirect users back to CMS pages after SAML login: The SSO integration uses the URI parameter to redirect users, but it ignores relative URLs such as /ess. Instead, use deep linking syntax like /navto.do?uri=/ess. This loads CMS content inside the main navigation iframe rather than full-page. When CMS pages are set to private (active=false), a customization to the Installation Exit login script is required to reconstruct the RelayState URL parameter for proper redirection after IdP authentication.
    • SAML does not redirect users appropriately after authentication: Verify whether the relay state parameter is correctly passed to and from the Identity Provider (IdP). Use browser developer tools or third-party HTTP monitoring tools (e.g., Chrome DevTools, Firefox HTTPfox, or Fiddler) to inspect HTTP requests and confirm relay state handling.

    Practical Considerations

    • ServiceNow instances do not support troubleshooting solutions from external sites; use the official knowledge base resources.
    • Proper plugin activation on all nodes is critical in multi-node environments to avoid JavaScript errors.
    • Custom scripting may be necessary to handle deep linking and redirection nuances for private CMS pages.
    • Monitoring HTTP traffic during authentication flows is essential for diagnosing relay state and redirection issues.

    Before contacting support, try the troubleshooting solutions available in the knowledge base on Hi.

    Note:
    The instance does not support solutions provided by external sites.

    To know more, see the KB0759251.

    Table 1. Other Common Issues
    Error or Symptom Solution
    Error message: "is not a function."

    This issue might occur in a multi-node environment. If the plugin does not get activated on all nodes, an error like the following appears:

    org.mozilla.javascript.EcmaError: [JavaPackage org.opensaml.saml2.core.impl.AuthnRequestBuilder] is not a function.

    		 This error occurs because the plugin was not active and did not load the .jar file. Therefore, the code appears to be missing. Contact Technical Support to restart nodes that are missing the plugin.
    SAML does not authenticate users accessing CMS pages. By default, CMS pages are public and therefore do not require authentication. If you want SAML to authenticate CMS pages, change the view_content.do public page from active=true to active=false.
    Cannot redirect a user back to a CMS page after SAML authentication. By default, the SSO integration uses a URL parameter called URI to control where the user is directed after authentication at the IdP. SSO ignores relative URLs. For example, SSO cannot redirect users to a /ess relative URL. Instead, the user has to navigate to a URL such as /nav_to.do?uri=/ess, which uses deep linking syntax.

    However, this puts the ESS portal inside the main navigation content IFrame. In other words, the site does not take up the full page, but rather loads as a page in your instance. For more information, see CMS Sites and Single Sign-On.

    If you change the CMS entry page to make it private by setting view_content.do to active=false, deep linking behavior then requires a customization to the Installation Exit login script. Create a script that looks for the URI portion of the URL and constructs a RelayState URL parameter containing the relative URL path to redirect users after authenticating at the IdP.
    SAML does not redirect users to the appropriate page after authentication. Determine if the relay state is passed out to the IdP and then passed back during authentication. You can do this with a browser capable of saving HTTP request headers and POST info, such as Chrome with its built-in developer tools, or Firefox with the add-on called HTTPfox. For Internet Explorer, use a third-party application such as Fiddler. The goal is to watch the requests pass from the client (browser) to the instance, and from the client to the IdP.