Post Upgrade to Clarity 16.1 existing SAML integration doesn't work
search cancel

Post Upgrade to Clarity 16.1 existing SAML integration doesn't work


Article ID: 254602


Updated On:


Clarity PPM On Premise


Customer who has SAML configured before 16.1 and haven't filled Signon URL in CSA  are unable to use SSO. 

Steps to Reproduce: 

  1. Ensure SAML 2.0 is configured before upgrading to 16.1 and Signon URL is blank 
  2. Start the upgrade to 16.1 and ensure its successful 
  3. Post upgrade try logging to 16.1 using SAML SSO 

Expected Result: The users should be able to login to clarity using SAML 

Actual Result: The users are unable to login and users are redirected to Authentication Error URL as SAML token is not generated and below error stacks can be seen upon enabling the SAML logger 

INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: start doFilter()
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: sessionId from cookie = null
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: Checking for and processing PPMSSO token
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: samlToken from request parameter: null
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: checking for cookie _clarity_User
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: Checking for and processing direct SAML
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: loading SAML settings from toolkit properties
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: samlResponse from request parameters = null
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: No SAML received, skipping destination validation
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: HttpRequest.getRequestURL() = https://CLARITYSERVER/niku/nu
INFO  2022-11-17 18:52:11,516 [https-openssl-nio2-##-##-##-##-443-exec-60] filter.SAMLFilter (clarity:unknown:-1:none) SAMLFilter: Loading of Classic Clarity detected, direct SAML.
INFO  2022-11-17 19:01:56,063 [WrapperListener_stop_runner] filter.SAMLFilter (none:none:none:none) SAMLFilter destroyed


16.1.1 and supported clarity releases. 


The architecture of SAML is changed with introduction of SSO Book Marking Feature where a user now can click on any clarity URL bookmarked and if its SSO enabled it will authenticate and ensure that context is not lost. 


Traditional SSO solutions, i.e. not using SAML,  need to have the field in
Administration > System Options > Other > 'Enable SAML Authentication'
be unchecked, as this is enabled by default, in an upgrade.

In order to use bookmark feature and SAML SSO with 16.0.3, 16.1, 16.1.1 and above please follow the below steps :


Version 16.0.3  - Clarity 16.0.3 has support for SSO_BOOKMARKS feature. This needs to be enabled using a feature toggle in 16.0.3 with command

<clarity home>/bin/admin toggle-feature SSO_BOOKMARKS 1 and restart clarity 


Version 16.1.0  - SSO_BOOKMARKS feature has been enabled by default and can't be disabled. Follow the below steps to configure the Signon URL in CSA

Sign on URL Examples for Okta and Azure IDP's


    • Under New UX → Administration → Authentication & Keys → SAML Configurations → Add the column "SSO Service URL".
    • Copy this value and configure this in NSA → Security → Signon URL.


    • Navigate to Azure Active Directory → Enterprise Applications → Application Created for Clarity.
    • Under properties of this enterprise application, we have a property named "User Access URL", copy this value in notepad.
    • This looks similar to,append &RelayState= to this URL.
    • The final URL looks similar to .
    • Add the above URL in the Signon URL under Settings in CSA

Ping IDP

    • Get "SSO Service URL" and "Entity ID" from SAML Configurations. SSO Service URL is in the format https://PINGSERVER/idp/ URL encode the Entity ID if it's in URL format and append it to SSO Service URL using PartnerSpId as query Parameter. Below is an example.
      SSO Service URL :- https://PINGSERVER/idp/
      Entity ID :- https://CLARITYSERVER/niku/nu#action:union.samlMetadata
      Appended URL :- https://PINGSERVER/idp/
    • Add the above URL in the Signon URL under Settings in CSA with appending &TargetResource=
    • The final URL will look like this: https://PINGSERVER/idp/
    • Save and restart the services

Net IQ Access Manager

    • Get the IDP Signon URL from your SSO Team and Append &TARGET= at the end of the URL. Configure this in the Signon URL of NSA on Clarity and bounce the services.

ADFS (Partial Support)

    • get the idp initiated sing on url from ADFS Admin. It's in the format
    • Once we have the above we need add a query parameter named "loginToRP" with the value of Entity ID of the Clarity Instance that is configured. (Note :- If the entity ID is in URL format, then we need to URL encoded it).
      Entity ID
      :- https://CLARITYSERVER/niku/nu Encoded :-
      Appended URL :- (Note :- An additional & sign is required at the end of the URL).
    • Add the above URL as SignOnURL in CSA


    • Get the IDP initiated sign-on URL from the Siteminder team. Based on the IDP-initiated URL here is a sample without RelayState encoded that can be placed as SignOn URL in CSA:- https://SERVERNAME/affwebservices/public/saml2sso?SPID=ENTITY_ID_PRESENT_IN_SAML_CONFIGURATION&

Version 16.1.1 - From this release SSO_BOOKMARKS feature can be enabled dynamically via the toggle feature. When upgrading to 16.1.1 from 16.0.3 or older versions where SSO_BOOKMARKS was not enabled then run the admin toggle to enable SSO Bookmark feature, and once done proceed to configure the Signon_URL, both steps are described above for the 16.0.3 and 16.1.1 sections respectively.      

Additional Information

Note: There might be other SSO providers where the Signon URL might be named differently, please check with IDP provider and provide the information in CSA in order to ensure SAML SSO is working. 

Some may require appending &RelayState= to the Sign On URL to avoid appending query string arguments to the end of the URL incorrectly.