SAML troubleshooting tips

If your SAML SSO integration is not working, here are some things you can try.

Check the Venafi Platform logs. Venafi Platform has very detailed logging for SAML Authentication when an error is encountered. Start with the Venafi Configuration Console Log Viewer. For example:

1. In Venafi Configuration Console, Expand the Venafi Event Viewer node.
2. Right-click on Custom Views and click Create Custom View.
3. In the Logged field, choose Last Hour.
4. For Event Sources, choose the parent SAML Group node, then click OK.
5. Give the custom view a Name, like SAML Last Hour and place it in the Custom Views container.

You now have an easy to use log view for troubleshooting SAML issues.

Enable Debug Logging for your UI Server. In Policy Tree on the Platform tree, you can select your servers that have "Web Console" enabled and activate debug logging temporarily. Additional logs will be stored, like your SAML Assertion, which is helpful for understanding what was sent and received between Venafi Platform and the SAML Identity Provider (IDP).

Make sure your FQDNs are configured. By default, email notifications and your SAML configuration use your windows machine hostname to build URLs. This is typically not the URLs you want to use in either lab or production environments. Instead, we recommend putting in a fully qualified domain name (FQDN) that matches the trusted Venafi Operational Certificate you have installed on Venafi Platform. Once this is set, you may need to re-export your Service Provider Metadata XML file from the Authentication node of the Venafi Configuration Console, and use the updated file to re-configure your settings with the Identity Provider.

Type the correct domain name in your browser. If your Venafi Platform is configured to use platform.example.com don't use the machine's IP address or localhost when accessing your SAML-enabled server. An error can occur, because Venafi Platform will redirect you to your identity provider. Your IDP will generate a signed SAML response using the domain name you configured (for example, platform.venafi.com) If the domain name that your IDP uses is not the same as the one you entered in your browser, Venafi Platform will reject the SAML response from your IDP for security reasons.

Check the value in the NameID within the subject section of the SAML assertion of your SAML Response. A SAML Response can be several hundred lines long, but in every response you should see a basic structure to include a NameID that tells your server "this is the user who I am authenticating."

You should know what type of identification you are using to identifying users. We recommend using a User Principle Name (UPN) because it always uniquely identifies a user within a given directory. However, there are other alternatives.

When looking at the SAML response, you're looking for two things:

1. Check that the SAML Response NameID matches the user identifier you are expecting. If yes, go to the next step.

2. Turn off SAML on Venafi Platform and authenticate to Aperture as a user from that Identity Provider. For example, if your IDP uses Active Directory, try logging in to Aperture with a valid AD user and password. Once in Aperture, take the string from the NameID and try to search from the user. In our example, search for a UPN of aaron.hixson@venqa.venafi.com. If there are no results, then you probably have one of the following problems:

   • Your User Search Expression for your Identity Provider doesn't include the attribute for user class objects that this attribute is stored on.

     For example, for UPN you didn't change your Active Directory user search expression to: (&(|(ANR=$search$)(userPrincipalName=$search$))(objectCategory=$userclass$))

   • If using Active Directory, you may have expected the attribute to be included in your directory's "Ambiguous Name Resolution" (ANR). By default, Venafi Platform's Active Directory driver searches for users using ANR. While Microsoft documents what the default attributes are for ANR, your Active Directory Administration team may have removed or added attributes that are different from Microsoft's default settings.
   • Your identity directory does not have the values you think it does. Let's say for example your Identity Provider has employee ID, and you thought Active Directory or LDAP also had an employee ID, if that is not the case, you should switch to a different unique attribute like Universal Principal Name (UPN). As mentioned before, a good test is to log into Aperture and try to search for the user using the desired attribute, if nothing shows up, then that problem needs to be resolved first.

Ensure you are using a unique identifier. If you are trying to use something like email, username, or SAMAccountName as the value in your NameID, it's possible that these values are returning multiple results when Venafi Platform searches your IDP's directory. When an Identity search returns multiple entries, the SAML Assertion is rejected because the lookup for a user is ambiguous. A match will only be made if there is one—and only one—user that matches the NameID of the SAML Assertion subject.

When looking at the log, if you see a log event similar to the following, this is likely your problem.

Your IDP is not signing the SAML Response. Venafi Platform requires SAML Responses to be signed, but with the exception of Okta, all of the IDPs that Venafi supports, by default, only sign the assertion within the response. When setting up your IDP to work with Venafi Platform, make sure Venafi Platform's application profile is configured to sign the response.

Time Sync Problem. Venafi Platform requires that the SAML Assertion include the NotOnOrAfter parameter within the SubjectConfirmationData of the assertion. This is to prevent the possibility of misuse of the signed XML document. Venafi Platform allows for a clock skew of 180 seconds (3 minutes). Check to make sure that the system time of your IDP and the system time of your Venafi servers are all accurate.

Other tips and information

• We suggest you try the Firefox SAML Tracer Extension, a valuable tool that picks through the network traffic and highlights the SAML XML documents that Venafi Platform and your SAML IDP are sending back and forth through your browser. While you can get this information if Venafi Platform is in Debug Mode, and you look through the logs, this extension provides real-time information, which is faster and simpler than using the system logs. In addition, in some customer environments, Debug Mode isn't allowed or is not a practical solution.

  TIP  Make sure you have the extension open before you visit your IDP or Venafi Platform's web console. The SAML Tracer Extension only captures traffic when the extension window is open.

• If you're looking for the Logout button in Venafi Platform's navigation, you should know that the Logout button isn't visible when SAML single sign-on is enabled. In Venafi Platform 24.1, we don't support SAML Single Log Out (SLO). What we do support is a Logout URL. If your IDP supports ending the session by simply visiting a URL, you can place that URL in the Logout URL field. After you set this, restart IIS and you should see the Logout link in the User menu of the Venafi Platform web console.

  As far as we know, Azure may be the only supported IDP that permits logging out by just visiting a URL. Azure users can use the following Logout URL:

  Copy

  https://login.microsoftonline.com/common/wsfederation?wa=wsignout1.0