If you're an enterprise customer using a dedicated or on-premises Backtrace instance, you can configure your instance to authenticate with Single Sign-On (SSO) via a SAML provider.

For dedicated Backtrace-hosted Instances

Please contact your Backtrace rep and let them know you're interested in integrating with a SAML provider.  We'll need to set things up on the back-end for you.  

Information that we'll need from you:

  • Your IdP endpoint

Once set up, we will provide you with the following to configure within your SAML provider:

  • Issuer ID
  • An ACS URL
  • NameID format (this will usually be e-mail)

Also make sure that encrypted assertions are disabled.

For On-Premises Backtrace Instances

Install Node.JS.

Please see https://nodejs.org/en/download/package-manager/

Install backtrace-saml package

Ask you backtrace rep for a copy of the backtrace-saml package.

Extract this archive into /opt/backtrace. You should see a bunch of files under /opt/backtrace/backtrace-saml.

The archive includes:

  • bin/login.js - This is the main backtrace-saml script.
  • Service files for systemd - this will launch login.js via Node.JS with the correct settings.
  • A default saml.json configuration file.

Configure saml.json

Under tenants, add an entry for the hostname component that end users will navigate to log into the coronerd instance.

In the following examples:

  • The backtrace-saml service and coronerd service are running on separate systems (see "additional notes" below for information on running them on the same box).
  • The hostname for the coronerd service is "bt-coronerd.mycompany.com"
  • The hostname and IP for the backtrace-saml service is "bt-saml.mycompany.com" and 192.168.55.1.
  • We're using an example Google SAML-style IdP entry point.

For this configuration, backtrace-saml should look like:


{
  "tenants" : {
    "bt-coronerd.mycompany.com" : {
      "entryPoint": "https://accounts.google.com/o/saml2/idp?idpid=xxxx",
      "issuer" : "https://bt-saml.mycompany.com"
    }
  },

  "url" : "https://bt-saml.mycompany.com",

  "bind" : {
    "port" : 443,
    "ssl" : {
      "key" : "/path/to/cert.key",
      "certificate" : "/path/to/cert.cert"
    }
  }
}

The key name immediately underneath tenants should match the hostname of your cortonerd instance.

The entryPoint field under the tenant specifies the URL that the end-user will navigate to in order to login. In the example above, we're using Google, but you'll need to change this to whichever entry point URL your provider requires.

The issuer field should be set to the URL of where you installed backtrace-saml.

The bind field is self-explanatory. The SAML service will need to listen on a publicly accessible IP address and port. You will be required to use SSL and should be able to recycle the coronerd certificate if the same hostname can be used for the SAML service, or a wildcard certificate is used.

Enable SAML in /etc/coronerd/coronerd.conf.

Add the following top-level stanza in coronerd.conf:

"saml" : {
        "provider" : "https://bt-saml.mycompany.com"
},

Note that provider must be a URL that matches issuer as configured in saml.json above. 

You also need to ensure that the IP address the SAML host is on is authenticated with coronerd. This can be configured as such (as a top-level stanza).

"httpd" : {
"authenticated" : [ "127.0.0.1:", "192.168.55.1:" ]
},

Restart coronerd and now you should see a "Sign in with SSO" button. 

Install backtrace-saml.service into systemd

Don't forget to reload the systemd daemon to pick up the new service file.

systemctl daemon-reload 

Start the service

You are now ready to start the service.

service backtrace-saml start 

Verify that the service is up by navigating to the URL you specified. If it's up, you should get a redirect to the main Backtrace website. If any changes are made to saml.json (which should be in that same directory), the service must be restarted.

Verify that login works. Logs are available in syslog.

SAML Provider configuration

Within your SAML provider, you'll need to ensure:

  1. SAML encrypted assertions are unsupported. We use SSL, but we don't use encrypted assertions along with SSL at the moment.
  2. You must configure your SAML provider to use an ACS URL of the form https://X/saml/<hostname of your coronerd instance>.  Note that X must match the hostname of issuer. For example, if issuer was https://bt-saml.mycompany.com then the ACS URL that you should use is: https://bt-saml.mycompany.com/saml/bt-coronerd.mycompany.com/.
  3. Use primary e-mail address for the NameID.

Additional notes for running backtrace-saml and coronerd on the *same* box.

coronerd must use port 443, so you'll need to bind backtrace-saml to a different port when running on the same machine as a coronerd service.  In the examples below, we'll use port 6100.

Make the following changes to your saml.json config file:

  • Change the bind : port  to 6100.
  • Append :6100 to the url.  (Do not append the port number to the issuer ). 
  • In coronerd.conf, append :6100 to saml : provider .  
  • Make sure your coronerd IP address is listed in coronerd.conf's authenticated  section.
  • In your SAML Provider configuration, append :6100 to the hostname of the ACS URL.

Example saml.json:

{
  "tenants" : {
    "bt-coronerd.mycompany.com" : {
      "entryPoint": "https://accounts.google.com/o/saml2/idp?idpid=xxxx",
      "issuer" : "https://bt-saml.mycompany.com"
    }
  },

  "url" : "https://bt-saml.mycompany.com:6100",

  "bind" : {
    "port" : 6100,
    "ssl" : {
      "key" : "/path/to/cert.key",
      "certificate" : "/path/to/cert.cert"
    }
  }
}

Example coronerd.conf excerpt (here, 192.168.55.1 is the IP of both coronerd and backtrace-saml):

...
"saml" : {
        "provider" : "https://bt-saml.mycompany.com:6100"
},
...
"httpd" : {
"authenticated" : [ "127.0.0.1:", "192.168.55.1:" ]
},
...

Troubleshooting

  • Make sure encrypted assertions are disabled within your SAML Provider configuration.
  • Make sure you're using primary e-mail address as your NameID format.
  • Make sure that your certificates are properly configured within saml.json and have the proper CNAMES for your backtrace-saml host.
  • If you are seeing the error "Failed to login - Internal Error", make sure the IP address if your backtrace-saml service host is listed within the authenticated  section of coronerd.conf, as outlined in "Enable SAML in /etc/coronerd/coronerd.conf" above.
  • When running backtrace-saml and coronerd on the same machine, make sure that the saml service is binding to a port different than port 443 within saml.json.  In addition, this port must be specified in the within the url  setting in saml.json (but not in issuer ), as well as within the saml : provider  setting in coronerd.conf. You must also specify the port within the ACS URL that you configure in the SAML Provider side.
Did this answer your question?