SAML Troubleshooting Tips

If your SAML Single Sign-On (SSO) integration fails to authenticate users, use the following diagnostic tools and resolution steps to identify and fix the issue.

Gaining Visibility into SAML Traffic

Before diagnosing specific errors, you must be able to inspect the SAML assertions and system logs to see the data being exchanged between Trust Protection Foundation and your Identity Provider (IdP).

Create a Custom Event View

Detailed SAML logging is available in the CyberArk Configuration Console. To isolate these events:

  1. Expand the Event Viewer node.
  2. Right-click Custom Views and select Create Custom View.
  3. In the Logged field, choose Last Hour.
  4. For Event Sources, select the parent SAML Group node.
  5. Save the view with a name such as SAML Last Hour.

Enable Debug Logging

If the standard logs lack sufficient detail, you can force the system to store raw SAML Assertions:

  1. In the Policy Tree, navigate to the Platforms tree.
  2. Select the server(s) with Web Console enabled.
  3. Temporarily activate Debug Logging.

Use a Browser Tracer

As a real-time alternative to server logs, use a browser extension like the Firefox SAML Tracer. This tool captures and decodes SAML XML documents as they pass through your browser. Ensure the extension window is open before you initiate the login attempt.

Common Configuration Failures

Verify that your environment meets these core SAML requirements. Small discrepancies in network or security settings are the most frequent causes of authentication failure.

Fully Qualified Domain Names (FQDN)

Trust Protection Foundation matches the SAML response destination against the URL in the browser.

  • The Issue: Accessing the console via IP address or localhost will cause the system to reject the SAML response for security reasons, even if the IdP is configured correctly.
  • The Fix: Always use the FQDN (e.g., platform.example.com) that matches the trusted Operational Certificate installed on the server. If you change the FQDN, you must re-export the Service Provider Metadata XML and update the configuration at your IdP.

Time Synchronization and Clock Skew

SAML assertions include a NotOnOrAfter parameter to prevent replay attacks. Trust Protection Foundation allows a maximum clock skew of 180 seconds (3 minutes). Ensure the system time on your IdP and all Trust Protection Foundation servers is synchronized via NTP.

Unsigned SAML Responses

Trust Protection Foundation requires the entire SAML Response to be signed.

  • The Issue: Many IdPs only sign the assertion within the response by default.
  • The Fix: Verify your IdP application profile is explicitly configured to sign the full SAML Response.

Resolving Identity Mapping Failures

If the IdP successfully authenticates the user but the login is still rejected, the system is likely failing to map the SAML NameID to a user in your identity directory.

Ambiguous Identity Lookup

A match is only successful if the directory returns exactly one user for the provided NameID.

  • The Error: Ambiguous identity lookup by name id... Found identity entries: [local, LDAP...]
  • The Fix: Ensure you are using a unique identifier, such as User Principal Name (UPN). If your search expression is too broad, it may return multiple matches, causing the system to reject the assertion.

User Not Found (Manual Validation)

If the logs indicate no user was found, perform a manual search to verify your directory configuration:

  1. Log in to the web console using a local administrator account.
  2. Search for the exact string provided in the SAML NameID (e.g., user.name@domain.com).
  3. If the search returns no results, check the following:
    • Search Expressions: Ensure your Active Directory or LDAP User Search Expression includes the attribute you are passing. For UPN, the expression should include: (&(|(ANR=$search$)(userPrincipalName=$search$))(objectCategory=$userclass$))
    • Directory Values: Confirm that the attribute is actually populated in your directory. If you are mapping to an attribute like Employee ID, verify that the user record in LDAP contains that value.

Logout Behavior and Configuration

Trust Protection Foundation does not support SAML Single Log Out (SLO). Consequently, the Logout button is hidden by default when SAML is enabled.

To restore logout functionality:

  1. Identify the specific Logout URL provided by your IdP.
    Example (Azure): https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0
  2. Enter this URL in the Logout URL field on the authentication connector.
  3. Restart IIS on the UI server to make the Logout link visible in the user menu.