[NOTE: This guide is specific to On-Premises Sysdig Monitor environments. If you are using cloud-based (SaaS) Sysdig Monitor, refer to this other guide instead.]

Introduction

SAML support in Sysdig Monitor allows authentication via your choice of Identity Provider (IDP). This document describes how to configure the feature as well as its limitations.

Summary of Functionality

Independent of the SAML feature, Sysdig Monitor ordinarily maintains its own user database to hold a username and password hash. The SAML feature instead allows for redirection to the customer’s IDP to validate username/password and other policies necessary to grant access to Sysdig Monitor. Upon successful authentication via SAML, a corresponding user record in Sysdig Monitor’s user database is automatically created, though the password that was sent to the IDP is never seen nor stored by Sysdig Monitor.

Once SAML is enabled, users can access your Sysdig Monitor app via https://HOSTNAME/api/saml (instead of https://HOSTNAME) and they will be redirected immediately to your IDP for authentication.

For those users that still try to access Sysdig Monitor at https://HOSTNAME, instead of their prior email/password login fields, they should begin their login procedure by clicking the SAML button as shown below.

Once clicked, the user's browser will be redirected to your IDP for authentication.

An alternative approach would be to leverage the optional steps described below to configure an IDP-initiated login login flow. With such a configuration, your users could select the Sysdig application from your IDP's app directory and not have to browse directly to https://HOSTNAME at all.

Summary of Configuration

To have SAML enabled for your environment, you will need to complete two steps:

Configure the Sysdig Monitor application in your IDP (see the IDP Configurations section below)
Apply SAML configuration to Sysdig Monitor, which can be done via a script (see the Configuring Sysdig Monitor section below)

Once these steps are completed, your users will be able to login to Sysdig Monitor via SAML as described above.

Also, if you intend to configure IDP-initiated login flow, before starting your IDP configuration, follow the instructions in this article to retrieve your customer ID number. As you are running On-Premises software, this number will very likely be 1. It will be referenced in later configuration steps as CUSTOMER-ID-NUMBER.

Limitations

SAML Assertion Encryption/Decryption is not currently supported.
SAML Single Logout is not supported. Therefore, users should take care to logout directly from Sysdig Monitor.

IDP Configurations

The following sections describe the configuration you'll need to complete with your IDP:

Okta
OneLogin

These are the IDPs for which Sysdig has performed detailed interoperability testing and confirmed the specifics of what you'll need to do relative to their standard docs. If your IDP is not listed here, it will likely still work with Sysdig Monitor as well. If you are using another provider, contact Sysdig Support and mention what IDP you are using.

To ensure the metadata URL you copy at the end of the IDP configuration procedure is correct, you can test it by directly accessing it via your browser. When accessing the URL, your browser should immediately download an XML file that begins similarly to the example shown below. No entry of credentials or other security measures should be required to successfully download it. If this is not the case, revisit the IDP configuration steps.

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://app.onelogin.com/saml/metadata/680358">
  <IDPSSODescriptor xmlns:ds="http://www.w3.org/2000/09/xmldsig#" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">names:tc:SAML:2.0:metadata" entityID="https://app.onelogin.com/saml/metadata/680358">
  ...

IDP Configuration - Okta

Configure Sysdig Monitor as a SAML application using Okta's documentation for Setting Up a SAML Application in Okta. The notes below call out specific steps that require additional action.

At step #6, if you don't intend to configure IDP-initiated login flow, check the box for "Do not display application icon to users"

At step #7, enter the values shown in the table below, replacing HOSTNAME with the hostname through which your users access the Sysdig Monitor application and PORT with the TCP port # (typically 443). If you wish to configure IDP-initiated login flow, use the CUSTOMER-ID-NUMBER retrieved as described in this article.

Setting	Value
Single sign on URL	https://`HOSTNAME`:`PORT`/api/saml/auth
Audience URI (SP Entity ID)	https://`HOSTNAME`:`PORT`/api/saml/metadata
Default RelayState (optional - only configure if you intend to use IDP-initiated login flow)	#/&customer=`CUSTOMER-ID-NUMBER`

IMPORTANT: You must include the port number even though port 443 is the typical default for https:// URLs.

At step #8, instead of those shown in the Okta example, add the values:

Name	Value
email	user.email
first name	user.firstName
last name	user.lastName

Note that the attributes are case sensitive, so use caution when entering them.

Only "email" is required. However, including first/last name is recommended, since these values will now be included in the records created in the Sysdig Monitor database when new users successfully login via SAML for the first time.

At step #10, copy the contents of the Identity Provider metadata link and save it for later. This is the metadata URL that will need to be configured into Sysdig Monitor at the next step for your SAML configuration to be completed.

IDP Configuration - OneLogin

Configure Sysdig Monitor as a SAML application using OneLogin's documentation for How to Use the OneLogin SAML Test Connector. The notes below call out specific steps that require additional action.

At the step for "Adding the SAML Test Connector", select SAML Test Connector (IdP w/ attr w/ sign response). If you don't intend to configure IDP-initiated login flow, uncheck the slider so it will no longer be "Visible in portal".

At the "Test Connector Configuration Page", enter the values shown in the table below, replacing HOSTNAME with the hostname through which your users access the Sysdig Monitor application and PORT with the TCP port # (typically 443).

Field	Value
RelayState (optional - only configure if you intend to use IDP-initiated login flow)	#/&customer=`CUSTOMER-ID-NUMBER`
Recipient	https://`HOSTNAME`:`PORT`/api/saml/auth
ACS (Consumer) URL Validator	https://`HOSTNAME`:`PORT`
ACS (Consumer) URL	https://`HOSTNAME`:`PORT`/api/saml/auth

IMPORTANT: You must include the port number even though port 443 is the typical default for https:// URLs.

(optional) If you want the user's First Name and Last Name to be included in the records created in the Sysdig Monitor database when new users successfully login via SAML for the first time, click to the "Parameters" tab. Click "Add parameter" and to create each of two New Fields, checking the box each time to "Include in SAML assertion". Then click to Edit each field and select the Value shown from the drop-down menu before clicking Save.

Field Name	Value
first name	First Name
last name	Last Name

Note that the Field Names are case sensitive, so be careful to enter them as all lowercase.

The following shows an example of a correctly-configured field for First Name:

Click to the "SSO" tab, copy the Issuer URL, and and save it for later. This is the metadata URL that will need to be configured into Sysdig Monitor at the next step for your SAML configuration to be completed.

Configuring Sysdig Monitor

The SAML configuration in Sysdig Monitor can now be completed via the administrative API using the set_saml_config.sh script (which can be downloaded from the sysdig-cloud-scripts repository on GitHub.) The following table describes the values you'll be prompted for:

Setting	Description
API URL	The URL through which your users access the Sysdig Monitor application. Unlike the IDP configuration, there's no need to include the port if it's standard https:// access via port 443.
Admin API Token	The Sysdig Monitor API Token for the "Super" Admin user (see this article for info on locating this user) as copied from the Settings page of the Sysdig Monitor application. This is required in order to apply the configuration via the API.
Metadata URL	The metadata URL from your IDP that you saved in the earlier IDP Configuration step.
Signed SAML assertion?	This setting must match with your IDP configuration. Testing has found that with Okta, this can be set to "true", but with OneLogin it must be set to "false".
Customer ID #	As an on-premises customer, you will enter the value "1".
Email parameter name	The Field Name your IDP attaches to the email address that will act as the user's login. Testing has found that with Okta, the default of "email" is fine, but with OneLogin, it must be set to "User.email".

The script will then show a curl command-line executed against the Sysdig Monitor API. If successful, you will see an HTTP/1.1 200 OK response code and a JSON object will be shown that reflects the modified SAML configuration.

Example script run:

# ./set_saml_config.sh
Enter API URL [https://app.sysdigcloud.com]: https://example.com
Enter Admin API Token (required): xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb
Enter Metadata URL from IDP (required): https://dev-123456.oktapreview.com/app/abcdefghijklmnopqrst/sso/saml/metadata
Require signed SAML assertion? [true]:
Enter Customer ID # (required): 1
Email parameter name [email]:
+ curl -XPOST -v -k https://example.com/api/admin/customer/1/saml/ -H Content-Type: application/json; charset=UTF-8 -H Accept: application/json, text/javascript, */*; q=0.01 -H Authorization: Bearer xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb --data-binary {"metadataUrl": "https://dev-123456.oktapreview.com/app/abcdefghijklmnopqrst/sso/saml/metadata", "signedAssertion": "true", "emailParameter": "email" } --compressed
[...verbose output...]
< HTTP/1.1 200 OK
[...verbose output...]
{"saml":{"metadataUrl":"https://dev-123456.oktapreview.com/app/abcdefghijklmnopqrst/sso/saml/metadata","validateSignature":true,"emailParameter":"email","signedAssertion":true}}

A get_saml_config.sh script is also available that can be used to view the current JSON config object.