SAML (On-Prem)

These instructions are specific to On-Premises Deployments of the Sysdig platform. If you are using the cloud-based (SaaS) Sysdig platform, refer to SAML (SaaS) instead.

SAML support in the Sysdig platform allows authentication via your choice of Identity Provider (IdP).

The Sysdig platform ordinarily maintains its own user database to hold a username and password hash. SAML instead allows for redirection to your organization’s IdP to validate username/password and other policies necessary to grant access to Sysdig application(s). Upon successful authentication via SAML, a corresponding user record in the Sysdig platform’s user database is automatically created, though the password that was sent to the IdP is never seen nor stored by the Sysdig platform.

This section describes how to integrate and enable SAML with both Sysdig Monitor and Sysdig Secure.

For specific IdP integration information, refer to:

See also Caveats, below.

Basic Enablement Workflow

Step

Options

Notes

1. Know which IdP your company uses and will be configuring.

These are the IdPs for which Sysdig has performed detailed interoperability testing and confirmed how to integrate using their standard docs.

If your IDP is not listed, it may still work with the Sysdig platform. Contact Sysdig Support for help.

2. Decide the login flow you want users to experience (choose from three options):

Click SAML button

From https://HOSTNAME/ or https://HOSTNAME/secure/

Type/bookmark a URL in browser

Monitor:https://HOSTNAME/api/saml

Secure: https://HOSTNAME/api/saml?product=SDS

Log in from an IdP interface

The individual IdP integration pages describe how to add Sysdig to the IdP interface.

You will need your Sysdig customer number on hand. Normally 1 for on-premises.

3. Perform the configuration steps in your IdP interface and collect the resulting config attributes.

Collect metadata URL (or XML) and test it.

If you intend to configure IDP-initiated login flow, have your Sysdig customer number on hand. It will be referenced in later configuration steps as CUSTOMER_ID_NUMBER. Normally 1.

4 a. Log in to Sysdig Monitor (as "super" admin) and enter the necessary configuration information in the UI. Enable SAML as your SSO.

4b. Log in to Sysdig Secure (as "super" admin) and repeat the above.

 

Administrator Steps

Configure IdP

Select the appropriate IdP from the list below, and follow the instructions:

UI-Based: Configure SAML in Settings

At this time, the Authorization UI is available only for Sysdig Monitor.

To enable baseline SAML functionality:

Enter SAML Connection Settings

  1. Log in to Sysdig Monitor or Sysdig Secure as administrator and select Settings.

  2. Select Authentication.

  3. Select the SAML tab.

  4. Enter the relevant parameters (see table below) and click Save.

It is strongly recommended that "Signed Assertion" and "Validate Signature" are enabled to ensure that the SAML SSO process is as secure as possible.
Connection SettingOptionsDescriptionSample Entry
MetadataURLThe URL provided at the end of the IdP configuration steps.
XMLAn option that can be used for an IdP that doesn’t support extracting metadata XML via URL.
Signed Assertionoff/onShould Sysdig check for assertions signed in responses (to assist in validating correct IdP).ON
Email ParameteremailName of parameter in the SAML response for user email ID. Sysdig uses this to extract the user’s email from the response.email
Validate Signatureoff/onSysdig backend should verify that the response is signed.ON
Verify Destinationoff/onFlag to control whether Sysdig should check the “destination” field in the SAMLResponse. Recommend ON, as a security measure. May be OFF in special cases, such as a proxy in front of the Sysdig back end.ON
(Optional) Inactive Session Expirationoff/onSpecify the period of time a user can be inactive before the authenticated session will be suspended. See Configure Customized Session Expiration.ON

Select SAML for SSO

  1. Select SAMLfrom the Enabled Single Sign-On dropdown

  2. Click Save Authentication.

  3. Repeat entire enablement process for Sysdig Monitor or Sysdig Secure, if you want to enable on both applications.

Script-Based: Configure SAML Using Scripts

The configuration of the SAML feature can be viewed, updated, and deleted by the “super” Admin. A saml_config.sh helper script is available in the SSO folder at sysdig-cloud-scripts repository to assist in completing this configuration. Invoking the script with no options will display help text.

# ./saml_config.sh
Must specify the Sysdig App whose SAML configuration will be viewed/set

Usage: ./saml_config.sh [OPTIONS]

Affect SAML login settings for your Sysdig software platform installation

If no OPTIONS are specified, only the help output is displayed.

To use the helper script, modify env.sh to set the required values for API_TOKEN of the “super” Admin user and the URL for accessing the Sysdig platform API (which will be the same URL that your users access for the Sysdig Monitor application).

Depending if the API_TOKEN has been obtained from the Sysdig Monitor or Sysdig Secure application UI, the settings will be applied to the relevant product.

Initially no SAML settings are set. A initial run of the script would confirm that:

# ./saml_config.sh
No saml settings are set
Run for further info: ./saml_config.sh -h

Add the -s option to set the SAML configuration for a particular Sysdig application. When setting the config, you’ll also include the metadata URL you saved in the earlier IDP configuration step (-m option) and specify the name of a supported IDP configuration (-i option), which will tailor other details of your SAML configuration to the specifics of that IDP. If the configuration is successfully posted to the Sysdig platform, the new configuration will be echoed back.

An example of creating the two separate SAML configurations for both Monitor and Secure, each using Okta IDP settings:

# ./saml_config.sh -s -m 'https://dev-824158.oktapreview.com/app/exkfpgqiskSoGZrjE0h7/sso/saml/metadata' -i okta
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547539750000,
    "type": "saml",
    "scope": "SYSTEM",
    "settings": {
      "metadataUrl": "https://dev-824158.oktapreview.com/app/exkfpgqiskSoGZrjE0h7/sso/saml/metadata",
      "metadata": null,
      "validateSignature": true,
      "emailParameter": "email",
      "signedAssertion": true,
      "verifyDestination": true,
      "createUserOnLogin": true
    }
  }
}

If you are using an IDP other than those available with the -i option, contact Sysdig Support for assistance with determining the correct settings.

Once you’ve completed this configuration, clicking the SAML button at the login screen of the appropriate Sysdig application(s) should redirect to your IDP for authentication.

If you wish to delete your SAML configuration, invoke the -d option. If successful, the disabled configuration will be printed.

# ./saml_config.sh -a monitor -d
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547539750000,
    "type": "saml",
    "scope": "SYSTEM",
    "settings": {
      "metadataUrl": "https://dev-824158.oktapreview.com/app/exkfpgqiskSoGZrjE0h7/sso/saml/metadata",
      "metadata": null,
      "validateSignature": true,
      "emailParameter": "email",
      "signedAssertion": true,
      "verifyDestination": true,
      "createUserOnLogin": true
    }
  }
}

Configure SAML Single Logout

Sysdig supports SAML Single Logout (SLO).

SLO is a feature in federated authentication where Sysdig users can sign out of both their Sysdig session (Service Provider) and associated IdP (Identity Provider) simultaneously. SLO allows you to terminate all sessions established via SAML SSO by initiating a single logout process. Closing all user sessions prevents unauthorized users from gaining access to Sysdig resources.

SLO Process

When a user initiates a logout, Sysdig sends a digitally-signed logout request to the IdP. The IdP validates the request and terminates the current login session, then redirects the user back to the Sysdig login page.

Caveats

  • SLO is currently supported only in US-West and EU-Central regions.

  • Sysdig does not support HTTP Post binding for single logout, and therefore, SLO with Okta is not functional at this point.

Configure IdP

  1. Configure logout URLs:

    • Monitor: <base_URL>/api/saml/slo/logout

    • Secure: <base_URL>/api/saml/slo/secureLogout

  2. Choose HTTP Redirect as the binding method.

    This option is an alternative to the HTTP POST method, which Sysdig does not support currently.

  3. If your IdP mandates, upload the public key for Sysdig.

    Contact Sysdig Support to retrieve the public key associated with your deployment.

    Certain IDPs, such as Azure, don’t require uploading the public key.

Configure Sysdig

  1. Log in to Sysdig Monitor or Sysdig Secure as an administrator and select Settings.

    For on-prem deployments, log in as the super admin.

  2. Navigate to Settings > Authentication, and select SAML under Connection Settings.

  3. Enter the SAML configuration.

  4. Ensure that Enable SAML single logout is toggled on.

  5. Click Save.

  6. Ensure that you select SAML from the Enable Single Sign On drop-down.

Optional: Auto-creation of user records

When a user successfully authenticates via SAML, if a user record does not yet exist in the Sysdig platform database for their email address, one will be created at that time (default behavior). Some environments may not like this approach and may instead only want to permit logins for users whose records already exist (such as may have been already created via email invite or creation via the API).

To disable the auto-creation of user records after SAML authentication, add the -n option to your command line when applying your settings. This will set createUserOnLogin to false .

# ./saml_config.sh -s -n -m 'https://dev-824158.oktapreview.com/app/exkfpgqiskSoGZrjE0h7/sso/saml/metadata' -i okta
{
  "authenticationSettings": {
    "id": 2,
    "version": 1,
    "createdOn": 1547539856000,
    "type": "saml",
    "scope": "SYSTEM",
    "settings": {
      "metadataUrl": "https://dev-824158.oktapreview.com/app/exkfpgqiskSoGZrjE0h7/sso/saml/metadata",
      "metadata": null,
      "validateSignature": true,
      "emailParameter": "email",
      "signedAssertion": true,
      "verifyDestination": true,
      "createUserOnLogin": false
    }
  }
}

User Experience

As noted in the Basic Workflow, above, you can offer users three ways to log in with a SAML configuration:

  • They can begin at the Sysdig SaaS URL and click the SAML button.

    In the US East, Monitor: https://HOSTNAME/ or Secure: https://HOSTNAME/secure/.

    See SaaS Regions and IP Ranges for URLs for other regions.

    They will be prompted to enter a Company Name, so the Sysdig platform can redirect the browser to your IdP for authentication.

  • You can provide an alternative URL to avoid the user having to enter a company name, in the format:

    Sysdig Monitor: https://<HOSTNAME>/api/saml

    Sysdig Secure: https://<HOSTNAME>/api/saml/secureAuth

    This format is for the US East region. See SaaS Regions and IP Ranges for URLs for other regions.

  • You can configure an IdP-initiated login flow when configuring your IdP. The users then select the Sysdig application from your IDP’s app directory and do not browse directly to a Sysdig application URL at all.

Users that complete their first successful SAML login to Sysdig Secure may receive the error message “User doesn’t have permission to login in Sysdig Secure”. This is because only members of the Secure Operations team are permitted access to Sysdig Secure, and newly-created logins are not in this team by default. Such a user should contact an Administrator for the Sysdig environment to be added to the Secure Operations team.

Environments that wish to have all users access Secure by default could use this example script to frequently “sync” the team memberships.

See also User and Team Administration for information on creating users.

Caveats

  • SAML Assertion Encryption/Decryption is not currently supported.

  • SAML Single Logout is not supported. Therefore, users should take care to log out directly from Sysdig application(s).