Troubleshoot SAML issues in Puppet Enterprise 2021.0 and later

If your SAML integration isn’t working, gather logging and browser information while reproducing the issue. Review the information to troubleshoot for common issues such as URL mismatches or a group mismatch.

Version and installation information

PE version: 2021.0 and later
OS: Any
Installation type: Any

Solution

Use these steps to:

• Enable logging for SAML
• Increase the console services log level to debug
• Reproduce the issue and capture a HAR file
• Revert SAML logging and console services log levels
• Collect console logs and configuration information
• Review the gathered information for common issues

Complete all steps on the primary server unless otherwise noted.

1. Enable SAML logging. Open /etc/puppetlabs/console-services/logback.xml and uncomment the SAML logging configuration.

   Change the following:

   <!-- Uncomment to log SAML configuration and negotation -->
   <!-- <logger name="com.onelogin" level="trace" /> -->
   <!-- <logger name="puppetlabs.rbac.services.http.saml" level="DEBUG" /> -->

   To this:

   <!-- Uncomment to log SAML configuration and negotation -->
   <logger name="com.onelogin" level="trace" />
   <logger name="puppetlabs.rbac.services.http.saml" level="DEBUG" />

2. Enable debug logging for console services manually or with a task.

   To enable debug logging manually, open /etc/puppetlabs/console-services/logback.xml and change root level from info to debug.

   Change the following:

   <root level="info">

   To this:

   <root level="debug">

3. Reproduce the issue and capture a HAR file. To help find information in logs, note the time that the issue is reproduced.

4. Revert SAML logging and console services log levels. If you leave logging at debug, it might expose sensitive information.

5. Collect console logs. Run the support script, limiting the logs and configuration files captured to the console by using the --only option. Run:

   /opt/puppetlabs/bin/puppet enterprise support --v3 --only pe.console

   A tarball is generated in /var/tmp/ (by default). Please check the logs for sensitive information before sending them to the Support team.

6. Review the gathered information and check for common issues.

   The most common issue is a 404 error due to mismatched URLs, often when interacting with CNAME entries. If that’s the case, there are two parameters that can be set in the PE Console node group under the puppet_enterprise::profile::console class,: saml_host and saml_port. To fix the issue, override the saml_host value with the correct FQDN and optionally the saml_port value (as needed) and run the puppet agent on the primary server.

   If there is an error with unknown attributes or permissions, there might be a group mismatch that’s preventing user-group bindings. Check your group lookup attributes.

   If you’re having trouble identifying or solving the error, please open a ticket, and attach the console logs and HAR file you collected.