Troubleshooting
What do I need to provide to Citrix Support and Engineering when I open a SAML support case?
In the event you need assistance with a SAML-related issue, Citrix Support and Engineering requires the following information:
- Include sufficient context and describe your logon scenario and Citrix or Active Directory environment.
- Which Citrix eDocs you followed during initial configuration.
- Screenshots and details of your SAML application inside your IdP.
- Details of your Active Directory.
- A SAML-tracer file (
.json) file from the SAML tracer browser extension. - A HAR file (
.har) from your browser dev tools. - Details of both working and failing Workspace end users or Citrix Cloud admin users.
- The public caller IP of the machine performing a SAML logon to Workspace or Citrix Cloud.
Capture SAML Traces for Citrix Support and Engineering
Citrix Engineering and Support recommends the use of the SAML-tracer browser extension for all SAML debugging as well as .HAR files generated by browser developer tools. This extension is available for most common web browsers and exports .JSON files. The extension decodes SAML requests and responses into XML, which renders them human-readable and much easier to understand and debug.
How do I collect a HAR file from my browser to send to Citrix Support and Engineering?
For more information, see article Collect HAR file
Useful 3rd party SAML debugging tools
IMPORTANT:
Citrix does not provide any liability when 3rd party tools are used for debugging purposes. Use and access 3rd party tools and websites at your own risk.
| Tool | Purpose |
|---|---|
| https://www.samltool.io/ | Decodes base 64 SAML requests and responses |
| https://www.sslshopper.com/certificate-decoder.html | Decodes certificate data |
| https://www.rcfed.com/SAMLWSFed/MetadataCertificateExtract | Extracts Signing and Encryption certificates as files from SAML metadata |
| https://www.whatismyip.com/ | Provides the caller IP of the client that is attempting a SAML logon. |
Attribute Errors
Attribute errors might arise under any of the following conditions:
- The required attributes in your SAML configuration are not encoded correctly.
- The
cip_sidandcip_upnattributes are missing from SAML assertion. - The
cip_sidorcip_oidattributes are missing from the SAML assertion and Citrix Cloud can’t retrieve them from Active Directory due to a connectivity issue.
When an attribute error occurs, Citrix Cloud displays an error message that includes the faulty attributes.
To resolve this type of error:
-
Ensure that your SAML provider sends the required attributes with the correct encoding, as shown in the following table. At a minimum, either the SID or UPN attribute must be included.
Attribute Encoding Required cip_email Must be in String format ( user@domain)cip_oid Must be in Base64 or String format cip_sid Must be in Base64 or String format Yes, if not using cip_upncip_upn Must be String format ( user@domain)Yes, if not using cip_sid -
Verify the Cloud Connectors are online and healthy so Citrix Cloud can retrieve any missing attributes that it needs. For more information, see Cloud Connector advanced health checks.
Unexpected errors
Citrix Cloud might experience an unexpected error when:
- A user initiates a SAML request using an IDP-initiated flow. For example, the request is made by selecting a tile through the identity provider’s app portal instead of navigating directly to the workspace URL (
customer.cloud.com). - The SAML certificate is invalid or has expired.
- The authentication context is invalid.
- SAML assertion and response signature is mismatched.
When this error occurs, Citrix Cloud displays a generic error message.
If this error results from navigating to Citrix Cloud through an identity provider’s app portal, you can use the following workaround:
- Create a bookmark app in the identity provider’s app portal that references your workspace URL (for example,
https://customer.cloud.com). - Assign users to both the SAML app and the bookmark app.
- Change the visibility settings of the SAML app and the bookmark app so that the bookmark app is visible and the SAML app is hidden in the app portal.
- Disable the Federated Identity Provider Sessions setting in Workspace Configuration to remove additional password prompts. For instructions, see Federated identity provider sessions in the Citrix Workspace product documentation.
In this article
- What do I need to provide to Citrix Support and Engineering when I open a SAML support case?
- Capture SAML Traces for Citrix Support and Engineering
- How do I collect a HAR file from my browser to send to Citrix Support and Engineering?
- Useful 3rd party SAML debugging tools
- Attribute Errors
- Unexpected errors