Authentication and Authorization (On-Prem Options)

• 1: Google OAuth (On-Prem)
• 2: SAML (On-Prem)
• 2.1: Okta (SAML On-Prem)
• 2.2: OneLogin (SAML On-Prem)
• 2.3: Azure Active Directory (SAML On-Prem)
• 2.4: ADFS (SAML On-Prem)
• 3: OpenID Connect (On-Prem)
• 3.1: Okta (OpenID On-Prem)
• 3.2: OneLogin (OpenID On-Prem)
• 3.3: Keycloak (OpenID On-Prem)
• 3.4: Azure (OpenID On-Prem)
• 4: LDAP
• 4.1: LDAP Authentication Configuration (for Platform v.1586+)
• 4.2: LDAP Authentication Configuration (for Platform v.1149 - 1511)
• 4.3: Mapping LDAP Users to Sysdig Teams
• 4.4: LDAP/SAML Hybrid Authentication
• 5: Disable Password Authentication
• 6: Configure Split DNS

This section is for the Sysdig On-Premises software platform only. If you are using SaaS (cloud-based) Sysdig applications, see Authentication and Authorization (SaaS) instead.

Sysdig Monitor and Sysdig Secure are designed to work with several user authentication/authorization methods:

Type	Enabled by Default	Integration Steps Required
User email/password	Yes	No
Google OAuth	No	Yes
SAML	No	Yes
OpenID Connect	No	Yes
LDAP	No	Yes

A sample user’s view:

The pages in this section describe the integration and enablement steps required for SAML or OpenID Connect, and the Identity Provider (IdP) services that support these protocols, such as Okta, OneLogin, Keycloak.

In the SaaS environment, Googlelogin can be enabled with a simple drop-down selection; the integration has already been performed.

To enable a third-party authentication method for both Sysdig Monitor and Sysdig Secure, you must configure the SSO settings separately for each.

Workflow

With the new Authorization UI, the basic process of enabling a Single Sign-On (SSO) option is:

1. Determine which SSO option (GoogleOAuth, SAML, OpenID, LDAP) your enterprise uses, and which IdP service (Okta, OneLogin, etc.) is used if any.

2. Configure any associated IdP settings on the IdP side.

3. Enter the required connection settings for the chosen SSO on the appropriate Authentication tab in Sysdig Settings.

   You can also configure the settings using a script, if preferred.

4. Select the SSO option from the Enabled Single Sign-On drop-down and click Save Authentication.

5. If enabling for both Sysdig Monitor and Sysdig Secure, perform the necessary steps on the second application.

View of the Authentication page for Google OAuth in the on-prem environment.

1 - Google OAuth (On-Prem)

Google supports OAuth 2.0, which allows users to log in to third-party applications such as Sysdig using Google credentials. By default, the created user will not have Admin rights within the Sysdig application, though these rights can be subsequently assigned.

Prerequisites

The Sysdig platform on-premises installation must have a DNS name associated with it. Google does not support applications that do not have an associated DNS name.

DNS Name

Replicated

For Replicated-based installations, enter your Hostname in the Settings tab.

Kubernetes

For Kubernetes-based installations, ensure the api.url ConfigMap element contains your hostname (older installations), or use the sysdig.dnsname (newer Installer-based).

For the examples that follow, DNS_NAME refers to this hostname you configured in your platform settings.

In Google Console: Obtain OAuth Client Credentials

1. Log in to the Google API Console.

2. Create your project.

3. Select Credentials from the left-hand navigation, and choose the OAuth consent screen from the navigation bar.

4. When prompted, select Internal or External User Type and click Create.

   Choosing Internal will limit the users to those with accounts belonging to the same domain as the email used to create the project, e.g. mycompany.com. Note that if some of your users have a different domain, e.g. mycompany.uk, you will want to choose the External user type.

   

5. On the subsequent Oauth Consent screen, enter the required Email address and Product name, as well as other additional optional information, then click Save.

   

6. From the Credentials tab, click the Create Credentials drop-down and select OAuth client ID.

   

7. When prompted for Application type, select Web application, then enter the following parameters:

   • Name: Use a meaningful name, such as “Sysdig”.

   • Authorized Javascript Origins: Enter https://DNS_NAME:API_PORT

   • Authorized Redirect URLs: Enter one or more of the following values:

     If configuring Sysdig Monitor, enter: https://DNS_NAME:API_PORT/api/oauth/google/auth

     If configuring Sysdig Secure, enter: https://DNS_NAME:API_PORT/api/oauth/google/secureAuth

8. Click Create.

   A success message with client ID and client secret will be displayed. Copy these to a safe place, as you will need them in the next step.

   

Configure Settings in Sysdig Platform

There are three options for configuring OAuth settings on the Sysdig side: a UI page, scripts, or entries in your Replicated or Kubernetes orchestrator.

Option 1 UI-Based: Configure Google OAuth in Settings

To enable baseline Google Oauth functionality:

Enter Google OAuth Basic Settings

1. Log in to Sysdig Monitor or Sysdig Secure as “super” Admin and select Settings.

2. Select Authentication.

3. Select the Google OAuth tab.

   

4. Enter the relevant parameters and click Save.

   Application ID: the Client ID you were sent.

   Application Secret: the Client Secret you were sent

   URL Redirect:

   If configuring Sysdig Monitor, enter: https://DNS_NAME:API_PORT/api/oauth/google/auth

   If configuring Sysdig Secure, enter: https://DNS_NAME:API_PORT/api/oauth/google/secureAuth Allowed Domains: Comma-separated list of domains permitted to log in. For example, mycompany.com, myxompanyalias.com.

Select Google OAuth for SSO

1. Select Google Oauth from the Enabled Single Sign-On dropdown

2. Click Save Authentication.

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

Option 2 Script-Based: Configure OAuth Using Scripts

The configuration of the Google OAuth feature can be viewed, updated, and deleted by the “super” Admin. A google_oauth_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.

# ./google_oauth_config.sh -h
Usage: ./google_oauth_config.sh [OPTIONS]

Affect Google Oauth login settings for your Sysdig software platform installation

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 consequent product.

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

# ./google_oauth_config.sh
No google-oauth settings are set
Run for further info: ./google_oauth_config.sh -h

Add the -s option to set the Google Oauth configuration for a particular Sysdig application. When setting the config, you’ll use additional options to provide the config details you saved in the earlier Google Oauth step.

If the configuration is successfully posted to the Sysdig platform, the new configuration will be echoed back.

# ./google_oauth_config.sh -s -i "t2em0alq7l13n1hevua48ehieenkb06q.apps.googleusercontent.com" -e "ucP_WY908-k" -r "https://sysdigtest.com:443/api/oauth/google/auth" -a "[\"sysdig.com\"]"
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547709552000,
    "type": "google-oauth",
    "scope": "SYSTEM",
    "settings": {
      "clientId": "t2em0alq7l13n1hevua48ehieenkb06q.apps.googleusercontent.com",
      "clientSecret": "ucP_WY908-k",
      "redirectUrl": "https://sysdigtest.com:443/api/oauth/google/auth",
      "allowedDomains": [
        "sysdig.com"
      ]
    }
  }
}

Once you’ve completed this configuration, clicking the Google Login button at the login screen of the appropriate Sysdig application(s) should redirect to Google Oauth login page.

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

# ./google_oauth_config.sh -d
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547709552000,
    "type": "google-oauth",
    "scope": "SYSTEM",
    "settings": {
      "clientId": "t2em0alq7l13n1hevua48ehieenkb06q.apps.googleusercontent.com",
      "clientSecret": "ucP_WY908-k",
      "redirectUrl": "https://sysdigtest.com:443/api/oauth/google/auth",
      "allowedDomains": [
        "sysdig.com"
      ]
    }
  }
}

Option 3 Orchestrator-Based: Enter Settings Using Orchestrator

Replicated

If you used the Replicated infrastructure manager to install the Sysdig platform:

1. Log in to the Replicated Management Console, click to the Settings tab, then check the box to expand theAdvanced Settings.

2. Enter the Google OAuth client ID and Google OAuth client Secret in the appropriate fields.

3. (Optional) In a comma-separated list, enter the OAuth-allowed email domains that should be permitted to authenticate. If set, only Google users whose email addresses are in these domains will be able to login to your Sysdig installation. If this setting is left blank, any user that successfully authenticates via Google will be permitted to login to your Sysdig installation.

   

4. Click Save.The Sysdig platform will then restart to enable the settings.

Kubernetes

Enter the OAuth allowed domains, Client ID, and Client Secret into the appropriate elements of the Kubernetes ConfigMap. Use appropriate Kubernetes methods to push the updated settings and restart the backend containers to make the changes take effect.

User Experience

Note the following requirements for successful Google OAuth login:

For such a user to log in via Google OAuth, click the Log in with Google button.

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

2 - SAML (On-Prem)

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:

• Okta (SAML On-Prem)

• OneLogin (SAML On-Prem)

• Azure Active Directory (SAML On-Prem)

• ADFS (SAML On-Prem)

See also Caveats, below.

Basic Enablement Workflow

Administrator Steps

Configure IdP

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

• Okta (SAML On-Prem)

• OneLogin (SAML On-Prem)

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.

Select SAML for SSO

1. Select SAML from 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).

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
    }
  }
}

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.

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).

2.1 - Okta (SAML On-Prem)

Review SAML (On-Prem) before you begin.

Configure Sysdig Monitor and/or Sysdig Secure 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.

Sysdig-Specific Steps for Okta Configuration

IDP-Initiated Login Flow

If you don’t intend to configure IDP-initiated login flow, check the boxes for “Do not display application icon to users” and “Do not display application icon in the Okta Mobile app”.

SSO, URI, and RelayState Values

Enter the values shown in the table below, replacing HOSTNAME with the hostname through which your users access the Sysdig application(s) and PORT with the TCP port # (typically 443).

To configure IDP-initiated login flow, replace CUSTOMER-ID-NUMBER with the number retrieved as described in Find Your Customer Number. (Normally the Customer ID will be 1 in on-prem installations.)

Email and Name Values

Instead of those shown in the Okta example, add these values:

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 platform’s database when new users successfully login via SAML for the first time.

URL Metadata Value

Copy the URL and paste in the Metadata entry on the SAML Configuration page in the SAML connection settings.

Test Metadata (Optional)

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.

2.2 - OneLogin (SAML On-Prem)

Review SAML (On-Prem) before you begin.

Configure Sysdig Monitor and/or Sysdig Secure as a SAML application using OneLogin’s article titled Use the OneLogin SAML Test Connector. The notes below call out specific steps that require additional action.

Sysdig-Specific Steps for OneLogin Configuration

Adding the SAML Test Connector

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”.

Test Connector Configuration Page Settings

At the “Test Connector Configuration Page”, enter the values shown in the table below. If you wish to configure IDP-initiated login flow, replace CUSTOMER-ID-NUMBER with the number retrieved as described in the Find Your Customer Number article.

(Optional) If you want the user’s First Name and Last Name to be included in the records created in the Sysdig platform’s database when new users successfully login via SAML for the first time, click to the Parameters tab. Click Add parameter and 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.

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:

Issuer URL

Click to the SSO tab, copy the Issuer URL, and paste in the Metadata entry on the SAML Configuration page in the SAML connection settings.

Test Metadata (Optional)

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.

2.3 - Azure Active Directory (SAML On-Prem)

This topic explains how to configure SAML Single Sign On (SSO) with Azure Active Directory (AD) and helps you configure Sysdig to allow users to access Sysdig application by using SSO.

Prerequisites

Administrator privileges on Sysdig and Azure.

Configure the Sysdig Application in Azure AD

1. Log in to the Azure AD portal.

2. Select Azure Active Directory, then click Enterprise Applications.

   The Enterprise applications - All application screen is displayed.

3. Click New Application.

4. On the Add an Application screen, select Non-gallery application.

5. Give your application a name, and click Add at the bottom of the page.

   

6. On the menu, select Single sign-on.

   

7. Choose SAML as the sign-on method.

8. Edit the Basic SAML Configuration as follows:

   1. In the configuration page, click the edit icon.

      

   2. Specify the following:

      

      • Identifier (Entity ID): Uniquely identifies the Sysdig application. Azure AD sends the identifier to the Sysdig application as the audience parameter of the SAML token. Sysdig validates this as part of the SSO process.

        For example, the identifier for Sysdig Monitor for the EU region is https://eu1.app.sysdig.com.

        See SaaS Regions and IP Ranges for the complete list of entity IDs for different regions.

      • Reply URL: Specifies where Sysdig expects to receive the SAML token.

        For example, the identifier for Sysdig Monitor for the EU region is https://eu1.app.sysdig.com/api/saml/auth.

      • See SaaS Regions and IP Ranges for the complete list of reply URLs for different regions.

      • Relay State: Specifies to the application where to redirect the user after authentication is completed. Typically the value is a valid URL for Sysdig. If you are configuring SSO for SaaS, change the relay state to reflect the correct customer number associated with your Sysdig application. For on-prem installations, the customer number is always 1.

        The format is:

        #/&customer=1234
        

      • Sign on URL: It is the sign-in page for the Sysdig application that will perform the service provider-initiated SSO. Leave it blank if you want to perform identity-provider-initiated SSO.

      For more information on configuration parameters, see Configure SAML-based single sign-on to non-gallery applications.

Sysdig-Specific Steps for Active Directory Configuration

1. Under SAML Signing Certificate, copy the App Federation Metadata URL.

   

2. Log in to your Sysdig instance as an admin.

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

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

4. Enter the following:

   • Metadata: Enter the App Federation Metadata URL you copied.

   • Email Parameter: Set the value to emailaddress.

     Azure AD claims are:

     saml = AD
     givenname = user.givenname
     surname = user.surname
     emailaddress = user.mail
     name = user.userprincipalname
     Unique User Identifier = user.userprincipalname
     

     In the Sysdig application, you need to set the email to emailaddress which is what Azure AD sends to Sysdig in the SAML assertion. Alternatively, Azure AD can be modified to send another attribute.

5. Click Save.

6. Select SAML from the Enable Single Sign On drop-down.

Create a User in Azure Active Directory Domain

1. Log in to the Azure AD portal.

2. Click Azure Active Directory, and note down the domain name.

3. Select Azure Active Directory, then Users.

   The Users - All Users screen is displayed.

4. Select New Users .

   You can either create a new user or invite an existing AD.

5. Enter name, username, and other details, then click Create.

6. In the Profile page, add the Email and Alternate Email parameters. The values can match

Assign the User to the Sysdig Application

1. Navigate to the Sysdig application.

2. Click Users and Group, then click the Add user button.

3. Select the Users and Groups checkbox, then choose the newly created user to add to the application.

4. Click Select, then Assign at the bottom of the screen.

Enable Authentication Settings in the Sysdig Instance

Ensure that Flag to enable/disable create user on login is enabled. Typically this setting is enabled by default.

If you are using both Sysdig Monitor and Secure, ensure that the user accounts are created on both the products. A user that is created only on one Sysdig application will not be able to log in to another by using SAML SSO.

(Optional) Configure Sysdig as a New Application

If Azure Active Directory does not allow you to create Sysdig as a Non- Gallery application, perform the following:

1. In Azure AD, click Enterprise Applications > New Application.

2. Select Application you’re developing.

   

   You will be taken to the app registration page:

3. Select New Registration:

4. Provide a name for the application you are registering.

   

5. Enter the redirect URI.

   For example, the redirect URI for Sysdig Monitor for the EU region is https://eu1.app.sysdig.com/api/saml/auth. See SaaS Regions and IP Ranges for the redirect URLs for other regions.

6. Click Register to complete the registration.

7. In the Overview tab click Add an Application ID URI:

   

8. Click Add a scope.

9. Add the application ID URI as follows:

   https://<your_sysdig_url>:443
   

   Replace <*your_sysdig_*url> with the URL appropriate to your application and region. See SaaS Regions and IP Ranges for more information.

10. In the Overview tab, click Endpoints, and copy the Federation Metadata URL.

11. Log in to Sysdig, navigate to SAML Authentication screen, and enter the Federation Metadata URL.

    You will still need to ensure that the user creation on the login option is enabled.

12. Save the settings.

2.4 - ADFS (SAML On-Prem)

Review SAML (On-Prem) before you begin.

These instructions assume you already have a working, Internet-accessible ADFS ( Active Directory Federation Service) server. Interoperability testing has been performed specifically with ADFS on Windows Server 2012 R2.

Follow the instructions below to configure ADFS with the ADFS Management tool in the Windows Server Manager.

For Service-Provider-Initiated Login Flow

1. Right-click to Service > Edit Federation Service Properties. Note the hostname in the Federation Service Identifier, as this will be used in the metadata URL that you paste in the Metadata entry on the SAML Configuration page in the Sysdig authentication settings. Specifically, the metadata URL will be of the format https://HOSTNAME/FederationMetadata/2007-06/FederationMetadata.xml. Also, so that the Sysdig platform can access this URL directly, this host must resolve in DNS and have a valid (not self-signed) SSL/TLS certificate.

   

2. Add a Relying Party Trust configuration for the Sysdig application.

   1. Right-click to Relying Party Trusts > Add Relying Party Trust and click Start to begin the wizard.

      

   2. In the Select Data Source step, click the button to Enter data about the relying party manually, then click Next

      

   3. Enter a Display name of your choosing (e.g. “Sysdig Monitor” or “Sysdig Secure”), then click Next

      

   4. Click Next to accept the default option to use AD FS profile

      

   5. Click Next to skip the selection of an optional token encryption certificate (Sysdig does not support this option)

      

   6. Check the box to Enable support for the SAML 2.0 Web SSO protocol, then enter one of the following values for Relying party SAML 2.0 SSO service URL:

      If configuring Sysdig Monitor in the US East, enter: https://<hostname>/api/saml/auth

      If configuring Sysdig Secure in the US East, enter: https://<hostname>/api/saml/secureAuth

      Replace <hostname> with the unique hostname associated with your on-prem deployment. For other regions, the format is https://<region>.<hostname>/api/saml/auth and https://<region>.<hostname>/api/saml/secureAuth.

      Then click Next.

      

   7. For the Relying party trust identifier, enter one of the following values:

      If configuring Sysdig Monitor in the US East, enter: https://<hostname>

      If configuring Sysdig Secure in the US East, enter: https://<hostname>/secure/

      Replace <hostname> with the unique hostname associated with your on-prem deployment. For other regions, the format is https://<region>.<hostname>/api/saml/auth and https://<region>.<hostname>/api/saml/secureAuth.

      Then click Add, then click Next

      

   8. Click Next to skip configuration of multi-factor authentication

      

   9. Choose a policy for whether users will be permitted to login to the Sysdig application. The default to Permit all users to access the relying party will typically be acceptable. Click Next.

      

   10. Review the summary and click Next to complete the configuration of the Relying Party Trust

       

   11. The next step will involve adding Claim Rules, so you can leave the box checked to Open the Edit Claim Rules dialog and click the Close button to be brought immediately into the Claim Rules editor

       

3. Ensure that the SamlResponseSignature option matches the Sysdig authentication configuration.

   1. Use the Set-AdfsRelyingPartyTrust/Get-AdfsRelyingPartyTrust cmdlets via PowerShell to configure SamlResponseSignature .

      -SamlResponseSignature
      Specifies the response signatures that the relying party expects. The acceptable values for this parameter are:
      
      AssertionOnly
      MessageAndAssertion
      MessageOnly
      

      For more information, see Set-AdfsRelyingPartyTrust.

   2. Navigate to Settings > Authentication on the Sysdig app and check the Sysdig authentication setting maps to the SamlResponseSignature :

      

      For MessageAndAssertion, enable both the options.

4. Next, use the Claim Rules to ensure that login data is sent as needed to the Sysdig platform. A user’s login to the Sysdig platform is based on an email address, and a default ADFS configuration would not send the email address as required. The following configuration ensures the correct field from Active Directory is delivered in the claim.

   1. If not already in the Claim Rules editor from the previous step, navigate to it by right-clicking on the Relying Party Trust that was just created and selecting Edit Claim Rules

      

   2. Click Add Rule. At the following screen, accept the default rule template to Send LDAP Attributes as Claims and click Next.

      

   3. Enter a name for the rule, select Active Directory as the Attribute store, then use the pull-down selectors to pick E-Mail Address as both the LDAP Attribute and Outgoing Claim Type, then similarly make pull-down selections for Given Name and Surname. Once these selections are made, click Finish.

      

   4. Now click Add Rule again, this time selecting the template for Transform an incoming claim

      

   5. Enter a name for the rule, then use the pull-downs to select an Incoming claim type of E-Mail Address, an Outgoing claim type of Name ID, and an Outgoing name ID format of Email, then click Finish.

      

   6. (Optional) If you want the user’s First Name and Last Name to be included in the records created in the Sysdig platform database when new users successfully login via SAML for the first time, additional Transform rules must also be created. Only the email-based username is strictly required and we already created a rule for this, so this step is optional.

      If you wish to do this, click Add Rule and once again select the template for Transform an incoming claim. Enter a name for the rule, then use the pull-down to select an Incoming claim type of Given Name, and for the Outgoing claim type, directly type first name into the field. After clicking Finish, click Add Rule and create a similar rule to transform the Incoming claim type of Surname to the Outgoing claim type of last name.

      

   7. Having clicked Finish after creating your last rule, you will see all rules now in the editor. Click Ok, and your ADFS configuration for your Sysdig application is complete.

      

For IdP-Initiated Login Flow (Optional)

(Optional) The steps above represent a Service-Provider-Initiated SAML configuration. If you would prefer an IdP-initiated SAML configuration, this is also possible with ADFS, but requires the additional steps described below.

1. The Sysdig platform requires a specific setting of RelayState in order to accept IdP-initiated login flows. On the ADFS versions tested, we’ve found this use of RelayState is disabled by default, and a Microsoft article describes the topic in detail. To enable it, as described in a Microsoft forum thread, on your ADFS host, edit %systemroot%\ADFS\Microsoft.IdentityServer.Servicehost.exe.config and add <useRelayStateForIdpInitiatedSignOn enabled="true" /> to the <microsoft.identityserver.web> section. Once the modification is saved, restart ADFS services for the change to take effect.

2. You will need to retrieve your Sysdig customer number as described in the Find Your Customer Number article.

3. You will then need to generate an IdP-initiated login URL.

   In addition to having the correct settings, it must be properly URL encoded. To ease this configuration, use this ADFS RelayState Generator tool. When launched, enter the values below, then hit the Generate URL button.

   • For the IDP URL String, enter https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx

   • For the Relying Party Identifier, enter one of the following values if you are in the US East region:

     • If configuring Sysdig Monitor, enter https://<hostname>.

     • If configuring Sysdig Secure, enter https://<hostname>/secure/

     Replace <hostname> with the unique hostname associated with your on-prem deployment.

     For other regions, the format is https://<region>.<hostname> for Sysdig Monitor and https://<region>.<hostname>/secure/ for Sysdig Secure. Replace <region> with the region where your Sysidig application is hosted.

     See SaaS Regions and IP Ranges for more information on regions.

   • For the Relay State/Target App, enter #/&customer=CUSTOMER-ID-NUMBER, substituting the CUSTOMER-ID-NUMBER you retrieved in the previous step

     

1. Use the Results URL from the tool to test your IdP-initiated login. Note that per this Microsoft forum thread, it is apparently not possible to configure ADFS to use such a URL when your users select the application from the pull-down menu at https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx. However, you may embed the URL into a custom portal or bookmarks list.

2. Now you can test login using an Active Directory user that has an Email address configured.

   

Test Metadata (Optional)

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.

3 - OpenID Connect (On-Prem)

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

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

Overview

Summary of OpenID Functionality in Sysdig

The Sysdig platform ordinarily maintains its own user database to hold a username and password hash. OpenID 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 OpenID, 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.

Basic Enablement Workflow

Administrator Steps

Configure IdP

Select the appropriate IdP link below, and follow the instructions:

• Okta (OpenID On-Prem)

• OneLogin (OpenID On-Prem)

• Keycloak (OpenID On-Prem)

• Azure (OpenID On-Prem)

UI-Based: Configure OpenID in Settings

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

To enable baseline OpenID functionality:

Enter OpenID Basic Connection Settings

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

2. Select Authentication.

3. Select the OpenID tab.

   

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

Enter OpenID Additional Settings (if needed)

In some cases, an OpenID IdP may not support metadata auto-discovery, and additional configuration settings must be entered manually.

In this case:

1. On the OpenID tab, toggle the Metadata Discovery button to OFF to display additional entries on the page.

   

2. Enter the relevant parameters derived from your IdP (see table below) and click Save.

Select OpenID for SSO

1. Select OpenID from the Enabled Single Sign-On dropdown.

2. Click Save Authentication.

Script-Based: Configure OpenID Using Scripts

The configuration of the OpenID Connect feature can be viewed, updated, and deleted by the “super” Admin. An oidc_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.

# ./oidc_config.sh
Must specify the Sysdig App whose OpenID Connect configuration will be viewed/set

Usage: ./oidc_config.sh [OPTIONS]

Affect OpenID Connect login settings for your Sysdig software platform installation

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).

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

# ./oidc_config.sh
No openid settings are set
Run for further info: ./oidc_config.sh -h

Add the -s option to set the OpenID Connect configuration for a particular Sysdig application. When setting the config, you’ll use additional options to provide the config details you saved in the earlier OpenID Provider configuration step.

If the configuration is successfully posted to the Sysdig platform, the new configuration will be echoed back.

An example of creating the two separate OpenID Connect configurations for both Monitor and Secure, each using Okta as an OpenID Provider:

# ./oidc_config.sh -s -u https://dev-824158.oktapreview.com -i 0oafpykpv7JMS4gMe0h7 -e ZctTGJMNJmuseEJHJGhvnb0pniZvz9Gf6RStxhHn
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547541009000,
    "type": "openid",
    "scope": "SYSTEM",
    "settings": {
      "issuer": "https://dev-824158.oktapreview.com",
      "clientId": "your-client-ID",
      "clientSecret": "your-client-secret",
      "metadataDiscovery": true
    }
  }
}

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

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

./oidc_config.sh -d
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547541009000,
    "type": "openid",
    "scope": "SYSTEM",
    "settings": {
      "issuer": "https://dev-824158.oktapreview.com",
      "clientId": "your-client-id",
      "clientSecret": "Your-client-secret",
      "metadataDiscovery": true
    }
  }
}

User Experience

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

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

  Monitor: https://HOSTNAME/ or Secure: https://HOSTNAME/secure.

  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:

  • Monitor: https://HOSTNAME/api/oauth/openid
  • Secure: https://HOSTNAME/api/oauth/openid?product=SDS

• 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.

3.1 - Okta (OpenID On-Prem)

Review OpenID Connect (On-Prem) before you begin.

The notes below describe minimal steps to be taken in Okta. You may need to adjust the steps based on the specifics of your environment.

1. Log in to your Okta organization as a user with administrative privileges and click the Admin page.

2. Click Add Applications, then click the Create New App button.

3. Select Web as the Platform type, then click OpenID Connect as the Sign-on method, then click Create.

4. Create a new application

   • Enter your choice of General Settings

   • For Login redirect URIs, enter one of the following values, replacing HOSTNAME with the hostname through which your users access the Sysdig application(s) and PORT with the TCP port # (typically 443):

     If configuring Sysdig Monitor, enter: https://HOSTNAME:PORT/api/oauth/openid/auth

     If configuring Sysdig Secure, enter: https://HOSTNAME:PORT/api/oauth/openid/secureAuth

   • Click Save.

5. You should next be placed in a General tab. Take note of the Client ID and Client secret that are shown, as you will need them to complete the configuration in the Sysdig platform.

6. Click the Sign On tab. Take note of the Issuer URL that is shown, as you will need it to complete the configuration in the Sysdig platform.

7. Return to the bottom section of the OpenID Connect (On-Prem) article for instructions on using the helper script to complete the configuration in the Sysdig platform.

3.2 - OneLogin (OpenID On-Prem)

Review OpenID Connect (On-Prem) before you begin.

The notes below describe minimal steps to be taken in OneLogin. You may need to adjust the steps based on the specifics of your environment.

1. Login to your OneLogin organization as a user with administrative privileges and click to Apps > Custom Connectors, then click the New Connector button.

2. Create a new Connector

   • Enter your choice of connector name

   • Select a Sign on Method of OpenID Connect

   • For Redirect URI to, enter one of the following values, replacing HOSTNAME with the hostname through which your users access the Sysdig application(s) and PORT with the TCP port # (typically 443):

     If configuring Sysdig Monitor, enter: https://HOSTNAME:PORT/api/oauth/openid/auth

     If configuring Sysdig Secure, enter: https://HOSTNAME:PORT/api/oauth/openid/secureAuth

   • Click the Save button

3. From the More Actions pull-down menu, select Add App to Connector.

4. Click Save to add the app to your catalog. Once clicked, additional tabs will appear.

5. Click to the SSO tab. Change the setting in the Token Endpoint drop-down to POST, then click Save.

   

6. While still on the SSO tab, take note of the Client ID and Client Secret that are shown (click Show client secret to reveal it), as you will need them to complete the configuration in the Sysdig platform.

7. Note that the Issuer URL you will need to complete the Sysdig platform configuration will consist of https://YOUR-ONELOGIN-DOMAIN.onelogin.com/oidc

8. Return to the bottom section of the OpenID Connect (On-Prem) article for instructions on using the helper script to complete the configuration in the Sysdig platform.

3.3 - Keycloak (OpenID On-Prem)

Review OpenID Connect (On-Prem) before you begin.

The notes below describe minimal steps to be taken in Keycloak. You may need to adjust the steps based on the specifics of your environment.

1. Login to your Keycloak server’s Administrative Console.

2. Select a realm or create a new one.

3. Click Clients, then click the Create button.

4. Enter the Client ID of your choosing (e.g. “SysdigMonitor”) and take note of it, as you will need it later to complete the configuration in the Sysdig platform.

5. Make sure the Client Protocol drop-down has openid-connect selected. Click the Save button.

6. Configure OpenID Connect client

   • Click the toggle for Authorization Enabled to ON

   • For Valid Redirect URI, enter one of the following values, replacing HOSTNAME with the hostname through which your users access the Sysdig application(s) and PORT with the TCP port # (typically 443):

     If configuring Sysdig Monitor, enter: https://HOSTNAME:PORT/api/oauth/openid/auth

     If configuring Sysdig Secure, enter: https://HOSTNAME:PORT/api/oauth/openid/secureAuth

   • Click the Save button

7. Click to the Credentials tab. Take note of the Secret that is shown, as you will need it to complete the configuration in the Sysdig platform.

8. Note that the Issuer URL you will need to configure in the Sysdig platform will consist of https://{KEYCLOAK-SERVER-ADDRESS}/auth/realms/{REALM_NAME}, where {KEYCLOAK-SERVER-ADDRESS} and {REALM-NAME} are derived from your environment where you just created the configuration.

9. Return to the bottom section of the OpenID Connect (On-Prem) article for instructions on using the helper script to complete the configuration in the Sysdig platform.

3.4 - Azure (OpenID On-Prem)

OpenID Connect is a security-token based extension of the OAuth 2.0 authorization protocol to do single sign-on. Azure Active Directory provides an implementation of OpenID Connect (OIDC) protocol and Sysdig supports it for single sign-on and API access to Sysdig application.

Enabling Azure OpenID Connect for single sign-on to Sysdig applications include configuration on the Microsoft Active Directory as well as on the Sysdig application.

Prerequisites

Administrator privileges on Sysdig and Azure Active Directory (AD).

Configuring Sysdig Application in Azure AD

1. Log in to the Azure AD portal.

2. Select your Azure Active Directory service or create a new one.

3. Click App registration > New registration.

4. In the Register an application page, specify the following:

   • Name: Display name to identify your Sysdig application. For example, Sysdig Secure.

   • Supported account types: Choose an account type that is appropriate for your deployment. If you choose single-tenant, all user and guest accounts created in your active directory can use Sysdig application and API. If you choose multi-tenant, all users with a work or school account from Microsoft can use Sysdig application and API.

   • Redirect URI: Authenticated Sysdig users are redirected to this URI.

     For Login redirect URIs, enter one of the following values, replacing HOSTNAME with the hostname through which your users access the Sysdig applications and PORT with the TCP port number, typically 443:

     For Sysdig Monitor: https://HOSTNAME:PORT/api/oauth/openid/auth

     For Sysdig Secure: https://HOSTNAME:PORT/api/oauth/openid/secureAuth

     You can add only a single redirect URL on this page. Use the Authentication page associated with your application to add additional redirect URIs.

5. Click Register.

6. Add additional redirect URIs.

   1. Select your application from App registration.

   2. Click Authentication from the left navigation.

   3. Add the redirect URIs corresponding to Monitor and Secure.

      

7. Create a Secret for the Sysdig application.

   It is a string that the Sysdig application uses to prove its identity when requesting a token.

   1. Click Certificates & secrets.

      

   2. Under Client Secrets, click New client secret.

   3. Enter a description that identifies the secret and choose an expiration period.

   4. Click Add.

   5. Copy the client secret. You will need the client secret while configuring OpenID Connect SSO on the Sysdig application.

8. Copy the Client ID and OpenID Connect endpoints corresponding to the application that you have created.

   1. Select your application from App registration.

   2. Copy the Application (client) ID.

      You will need the client ID while configuring OpenID Connect SSO on the Sysdig application.

   3. Click Endpoints.

      

   4. Copy the OpenID Connect metadata document and open it in a browser.

   5. Copy the OpenID Connect URI (Issuer URI).

      For example, https://login.microsoftonline.com/5a4b56fc-dceb-4a64-94ff-21e08e5892f5/v2.0

Configure Sysdig Settings

To enable Azure OpenID functionality on the Sysdig application, you need the following:

• Client ID

• Client Secret

• Issuer URL.

See OpenID Connect (On-Prem) to learn how to complete your configuration.

4 - LDAP

LDAP support in the Sysdig software platform allows user authentication using credentials in a customer’s own directory server. LDAP support is not currently available the cloud-based (SaaS) Sysdig platform.

The configuration and functionality of LDAP has changed significantly in recent releases of the platform. It is recommended to upgrade to the newest on-prem release to take advantage of improvements. However, if you are running an older release and cannot yet upgrade, contact Sysdig Support if you need further assistance.

General LDAP Tips

Testing Configurations With ldapsearch

Small typos in fields such as search filters can cause failures that are difficult to debug. You may want to perfect your more complex configurations before applying them via the helper scripts. This will help “divide & conquer” as to whether an issue is generic to LDAP syntax and/or the directory vs. a possible bug in the Sysdig platform.

If you have an Ubuntu Linux host at your disposal that can access your directory server via LDAP, install the ldap-utils package:

# sudo apt install ldap-utils

If accessing LDAP over SSL/TLS, edit the file /etc/ldap/ldap.conf and add the following line:

TLS_REQCERT allow

Then copy the CA certificate (the same one that was uploaded in the Settings of the Replicated console) to a location on the host, such as /tmp/cert.pem .

Now you can run arbitrary queries via generic LDAP and study their success or failure. For instance, the following command-line uses some of the settings from LDAP Authentication Configuration (for Platform v. 963 - 1091) examples:

# LDAPTLS_CACERT=/tmp/cert.pem ldapsearch -H ldaps://172.16.0.1:636 -M -b "DC=example,DC=local" -D "cn=Administrator,cn=Users,dc=example,dc=local" -w "myMgrPassword" "(&(objectClass=organizationalPerson)(sAMAccountName=jdoe))"

...
# John Doe, Users, example.local
dn: CN=John Doe,CN=Users,DC=example,DC=local
...

Excluding Classes of Users (e.g. Disabled Accounts)

Per this post, Active Directory admins may leverage certain queries to easily exclude certain classes of users from being able to authenticate to the Sysdig platform. For example, the following will filter out users whose accounts have been disabled in Active Directory.

(!(userAccountControl:1.2.840.113556.1.4.803:=2))

This can be combined with other config via AND logic, such as by extending one of our searchFilter examples:

"searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName={0})(!(userAccountControl:1.2.840.113556.1.4.803:=2)))"

4.1 - LDAP Authentication Configuration (for Platform v.1586+)

LDAP support in the Sysdig software platform is used to allow user authentication using credentials in an enterprise’s own directory server.

This document describes how to configure base LDAP settings, as well as the limitations of the LDAP support.

Overview

Functionality

The Sysdig platform ordinarily maintains its own user database to hold a username and password hash, as well as settings for Admin privileges, Sysdig team membership, and a user’s configured dashboards and alerts. Sysdig’s LDAP authentication feature provides a means to allow the Sysdig platform to query your separate directory server to validate username/password. Upon successful authentication, a corresponding user record in the Sysdig platform’s user database is automatically created. When the LDAP feature is in use, the user’s directory password is not stored in the Sysdig user database.

Once LDAP authentication is enabled, all normal user authentication will be performed against your configured directory server. Other local, non-LDAP users that were created before LDAP was enabled can still authenticate via LDAP as long as their username in your directory matches with the username of their pre-existing record in the Sysdig user database. For example, consider a user jdoe@example.com who had been a user in the Sysdig environment before LDAP was enabled. Once LDAP authentication is enabled, if a user jdoe exists in the directory server and is able to authenticate successfully via LDAP, they will be permitted to log in to the Sysdig platform as the pre-existing jdoe@example.com user. Any user-specific configuration (Alerts, Dashboards, etc.) that were attached to jdoe@example.com will still be visible to this user. Any password previously set for such a pre-existing user record will not be used for authentication to the Sysdig platform unless LDAP authentication is disabled.

Prerequisite: Have the “Super” Admin User Credentials and Token

In an environment enabled for LDAP authentication, the one user still subject to direct email+password authentication is the “super” Admin user.

Creation of this user is a required initial install step.

You can find the credentials either in the Replicated console (screenshot below) or your Kubernetes ConfigMap element sysdigcloud.default.user .

This user is required and cannot be deleted. This login provides:

• A way to access the Sysdig platform when LDAP connectivity is severed.

• The first Admin user in the install, essential for assigning Admin rights to other users once they’ve authenticated via your directory and their user records have been added to the Sysdig user database.

• The user whose token can be used to perform further LDAP configurations.

  See Retrieve the Sysdig API Security Token for details.

Configure Basic LDAP Settings

There are two ways to configure the basic LDAP settings for Sysdig: via the Sysdig UI, or via the API endpoint using scripts and HTTP methods.

UI-Based: Configure LDAP in Settings

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

Enter LDAP Connection Settings

1. Log in to Sysdig Monitor or Sysdig Secure as the “super” Admin user. and select Settings.

2. Select Authentication.

3. Select the LDAP tab.

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

Table_loginConnectionSettings

# openssl s_client -showcerts -connect <server-ip>:636

-----BEGIN CERTIFICATE-----
[random text...]
-----END CERTIFICATE-----

cn=Administrator,cn=Users,dc=example,dc=local

dc=example,dc=local

Table_loginFilter

cn=Users

cn=Users,dc=example,dc=local

(&(objectClass=organizationalPerson)(sAMAccountName={0}))

Select LDAP for SSO

1. Select LDAP from 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 LDAP Using Scripts

The configuration of the LDAP feature can be viewed, updated, and deleted by the “super” Admin via the API endpoint /api/admin/ldap/settings using HTTP methods for GET, POST, and DELETE, respectively.

The workflow is as follows:

1. Log in as super admin (prerequisite ).

2. Retrieve the Sysdig API Security Token (prerequisite)

3. Access login_config.sh and verify_user.sh helper scripts available in the SSO folder at sysdig-cloud-scripts repository, to assist in completing this configuration.

4. Modify the env.sh to enter the API_TOKEN and the URL of your environment.

5. Modify settings_login_simple.json file with Login Connection settings and Login Filter settings.

6. Execute various scripts

   # get current settings: initially empty
   ./login_config.sh
   
   # set settings we have detailed above
   ./login_config.sh -s settings_login_simple.json
   
   # verify an existing user information is retrieved
   ./verify_user.sh -u jdoe
   
   # verify a non existing user information is not retrieved
   ./verify_user.sh -u nothere
   
   # optionally delete the settings
   # ./login_config.sh -d
   

7. See Advanced Use Cases (below) if you have a multi-server environment, or want to create LDAP users before they log in.

Details of this workflow are as follows:

Configure env.sh

To use the helper script, modify the env.sh

to set the required values for API_TOKEN and URL for your environment. Once set, invoking login_config.sh (at the sysdig-cloud-scripts repository in GitHub) helper script with no options will print the current configuration. Initially empty.

Retrieve Current LDAP Settings

# ./login_config.sh
No ldap settings are set
Run for further info: ./login_config.sh -h

Configure settings_login_simple.json and set withlogin_config.sh

In the sysdig-cloud-scripts repository in GitHub, find the example settings_login_simple.json and modify it for your environment, following the Tables above.

To apply the new LDAP settings invoke login_config.sh with the -s option and specify the filename containing the JSON config:

# ./login_config.sh -s settings_login_simple.json
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547542447000,
    "type": "ldap",
    "scope": "SYSTEM",
    "settings": {
      "loginConnectionSettings": {
        "server": "ldap://172.16.0.1",
        "rootDn": "dc=example,dc=local",
        "managerDn": "cn=Administrator,cn=Users,dc=example,dc=local",
        "managerPassword": "myMgrPassword",
        "referral": "IGNORE"
      },
      "loginFilter": {
        "searchBase": "cn=Users",
        "searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName={0}))"
      }
    }
  }
}

Sample result in Active Directory

Using the specific example settings_login_simple.json and the minimal Active Directory configuration in the screenshot below, login to the Sysdig platform would now be permitted for a user jdoe that has the following distinguishedName:

CN=John Doe,CN=Users,DC=example,DC=local

Test User Login

To test the login configuration, the “super” Admin user can confirm if a particular user would be permitted to login given current LDAP login connection settings. To do this, perform an HTTP GET to the API endpoint /api/admin/ldap/settings/verify/USERNAME . A verify_user.sh helper script is provided to easily perform this. If invoked with the -u option and a username, and the user’s login would be successful, it will return the user’s information from the directory.

# ./verify_user.sh -u jdoe
{"element":"uSNCreated=12799, countryCode=0, badPwdCount=0, whenChanged=20180406232737.0Z, objectClass=top, primaryGroupID=513, givenName=John, objectGUID=..., objectSid=..., instanceType=4, whenCreated=20180406220651.0Z, dSCorePropagationData=16010101000000.0Z, sn=Doe, userAccountControl=66048, lastLogonTimestamp=131675308573317669, cn=John Doe, codePage=0, accountExpires=9223372036854775807, sAMAccountName=jdoe, sAMAccountType=805306368, userPrincipalName=jdoe@example.local, displayName=John Doe, pwdLastSet=131675260113435098, lastLogon=131682933890462204, name=John Doe, objectCategory=CN=Person,CN=Schema,CN=Configuration,DC=example,DC=local, distinguishedName=CN=John Doe,CN=Users,DC=example,DC=local, lastLogoff=0, memberOf=CN=Sysdig Viewers,CN=Users,DC=example,DC=local, logonCount=0, uSNChanged=12986"}

If the user would not be able to login, an error message will be returned.

# ./verify_user.sh -u nothere
Could not verify user "nothere". Check LDAP login config settings and/or system log.

Note that if LDAP authentication is disabled this method for testing user login is not available.

Optional: Delete LDAP settings

To delete LDAP settings, invoke login_config.sh with the -d option. After running the following command all LDAP users will not be able to login to the Sysdig platform.

# ./login_config.sh -d
{
  "authenticationSettings": {
    "id": 1,
    "version": 1,
    "createdOn": 1547542447000,
    "type": "ldap",
    "scope": "SYSTEM",
    "settings": {
      "loginConnectionSettings": {
        "server": "ldap://172.16.0.1",
        "rootDn": "dc=example,dc=local",
        "managerDn": "cn=Administrator,cn=Users,dc=example,dc=local",
        "managerPassword": "myMgrPassword",
        "referral": "IGNORE"
      },
      "loginFilter": {
        "searchBase": "cn=Users",
        "searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName={0}))"
      }
    }
  }
}

User Experience

When a user accesses the Sysdig interface, they are prompted to enter their LDAP credentials (in the fields normally used for email/password).

Monitor: https://HOSTNAME/ or Secure: https://HOSTNAME/secure

Advanced Use Cases

Multi-Server Directories

Data about your users that need to access the Sysdig platform may be stored across many directory servers in your environment. As the Sysdig platform is only able to query one LDAP server endpoint, you would need to take extra steps to ensure successful authentication for such users.

The simplest approach to achieve this is to query against a Global Catalog. As the Global Catalog stores a copy of all Active Directory objects in a forest, this provides a fast and convenient target for the Sysdig platform to find all users that may need to authenticate. Since queries against the Global Catalog are also performed via LDAP, you simply need to ensure your LDAP configuration specifies the appropriate address and TCP port for the Global Catalog, e.g. ldap://176.16.0.1:3268 for cleartext LDAP or ldaps://172.16.0.1:3269 for LDAP over SSL. If querying against a Global Catalog, the referral option of the Sysdig platform’s LDAP configuration can remain at its default setting of "IGNORE".

If a Global Catalog is not available, another approach is to leverage referral chasing. Such chasing depends on complex interplay of configuration settings, DNS resolution, and network connectivity to multiple servers. If you require this option, carefully read the tips in this section and validate your configuration in a test environment before attempting its use in production. Contact Sysdig support for assistance as necessary.

For our example configuration, we’ve added another Domain Controller to our environment that holds users a separate set of users for the child domain eu.example.local.

We’d like to permit login for a user “eurodude” in the child domain. This user has distinguishedName:

CN=Euro Dude,CN=Users,DC=eu,DC=example,DC=local

In the example configuration settings_login_referral_follow.json shown below, the Sysdig platform still begins its LDAP queries at the same top-level server target. However, the referral option is set to "FOLLOW", which will cause the Sysdig platform to perform subsequent queries if a query returns one or more referrals.

{
  "authenticationSettings": {
    "settings": {
      "loginConnectionSettings": {
        "server": "ldap://172.16.0.1",
        "managerDn": "cn=Administrator,cn=Users,dc=example,dc=local",
        "managerPassword": "myMgrPassword",
        "referral": "FOLLOW"
      },
      "loginFilter": {
        "searchBase": "dc=example,dc=local",
        "searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName={0}))"
      }
    },
    "version": 1,
    "type": "ldap"
  }
}

Note also how in this case the rootDn option is left unspecified and the searchBase is set to the distinguished name of the top-level domain. This is necessary to ensure the scope of the chased referral queries will include the child domain. If **rootDn **and searchBase had been left as they were set in the settings_login_simple.json example, the initial query would have been targeted only within cn=Users,dc=example,dc=local and hence the referral would never have been returned by the top-level server.

Note these other caveats of referral chasing in the Sysdig platform:

• Referrals may only be successfully chased to child domains. If referrals point to parallel domains (e.g. for our example, dc=adjacent,dc=local) the queries will not succeed and users stored in the directory servers for such domains will not be able to authenticate.

• The LDAP library used by the Sysdig platform does not log information about each referral it attempts to chase. Therefore, if you enable referral chasing, it is important that you understand the server targets that may be chased in your environment and ensure the network connectivity (routing/firewalls) will permit the Sysdig platform to query these server targets. If LDAP queries are failing due to a network connectivity issue, this will typically be accompanied by delays during Sysdig user logins of approximately 30 seconds followed by a login failure with an HTTP 504 error message shown in the login screen. If this occurs, contact Sysdig support for assistance.

Creating LDAP Users Before They Login

The default behavior of the LDAP feature is to create a new record in the Sysdig user database when a user authenticates successfully via LDAP for the first time. However, it may be desirable to add such user records in advance of their first login, such as if you wish to use automation to change user permissions, assign team membership, or pre-populate Dashboard/Alert configurations. A create_user.sh helper script is available in the sysdig-cloud-scripts repository to create such user records via the API. This script can also be used to enable/disable this functionality in the Sysdig platform. See the README for details.

Additional details regarding this type of user creation in conjunction with LDAP authentication:

• This method allows creation of any username, even if it doesn’t currently exist in the directory that is queried via LDAP.

• When LDAP authentication is enabled, such users can be created with a simple username (e.g. jdoe ) or with an email-style postfix (as is typical for non-LDAP Sysdig user, e.g. jdoe@example.com ). In this latter case only the username portion ( jdoe ) is used when the Sysdig platform is performing an LDAP query during attempted login.

• While the password must be included in the config you POST to create the user, it is not used by the Sysdig platform when LDAP is enabled, as authentication will always be performed via LDAP. For this same reason, if a user has been created in this way, they will not be able to login unless there is a matching user in the directory that is queried via LDAP.

• The firstName and lastName values as specified in the example are optional and independent from any equivalent name settings in the directory that is queried via LDAP.

Limitations and Caveats

• LDAP support has been tested with Active Directory in Windows Server 2012 R2. It may work with AD versions that ship with other versions of Windows, or other directory servers that use the LDAP protocol. If you are intending to use LDAP with something other than Active Directory, please contact Sysdig Support.

• The LDAP feature is only present in Sysdig software platform installs (not the SaaS version).

• Only one LDAP config can exist per deployment (i.e. the platform can only query one directory server endpoint).

• Because the Sysdig software platform is based on the same technology as the SaaS-based Sysdig service, it theoretically supports the configuration of multiple “customers” using the same install. However, the multi-customer option is not supported when the LDAP feature is enabled.

• When LDAP authentication is enabled, adding users via email “invites” is not possible.

• LDAP authentication for directory usernames that begin or end with a space character (e.g. " jdoe" or "jdoe " ) are not supported.

• Configuration entries that contain special characters (for instance, a managerPassword that contains a backslash character) are supported, but note that you will need to perform proper JSON escaping in the configuration you POST to the API. If you attempt to post invalid JSON, the helper scripts will return an error message. If this occurs, you can use tools such as JSONLint to narrow down the source of the problem and/or JSON String Escape to learn how to properly escape your text.

• The LDAP feature does not attempt any ongoing “sync” back from the Sysdig platform user database to the directory server. Note how this impacts the following:

  • If a user is deleted from the directory server, their user record will remain in the Sysdig user database until a Sysdig Admin deletes it. Of course, that user will not be able to login since they will no longer be able to authenticate successfully via LDAP.

  • If an Admin deletes a user from the Sysdig user database, but the user can still authenticate successfully via LDAP, their Sysdig user record will be recreated if they login again via LDAP.

  • If a person’s username should change in the directory server (e.g. the value for sAMAccountName in our examples above), the next time they login, a new user record will be created for them in the Sysdig user database. Settings they previously had in the Sysdig platform such as Admin rights and Alerts/Dashboard configurations will not be present for this recreated user.

• Other LDAP-centric functionality that is not currently supported (not an exhaustive list):

  • Mapping a user in the directory server to the Sysdig “super” Admin (such as to avoid the need to configure the this “super” Admin user).

  • Session expiry based on configuration in the directory server (such as to set a user account to only be valid until a certain date).

  • Login policies based on configuration in the directory server (such as to restrict login to certain hours).

  • User timeout functionality (such as to remove a user from the Sysdig user database if they have not logged in for a certain amount of time).

4.2 - LDAP Authentication Configuration (for Platform v.1149 - 1511)

Introduction

LDAP support in the Sysdig software platform is often leveraged to allow user authentication using credentials in a customer’s own directory server.

This document describes how to configure base LDAP settings, as well as the limitations of the LDAP support.

LDAP can be complex to configure. Sysdig strongly recommends that you first refine your LDAP configuration in a separate test setup before applying the LDAP settings in your production environment. If you do not have a “development license” for test purposes or have misplaced your license information, contact <billing@sysdig.com.>

Summary of Functionality

Independent of the LDAP feature, the Sysdig platform ordinarily maintains its own user database to hold not only a username and password hash but also settings for Admin privileges, Sysdig team membership, and a user’s configured Dashboards and Alerts. Sysdig’s LDAP authentication feature provides a means to allow the Sysdig platform to query your separate directory server to validate username/password. Upon successful authentication, a corresponding user record in the Sysdig platform’s user database is automatically created. When the LDAP feature is in use, the user’s directory password is not stored in the Sysdig user database.

Once LDAP authentication is enabled, all normal user authentication will be performed against your configured directory server. Other local, non-LDAP users that were created before LDAP was enabled can still authenticate via LDAP as long as their username in your directory matches with the the username of their pre-existing record in the Sysdig user database. For example, consider a user jdoe@example.com who had been a user in the Sysdig environment before LDAP was enabled. Once LDAP authentication is enabled, if a user jdoe exists in the directory server and is able to authenticate successfully via LDAP, they will be permitted to log in to the Sysdig platform as the pre-existing jdoe@example.com user. Any user-specific configuration (Alerts, Dashboards, etc.) that were attached to jdoe@example.com will still be visible to this user. Any password previously set for such a pre-existing user record will not be used for authentication to the Sysdig platform unless LDAP authentication is disabled.

Upgrades - Migration of Settings

Note: This section is only relevant if you have already been using LDAP support as it existed in Sysdig platform version 858 and earlier and are upgrading to version 1149 or newer. If you are configuring LDAP for the first time and are running version 1149 or newer, skip this section.

LDAP support in version 858 and older was configured exclusively via the Replicated console or Kubernetes ConfigMap, depending on your installation type. This required the Sysdig platform to be restarted after any changes to the LDAP settings. When you upgrade your environment to version 1149 or newer, your existing settings will be migrated to a new API-based configuration described below. The only LDAP-related setting that remains in the Replicated console is the optional CA certificate for LDAPS connectivity.

For Kubernetes-based installs, you should leave the prior LDAP settings intact to ensure successful migration upon upgrade. But once you are successfully running version 1149 or newer, all elements that begin with sysdigcloud.ldap can be removed from your ConfigMap.

Prerequisite: The “Super” Admin user

In an environment enabled for LDAP authentication, the one user still subject to direct email+password authentication is the “super” Admin user. Creation of this user is a required initial install step either via the Replicated console (see screenshot below) or Kubernetes ConfigMap element sysdigcloud.default.user.

This user is required and cannot be deleted. This login provides:

• A way to access the Sysdig platform when LDAP connectivity is severed.

• The first Admin user in the install, essential for assigning Admin rights to other users once they’ve authenticated via your directory and their user records have been added to the Sysdig user database.

• The user whose REST API Token can be used to perform further LDAP configurations via the Sysdig platform API.

Once other directory-authenticated users have been promoted to Admins, those Admins can promote other directory-authenticated users to Admin, and so on.

Configuration of Base LDAP Settings

The configuration of the LDAP feature can be viewed, updated, and deleted by the “super” Admin via the API endpoint /api/admin/ldap/settings using HTTP methods for GET, POST, and DELETE, respectively.

NOTE: See the REST API page for general info on the API, and the the Locating the “Super” Admin User page for guidance on finding the token for the appropriate “super” Admin user.

A version of a login_config.sh helper script is available in a beta branch of the sysdig-cloud-scripts repository for your use along with an example settings_login_simple.json that can be modified for your environment. Refer to the tables for details on config options. Example command-lines below the table describe how to enable LDAP with these settings.

The follow settings are in the required loginConnectionSettings section.

# openssl s_client -showcerts -connect <server-ip>:636

-----BEGIN CERTIFICATE-----
[random text...]
-----END CERTIFICATE-----

cn=Administrator,cn=Users,dc=example,dc=local

dc=example,dc=local

The following settings are in the optional loginFilter section:s

cn=Users

cn=Users,dc=example,dc=local

(&(objectClass=organizationalPerson)(sAMAccountName={0}))

To use the helper script, modify the env.sh to set the required values for API_TOKEN and URL for your environment. Once set, invoking login_config.sh with no options will print the current configuration. If you were running Sysdig platform version 858 or older and have just upgraded to version 1149 or newer, you will see your migrated settings. Otherwise, the LDAP feature will start out disabled ("enableLdapAuthentication": false) and other configuration settings will not be shown.

# ./login_config.sh
{
    "ldapSettings": {
        "enableLdapAuthentication": false,
        "version": 1
    }
}

Using the guidance in the settings table above, modify the settings_login_simple.json as necessary to allow for connectivity and querying of users in your directory server. To apply the new LDAP settings, invoke login_config.sh with the -s option and specify the filename containing the JSON config, . If successful, the applied configuration will be echoed back by the API.

# ./login_config.sh -s settings_login_simple.json
{"ldapSettings":{"version":2,"loginConnectionSettings":{"server":"ldap://172.16.0.1","rootDn":"dc=example,dc=local","managerDn":"cn=Administrator,cn=Users,dc=example,dc=local","managerPassword":"myMgrPassword","referral":"IGNORE"},"loginFilter":{"searchBase":"cn=Users","searchFilter":"(&(objectClass=organizationalPerson)(sAMAccountName={0}))"},"enableLdapAuthentication":true}}

Using the specific example settings_login_simple.json and the minimal Active Directory configuration in the screenshot below, login to the Sysdig platform would now be permitted for a user jdoe that has distinguishedName:

CN=John Doe,CN=Users,DC=example,DC=local

To delete LDAP settings, invoke login_config.sh with the -d option. This should be used with caution, as this will prevent all LDAP users from being able to log in to the Sysdig platform!

# ./login_config.sh -d
{"ldapSettings":{"version":3,"enableLdapAuthentication":false}}

Group Membership Configuration (deprecated)

The LDAP feature as it existed in version 858 and earlier included optional additional settings that, when specified, ensured that authenticated users were also members of one or more groups before permitting them to login to the Sysdig platform. These settings are documented here for the benefit of those who used these settings in the past and have had their settings migrated to the newer API-based configuration, where they become part of the **loginFilter **section. See below for details on how to use the searchFilter instead to achieve equivalent functionality.

For use with the login_config.sh helper script, an example settings_login_group_deprecated.json is provided that can be modified for your environment based on the table below. Example command-lines are shown below the table.

ou=Planets

(&(cn=Mars)(objectclass=group))

(| (member={0}) (uniqueMember={0}) (memberUid={1}))

Using the specific example settings_login_group_deprecated.json and the minimal Active Directory configuration in the screenshot below, login to the Sysdig platform would be permitted for this user who belongs to the Mars group.

But jdoe user who is not a member would be prevented from logging in.

To simplify your configuration and avoid use of these deprecated options, an equivalent configuration can be achieved by making the group membership part of the searchFilter:

"searchFilter": "(&(memberOf=CN=Mars,OU=Planets,DC=example,DC=local)(objectClass=organizationalPerson)(sAMAccountName={0}))"

See the example settings_login_group.json for an updated configuration that can be compared side-by-side with settings_login_group_deprecated.json.

Multi-Server Directories

Data about your users that need to access the Sysdig platform may be stored across many directory servers in your environment. As the Sysdig platform is only able to query one LDAP server endpoint, you would need to take extra steps to ensure successful authentication for such users.

The simplest approach to achieve this is to query against a Global Catalog. As the Global Catalog stores a copy of all Active Directory objects in a forest, this provides a fast and convenient target for the Sysdig platform to find all users that may need to authenticate. Since queries against the Global Catalog are also performed via LDAP, you simply need to ensure your LDAP configuration specifies the appropriate address and TCP port for the Global Catalog, e.g. ldap://176.16.0.1:3268 for cleartext LDAP or ldaps://172.16.0.1:3269 for LDAP over SSL. If querying against a Global Catalog, the referral option of the Sysdig platform’s LDAP configuration can remain at its default setting of "IGNORE".

If a Global Catalog is not available, another approach is to leverage referral chasing. Such chasing depends on the complex interplay of configuration settings, DNS resolution, and network connectivity to multiple servers. If you require this option, carefully read the tips in this section and validate your configuration in a test environment before attempting its use in production. Contact Sysdig support for assistance as necessary.

For our example configuration, we’ve added another Domain Controller to our environment that holds users a separate set of users for the child domain eu.example.local.

We’d like to permit login for a user “eurodude” in the child domain. This user has distinguishedName:

CN=Euro Dude,CN=Users,DC=eu,DC=example,DC=local

In the example configuration settings_login_referral_follow.json shown below, the Sysdig platform still begins its LDAP queries at the same top-level server target. However, the referral option is set to "FOLLOW", which will cause the Sysdig platform to perform subsequent queries if a query returns one or more referrals.

{
  "loginConnectionSettings": {
    "server": "ldap://172.16.0.1",
    "managerDn": "cn=Administrator,cn=Users,dc=example,dc=local",
    "managerPassword": "myMgrPassword",
    "referral": "FOLLOW"
  },
  "loginFilter": {
    "searchBase": "dc=example,dc=local",
    "searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName={0}))"
  },
  "enableLdapAuthentication": true
}

Note also how in this case the rootDn option is left unspecified and the searchBase is set to the distinguished name of the top-level domain. This is necessary to ensure the scope of the chased referral queries will include the child domain. If **rootDn **and searchBase had been left as they were set in the settings_login_simple.json example, the initial query would have been targeted only within cn=Users,dc=example,dc=local and hence the referral would never have been returned by the top-level server.

Note these other caveats of referral chasing in the Sysdig platform:

• Referrals may only be successfully chased to child domains. If referrals point to parallel domains (e.g. for our example, dc=adjacent,dc=local) the queries will not succeed and users stored in the directory servers for such domains will not be able to authenticate.

• The LDAP library used by the Sysdig platform does not log information about each referral it attempts to chase. Therefore, if you enable referral chasing, it is important that you understand the server targets that may be chased in your environment and ensure the network connectivity (routing/firewalls) will permit the Sysdig platform to query these server targets. If LDAP queries are failing due to a network connectivity issue, this will typically be accompanied by delays during Sysdig user logins of approximately 30 seconds followed by a login failure with an HTTP 504 error message shown in the login screen. If this occurs, contact Sysdig support for assistance.

Testing User Login

To test the login configuration, the “super” Admin user can confirm if a particular user would be permitted to login given current LDAP login connection settings. To do this, perform an HTTP GET to the API endpoint /api/admin/ldap/settings/verify/USERNAME . A verify_user.sh helper script is provided to easily perform this. If invoked with the -u option and a username, and the user’s login would be successful, it will return the user’s information from the directory.

# ./verify_user.sh -u jdoe
{"element":"uSNCreated=12799, countryCode=0, badPwdCount=0, whenChanged=20180406232737.0Z, objectClass=top, primaryGroupID=513, givenName=John, objectGUID=..., objectSid=..., instanceType=4, whenCreated=20180406220651.0Z, dSCorePropagationData=16010101000000.0Z, sn=Doe, userAccountControl=66048, lastLogonTimestamp=131675308573317669, cn=John Doe, codePage=0, accountExpires=9223372036854775807, sAMAccountName=jdoe, sAMAccountType=805306368, userPrincipalName=jdoe@example.local, displayName=John Doe, pwdLastSet=131675260113435098, lastLogon=131682933890462204, name=John Doe, objectCategory=CN=Person,CN=Schema,CN=Configuration,DC=example,DC=local, distinguishedName=CN=John Doe,CN=Users,DC=example,DC=local, lastLogoff=0, memberOf=CN=Sysdig Viewers,CN=Users,DC=example,DC=local, logonCount=0, uSNChanged=12986"}

If the user would not be able to login, an error message will be returned.

# ./verify_user.sh -u nothere
Could not verify user "nothere". Check LDAP login config settings and/or system log.

Note that if LDAP authentication is disabled this method for testing user login is not available.

Creating LDAP Users Before They Login

The default behavior of the LDAP feature is to create a new record in the Sysdig user database when a user authenticates successfully via LDAP for the first time. However, it may be desirable to add such user records in advance of their first login, such as if you wish to use automation to change user permissions, assign team membership, or pre-populate Dashboard/Alert configurations. A create_user.sh helper script is available in the sysdig-cloud-scripts repository to create such user records via the API. This script can also be used to enable/disable this functionality in the Sysdig platform. See the README for details.

Additional details regarding this type of user creation in conjunction with LDAP authentication:

• This method allows creation of any username, even if it doesn’t currently exist in the directory that is queried via LDAP.

• When LDAP authentication is enabled, such users can be created with a simple username (e.g. jdoe ) or with an email-style postfix (as is typical for non-LDAP Sysdig user, e.g. jdoe@example.com ). In this latter case only the username portion ( jdoe ) is used when the Sysdig platform is performing an LDAP query during attempted login.

• While the password must be included in the config you POST to create the user, it is not used by the Sysdig platform when LDAP is enabled, as authentication will always be performed via LDAP. For this same reason, if a user has been created in this way, they will not be able to login unless there is a matching user in the directory that is queried via LDAP.

• The firstName and lastName values as specified in the example are optional and independent from any equivalent name settings in the directory that is queried via LDAP.

Limitations and Caveats

• LDAP support has been tested with Active Directory in Windows Server 2012 R2. It may work with AD versions that ship with other versions of Windows, or other directory servers that use the LDAP protocol. If you are intending to use LDAP with something other than Active Directory, please contact Sysdig Support.

• The LDAP feature is only present in Sysdig software platform installs (not the SaaS version).

• Only one LDAP config can exist per deployment (i.e. the platform can only query one directory server endpoint).

• Because the Sysdig software platform is based on the same technology as the SaaS-based Sysdig service, it theoretically supports the configuration of multiple “customers” using the same install. However, the multi-customer option is not supported when the LDAP feature is enabled.

• When LDAP authentication is enabled, adding users via email “invites” is not possible.

• LDAP authentication for directory usernames that begin or end with a space character (e.g. " jdoe" or "jdoe " ) are not supported.

• Configuration entries that contain special characters (for instance, a managerPassword that contains a backslash character) are supported, but note that you will need to perform proper JSON escaping in the configuration you POST to the API. If you attempt to post invalid JSON, the helper scripts will return an error message. If this occurs, you can use tools such as JSONLint to narrow down the source of the problem and/or JSON String Escape to learn how to properly escape your text.

• The LDAP feature does not attempt any ongoing “sync” back from the Sysdig platform user database to the directory server. Note how this impacts the following:

  • If a user is deleted from the directory server, their user record will remain in the Sysdig user database until a Sysdig Admin deletes it. Of course, that user will not be able to login since they will no longer be able to authenticate successfully via LDAP.

  • If an Admin deletes a user from the Sysdig user database, but the user can still authenticate successfully via LDAP, their Sysdig user record will be recreated if they login again via LDAP.

  • If a person’s username should change in the directory server (e.g. the value for sAMAccountName in our examples above), the next time they login, a new user record will be created for them in the Sysdig user database. Settings they previously had in the Sysdig platform such as Admin rights and Alerts/Dashboard configurations will not be present for this recreated user.

• Other LDAP-centric functionality that is not currently supported (not an exhaustive list):

  • Mapping a user in the directory server to the Sysdig “super” Admin (such as to avoid the need to configure the this “super” Admin user).

  • Session expiry based on configuration in the directory server (such as to set a user account to only be valid until a certain date).

  • Login policies based on configuration in the directory server (such as to restrict login to certain hours).

  • User timeout functionality (such as to remove a user from the Sysdig user database if they have not logged in for a certain amount of time).

4.3 - Mapping LDAP Users to Sysdig Teams

LDAP support in the Sysdig on-premises platform allows user authentication via credentials stored in your own directory server. Once LDAP authentication is configured, the optional mapping feature can be used to map groups of users from your directory to Sysdig teams.

How It Works

After basic LDAP integration, records in the Sysdig user database are automatically created when users successfully authenticate via LDAP the first time. Then a Sysdig Admin could add/remove them from Sysdig teams and change their roles in those teams.

To eliminate this manual workflow, LDAP mapping provides a policy-driven, automated way to use relevant information from your directory to affect the lifecycle of such users/teams. This is achieved by creating LDAP-mapping rules that identify groups of users in your directory and port them to Sysdig’s database, specifying teams in which they should be members and their roles in those teams. LDAP-mapping rules trigger the automatic creation of such users and teams in the Sysdig platform database, and ongoing synchronization ensures the Sysdig platform database always reflects the current state of your directory, such as when users are deleted from your directory or are no longer members of a group.

Process Overview

1. Configure Basic LDAP.

   Note that in the process, you modify env.sh with token and authentication credentials.

2. Download Helper Scripts.

3. Configure settings_mapping_simple.json.

4. Deploy mapping_config.sh file (various options).

Prerequisites

Configure Basic LDAP

• Have “super” admin credentials available.

  See Find the Super Admin Credentials and API Token.

• Configure basic LDAP integration and ensure users can log in successfully via LDAP.

  The script-based option is usually employed. The steps include modifying the env.sh to add your environment URL and authorization token.

Download Helper Scripts

Scripts and sample files are found in GitHub:

• Sample .json to modify: settings_mapping_simple.json

• Helper script: mapping_config.sh

Configure settings_mapping_simple.json

Note that if you only want to create users via LDAP and map them to Sysdig teams, you will use the settings_mapping_simple.json.

If you want to map users and also enable log on through SAML single-sign-on, you will use the settings_mapping_hybrid.json.

Structure of settings_mapping_simple.json

{
    "ldapTeamMapping": [
      {
        "ldapFilterSettings": {
          "searchFilter": "(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Viewers,CN=Users,DC=example,DC=local)(sAMAccountName=*))",
          "searchBase": "cn=Users"
        },
        "teams": [
          "Viewers"
        ],
        "teamRole": "ROLE_TEAM_READ",
        "usernameAttribute": "sAMAccountName"
      },
      {
        "ldapFilterSettings": {
          "searchFilter": "(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*))",
          "searchBase": "cn=Users"
        },
        "teams": [
          "Editors1",
          "Editors2"
        ],
        "teamRole": "ROLE_TEAM_EDIT",
        "usernameAttribute": "sAMAccountName"
      },
      {
        "ldapFilterSettings": {
          "searchFilter": "(&(objectClass=organizationalPerson)(givenName=Mary))",
          "searchBase": "cn=Users"
        },
        "teams": [
          "Mixed"
        ],
        "teamRole": "ROLE_TEAM_EDIT",
        "usernameAttribute": "sAMAccountName"
      },
      {
        "ldapFilterSettings": {
          "searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName=jdoe))",
          "searchBase": "cn=Users"
        },
        "teams": [
          "Mixed"
        ],
        "teamRole": "ROLE_TEAM_READ",
        "usernameAttribute": "sAMAccountName"
      }
    ],
    "teamDefinitions": [
      {
        "name": "Mixed",
        "products": ["SDC"],
        "show": "host"
      },
      {
        "name": "Viewers",
        "products": ["SDC"],
        "show": "host"
      },
      {
        "name": "Editors1",
        "products": ["SDC"],
        "show": "host"
      },
      {
        "name": "Editors2",
        "products": ["SDC"],
        "theme": "#FF5C49",
        "show": "container",
        "filter": "container.image contains \"mysql\"",
        "canUseSysdigCapture": false,
        "canUseCustomEvents": false,
        "canUseAwsMetrics": false,
        "entryPoint": {
          "module": "Dashboards"
        }
      }
    ],
    "dryRun": true
}

ldapTeamMapping Parameters

Each of the options in the first table is Required.

"searchFilter": "(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*))",
"searchBase": "cn=Users" 

"teams": [
  "Web Devs",
  "DBAs"
}

"teamRole": "ROLE_TEAM_EDIT"

ldapTeamMapping Parameters

The Settings below define when and how synchronization is performed between your directory and the Sysdig database:

"teamDefinitions": [
  {
    "name": "Mixed",
    "show": "host"
  }
] 

LDAP Sync Process Settings

"defaultTeamRole": "ROLE_TEAM_EDIT"

teamDefinitions Settings

Options for Applying mapping_config.sh

Apply the LDAP configuration settings the JSON file using the mapping.config.sh.

For example:

mapping_config.sh -s settings_mapping_simple.json

The following sections provide examples for applying settings, forcing synchronization, deleting settings, and reporting status using mapping_config.sh.

mapping_config.sh Option Summary

Print Current Configuration

Once set, invoking mapping_config.sh with no options will print the current configuration. If you haven’t yet configured any mapping rules, the config shown will start out empty:

# ./mapping_config.sh
{
    "ldapSyncSettings": {
        "dryRun": false,
        "ldapTeamMapping": [],
        "maxAllowedMappedUsers": 100,
        "syncIntervalMinutes": 10,
        "syncTimeoutSeconds": 120,
        "teamDefinitions": [],
        "version": 1
    }
}

Apply New Settings -s

To apply new mapping settings, invoke mapping_config.sh with the -s option and specify the filename containing the JSON config. If successful, the applied configuration will be echoed back by the API.

# ./mapping_config -s settings_mapping_simple.json{"ldapSyncSettings":{"version":2,"ldapTeamMapping":[{"ldapFilterSettings":{"searchBase":"cn=Users","searchFilter":"(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Viewers,CN=Users,DC=example,DC=local)(sAMAccountName=*))"},"teams":["Viewers"],"teamRole":"ROLE_TEAM_READ","usernameAttribute":"sAMAccountName"},{"ldapFilterSettings":{"searchBase":"cn=Users","searchFilter":"(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*))"},"teams":["Editors1","Editors2"],"teamRole":"ROLE_TEAM_EDIT","usernameAttribute":"sAMAccountName"},{"ldapFilterSettings":{"searchBase":"cn=Users","searchFilter":"(&(objectClass=organizationalPerson)(givenName=Mary))"},"teams":["Mixed"],"teamRole":"ROLE_TEAM_EDIT","usernameAttribute":"sAMAccountName"},{"ldapFilterSettings":{"searchBase":"cn=Users","searchFilter":"(&(objectClass=organizationalPerson)(sAMAccountName=jdoe))"},"teams":["Mixed"],"teamRole":"ROLE_TEAM_READ","usernameAttribute":"sAMAccountName"}],"teamDefinitions":[{"version":0,"customerId":0,"immutable":false,"name":"Mixed","show":"host","origin":"SYSDIG","products":["SDC"],"entryPoint":{"module":"Explore"},"properties":{},"dateCreated":1537312025306,"canUseSysdigCapture":true,"canUseCustomEvents":true,"canUseAwsMetrics":true,"default":false,"userRoles":[]},{"version":0,"customerId":0,"immutable":false,"name":"Viewers","show":"host","origin":"SYSDIG","products":["SDC"],"entryPoint":{"module":"Explore"},"properties":{},"dateCreated":1537312025306,"canUseSysdigCapture":true,"canUseCustomEvents":true,"canUseAwsMetrics":true,"default":false,"userRoles":[]},{"version":0,"customerId":0,"immutable":false,"name":"Editors1","show":"host","origin":"SYSDIG","products":["SDC"],"entryPoint":{"module":"Explore"},"properties":{},"dateCreated":1537312025306,"canUseSysdigCapture":true,"canUseCustomEvents":true,"canUseAwsMetrics":true,"default":false,"userRoles":[]},{"version":0,"customerId":0,"immutable":false,"filter":"container.image contains \"mysql\"","name":"Editors2","theme":"#FF5C49","show":"container","origin":"SYSDIG","products":["SDC"],"entryPoint":{"module":"Dashboards"},"properties":{},"dateCreated":1537312025307,"canUseSysdigCapture":false,"canUseCustomEvents":false,"canUseAwsMetrics":false,"default":false,"userRoles":[]}],"syncIntervalMinutes":10,"dryRun":true,"maxAllowedMappedUsers":100,"syncTimeoutSeconds":120}}

Force a Sync -f

To force an immediate sync operation to apply the mapping roles, invoke the -f option, which performs a PUT on the /api/admin/ldap/syncLdap endpoint:

# ./mapping_config.sh -f
Forcing sync

To apply a new setting and force an immediate synchronization, combine the two functions:

# ./mapping_config.sh -s settings_mapping_simple.json -f
{"ldapSyncSettings": ... }}
Forcing sync

Report Current State -r

To see the mapped users/teams state and changes/problems from the most recent sync operation, view the report using the -r option, which performs a GET on the /api/admin/ldap/syncReport endpoint.

This same report information is in the system log for every sync operation.

(Note that the Warning in this report is discussed in the Error Messages section below.)

# ./mapping_config.sh -r
{
    "ldapSyncReport": {
        "changesApplied": true,
        "conflictingTeamNames": [],
        "duration": 368,
        "lastSyncEnd": 1537312224878,
        "lastSyncEndReadable": "9/18/18 11:10 PM",
        "lastSyncStart": 1537312224510,
        "teamsMapped": [
            "Mixed",
            "Editors1",
            "Viewers",
            "Editors2"
        ],
        "teamsToRemove": [],
        "teamsToSave": [
            "Mixed",
            "Editors1",
            "Viewers",
            "Editors2"
        ],
        "unmappedUser": {},
        "usersMappings": [
            {
                "teams": {
                    "Mixed": "ROLE_TEAM_READ",
                    "Viewers": "ROLE_TEAM_READ"
                },
                "username": "jdoe@example.local"
            },
            {
                "teams": {
                    "Mixed": "ROLE_TEAM_EDIT",
                    "Viewers": "ROLE_TEAM_READ"
                },
                "username": "mpeterson@example.local"
            },
            {
                "teams": {
                    "Editors1": "ROLE_TEAM_EDIT",
                    "Editors2": "ROLE_TEAM_EDIT",
                    "Mixed": "ROLE_TEAM_EDIT"
                },
                "username": "msmith@example.local"
            }
        ],
        "version": 5,
        "warnings": [
            "LDAP mapping LdapMapping(ldapFilterSettings=LdapFilterSettings(searchBase=cn=Users, searchFilter=(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*)), groupSearchBase=null, groupSearchFilter=null, groupMembershipFilter=null), teams=[Editors1, Editors2], teamRole=ROLE_TEAM_EDIT, usernameAttribute=mail) matched 2 entities that has no requested username attribute"
        ]
    }
}

Delete Settings -d

To delete all LDAP mapping settings, invoke the -d option, optionally adding the -f option to force an immediate sync.

# /mapping_config.sh -d
{"ldapSyncSettings":{"version":31,"ldapTeamMapping":[],"syncIntervalMinutes":10,"dryRun":false,"maxAllowedMappedUsers":100}}

# ./mapping_config.sh -d -f
{"ldapSyncSettings":{"version":4,"ldapTeamMapping":[],"teamDefinitions":[],"syncIntervalMinutes":10,"dryRun":false,"maxAllowedMappedUsers":100,"syncTimeoutSeconds":120}}
Forcing sync

Sample Use Cases

The sample settings_mapping_simple.json illustrates some common use cases.

Consider a minimal Active Directory with the following users:

Presume the groups Sysdig Viewers and Sysdig Editors are defined in the Active Directory with the listed memberships:

Mapping Users to Teams 1:1

The first mapping rule shows a simple 1-to-1 mapping of all the users in the Sysdig Viewers group in our directory to a Sysdig team called Viewers in which these users will have Read-only permission.

{
    "ldapFilterSettings": {
        "searchBase": "cn=Users",
        "searchFilter": "(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Viewers,CN=Users,DC=example,DC=local)(sAMAccountName=*))"
    },
    "teamRole": "ROLE_TEAM_READ",
    "teams": [
        "Viewers"
    ],
    "usernameAttribute": "sAMAccountName"
}

Mapping Users in a Group to Multiple Teams

The second mapping rule illustrates how to map the Sysdig Editors group of users to more than one Sysdig team (Editors1 and Editors2), granting Read/Write access in both teams.

{
    "ldapFilterSettings": {
        "searchBase": "cn=Users",
        "searchFilter": "(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*))"
    },
    "teamRole": "ROLE_TEAM_EDIT",
    "teams": [
        "Editors1",
        "Editors2"
    ],
    "usernameAttribute": "sAMAccountName"
}

Complex Mapping Example

The third and fourth rules illustrate the flexibility of how groups are handled by the Sysdig LDAP Mapping feature.

The third rule shows how users targeted by a mapping rule can ultimately be anything specified by a searchFilter. In this contrived example, we’ve targeted all users with the first name “Mary” and mapped them to a Sysdig team called “Mixed” where they will have Read/Write permissions.

The fourth rule builds on the third, showing how to combine multiple rules to target different groups of users from the directory and potentially assign them different permissions in the same Sysdig team. Here we target our single “John Doe” user and also map him to the “Mixed” team, but with Read-Only access.

{
  "ldapFilterSettings": {
    "searchFilter": "(&(objectClass=organizationalPerson)(givenName=Mary))",
    "searchBase": "cn=Users"
  },
  "teams": [
    "Mixed"
  ],
  "teamRole": "ROLE_TEAM_EDIT",
  "usernameAttribute": "sAMAccountName"
},
{
  "ldapFilterSettings": {
    "searchFilter": "(&(objectClass=organizationalPerson)(sAMAccountName=jdoe))",
    "searchBase": "cn=Users"
  },
  "teams": [
    "Mixed"
  ],
  "teamRole": "ROLE_TEAM_READ",
  "usernameAttribute": "sAMAccountName"
}

Notes on Mapping Behaviors

As the examples show, the LDAP mapping configuration is flexible and powerful. However, misconfigurations (such as mistakes in filter syntax) may trigger the unintentional creation/deletion of excess user and/or team data. It is recommended to use the dryRun option extensively, particularly when first becoming familiar with the feature. The following notes about the constraints and side-effects of LDAP mapping should also be considered.

• During sync, if a user from the directory matches on a mapping rule and does not yet exist in the Sysdig user database, it will be auto-created in the Sysdig database at that time. These will start out as non-Admin users, but could be promoted to Admin by a Sysdig Admin once their record has been auto-created.

• As with other Sysdig teams, all Sysdig Admin users will automatically be members of all LDAP-mapped teams.

• During sync, if a mapped team specified in a rule and teamDefinitions array does not yet exist in the Sysdig database, it will be auto-created in the Sysdig database at that time. If a sync would result in the creation of a team that has the same name as a non-mapped team that already exists (i.e. one that was created previously by a Sysdig Admin), the mapped team will not be created and no mapping of users to that team will be performed. This will also be noted in the system log.

• If an LDAP-mapped user is no longer a match in a particular LDAP-mapped team, they will be removed from that team. Any team-specific data attached to that user (e.g. Dashboards) will not be deleted.

  • Dashboards that were Shared by that user within the team will remain visible to other team members.

  • Personal Dashboards for that user will effectively be hidden, though if the user is mapped to the team again, they will be visible to that user again.

• An LDAP-mapped user that no longer is a match on their last remaining LDAP-mapped team will be moved to the Default Team. This is to ensure against accidental deletion of the user’s data in the event of configuration mistakes. If desired, a Sysdig Admin can perform a final delete of the user record through the UI or API, which would result in deletion of all data attached to that user in all teams.

• If a user is mapped to the same team via multiple rules, and the teamRole settings differ between the rules, the most generous setting will apply (i.e. ROLE_TEAM_EDIT).

• Membership of LDAP-mapped teams is controlled exclusively via mapping rules. The Sysdig web UI will prevent membership changes in such teams.

• The searchFilter entries in LDAP mapping rules are independent from the base LDAP loginFilter that is used for authentication. It is therefore possible for LDAP mapping rules to trigger creation of Sysdig user records for users that may not yet be able to login to the Sysdig platform.

• No changes made within the Sysdig database will result in any modifications to the directory being queried via LDAP (i.e. sync is a “one-way” operation from directory to the Sysdig database).

• See General LDAP Tipsfor more guidance to assist with debugging or perfecting your LDAP configuration.

Error Messages

Consider the following LDAP mapping excerpt:

{
    "ldapFilterSettings": {
        "searchBase": "cn=Users",
        "searchFilter": "(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*))"
    },
    "teamRole": "ROLE_TEAM_EDIT",
    "teams": [
        "Editors1",
        "Editors2"
    ],
    "usernameAttribute": "mail"
}

In the Report section above, there was a warning:

"warnings": [
    "LDAP mapping LdapMapping(ldapFilterSettings=LdapFilterSettings(searchBase=cn=Users, searchFilter=(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*)), groupSearchBase=null, groupSearchFilter=null, groupMembershipFilter=null), teams=[Editors1, Editors2], teamRole=ROLE_TEAM_EDIT, usernameAttribute=mail) matched 2 entities that has no requested username attribute"
]

This was because two of the user records that matched our searchFilter (that is, they were members of the “Sysdig Editors” group in Active Directory) each had an empty mail attribute in AD. The LDAP Mapping configuration would have ordinarily resulted in the creation of these user records in the Sysdig platform user database, but since the usernameAttribute setting pointed the Sysdig platform at these empty mail values, the error message alerts us to this fact.

If these sort of empty attributes are typical for your AD environment, the error message can be ignored.

Similarly, if such attributes were not unique (i.e., multiple Mapped users were found to have the same email address), the error message would be:

"warnings": [
    "Duplicate username founds. They will be ignored in mapping: [duplicates@example.local]"
]

4.4 - LDAP/SAML Hybrid Authentication

This is an advanced option wherein LDAP Mapping is used to trigger the creation of user records in Sysdig, but authentication of those users is actually performed via SAML (with LDAP-based authentication disabled). In this configuration, if a user successfully authenticates via SAML, and the platform finds a user record with a matching email address in the Sysdig platform, they will be permitted to log in.

The process involves:

1. Enable SAML login and disable automatic user creation via SAML.

2. Enable LDAP user creation using LDAP mapping, but employ the _hybrid, rather than the _simple json configuration file.

3. (Optional) Disable user creation via API.

4. (Optional) Disable simple password login, to ensure SAML SSO is always used.

5. Ensure SAML has been enabled in the UI as the chosen authentication method.

Enable SAML Log In

1. Follow the instructions for SAML (On-Prem) configuration for your IdP. Use the UI in Sysidg Platform version 3.5.0, or the script-based option for earlier versions.

2. To ensure that user records are created solely via LDAP mapping, disable user-creation-on-demand and (optionally) password authentication.

   1. UI-based option: Use the toggles in the UI to disable “create user on login” and “user name and password login.”

      

   2. Script-based option: Use the -n option of the saml_config.sh script, as described in the Optional: Auto-creation of user records section.

3. User experience:

   With this configuration, if a user successfully logs in via SAML but does not have an existing username/email record in the Sysdig database, they will receive an error message.

   

Enable LDAP User Creation using LDAP Mapping

1. Configure the settings_mapping_hybrid.json file.

   The only difference between the _simple and the _hybrid files is the userAttributeName value. In _hybrid, this is set to email, because SAML-derived usernames in the Sysdig platform area always based on email address.

2. Apply the settings using the mapping_config.sh script:

   mapping_config.sh -s settings_mapping_hybrid.json
   

   See also: Options for Applying mapping_config.sh.

Optional: Disable User-Creation via API

If you want to ensure your user records are derived only from LDAP hybrid mapping, then use the -d option with the api_user_creation.sh script, as described in the Readme.

Optional: Disable Password Login

You may have pre-existing records in your Sysdig platform database for users who have previously authenticated via simple email/password. If you want to prevent such logins and ensure 100% authentication via SAML, you can disable password login.

In this configuration, only the “super” Admin can still login via email/password.

See Disable Password Authentication.

Ensure SAML is Enabled in the UI

When all configurations are complete, log in to the Settings in the Sysdig user interface and Select SAML for SSO, if it is not already selected.

5 - Disable Password Authentication

Sysdig Platform supports disabling password-based authentication on both SaaS and on-prem deployments. As an administrator (super administrator for on-prem), you can use an API to achieve it. This configuration is applicable to those who use single sign-on.

On-Prem Deployments

As a super administrator, perform the following:

1. Get the Sysdig Platform settings:

   GET https://<URL-installation>/api/admin/auth/settings
   

   Replace <URL-installation> with the URL of your on-prem deployment.

2. Retrieve the specific settings associated with the SSO setup. In a typical scenario, only one IDP exists per deployment.

   GET https://<URL-installation>/api/auth/settings/{id}
   

   The setting is displayed in a JSON file.

3. In the JSON file, change the following from false to true:

   settings/forbidPasswordLogin: True
   

4. Update the setting with a request to the same URL with the same JSON, with the changed parameter. URL depends on the type of deployment.

   PUT https://app.sysdigcloud.com/api/admin/auth/settings/{id}
   

Migrating from the ConfigMap Method

Previously, the sysdigcloud.restrict.password.login parameter in the Kubernetes ConfigMap has been used to disable password authentication. After installing 3.2.0, deployments utilizing the sysdigcloud.restrict.password.login settings will be automatically migrated to use the new settings.

6 - Configure Split DNS

Split Domain Name System (Split DNS) is a configuration in which two DNS servers (sub-domains) are created for the same domain, one for the internal network and the other for the external, as a means to tighten the security. In this setting, internal hosts are directed to an internal domain name server and external hosts are directed to an external domain name server for name resolution.

In environments where Sysdig Platform is available through an Identity Provider (IDP) on two DNS records (split DNS), one set of users may not be able to log in to Sysdig, as the IDP redirects them only to a single DNS. In order to redirect users to the original DNS name they have requested, configure your deployment as given below.

Prerequisites

• You have the administrator privileges to configure Split DNS.

• Sysdig Platform is installed on-premises.

• Sysdig Platform is available on two or more DNS names. 

• Users are accessing the Sysdig Platform by using two DNS names.

• Users are required to be redirected to the original DNS name.

Supported IDP Protocols

• SAML

• OpenID Connect

Sysdig Platform Configuration

The topic assumes the request flows through the following setup: Browser > Application Load Balancer (optional) > Kubernetes Ingress Controller > Sysdig NGINX > Sysdig API.

1. Configure the Ingress Controller.

   1. Open the Ingress Controller.

      kubectl get ingress -o yaml > ingress.yaml
      

   2. Edit the ingress.yaml file as follows:

      apiVersion: extensions/v1beta1
      kind: Ingress
      metadata:
      annotations:
      ingress.kubernetes.io/affinity: cookie
      ingress.kubernetes.io/session-cookie-name: INGRESSCOOKIEAPI
      kubernetes.io/ingress.class: haproxy
      creationTimestamp: "2019-12-23T14:45:07Z"
      generation: 1
      labels:
      app.kubernetes.io/managed-by: ingress-config
      app.kubernetes.io/name: ingress-config
      app.kubernetes.io/part-of: sysdigcloud
      role: ingress-config
      tier: infra
      name: sysdigcloud-api-ingress
      namespace: sysdigcloud
      resourceVersion: "156675"
      selfLink: /apis/extensions/v1beta1/namespaces/sysdigcloud/ingresses/sysdigcloud-api-ingress
      uid: 891a0a46-ce64-41e0-906b-31627306a844
      spec:
      rules:
      - host: <REPLACE WITH EXTERNAL DNS FQDN>
      http:
      paths:
      - backend:
      serviceName: sysdigcloud-api
      servicePort: 8080
      path: /
      - backend:
      serviceName: sysdigcloud-scanning-api
      servicePort: 80
      path: /api/scanning
      - host: <REPLACE WITH INTERNAL DNS FQDN>
      http:
      paths:
      - backend:
      serviceName: sysdigcloud-api
      servicePort: 8080
      path: /
      - backend:
      serviceName: sysdigcloud-scanning-api
      servicePort: 80
      path: /api/scanning
      tls:
      - hosts:
      - <REPLACE WITH EXTERNAL DNS FQDN>
      - <REPLACE WITH INTERNAL DNS FQDN>
      secretName: sysdigcloud-ssl-secret
      status:
      loadBalancer:
      ingress:
      - {}
      

   3. Apply the changes:

      kubectl apply -f ingress.yaml
      

2. Configure Nginx in the Kubernetes API pod.

   1. Open the configuration file corresponding to the sysdig-api deployment.

   2. Add the following snippet to the Nginx environment variables section:

       - name: NGINX_NOT_ON_EDGE
         value: "true"
      

   3. Apply the changes.

   4. Ensure that the following snippet is added to the Ngnix configuration file at /etc/nginx/conf.d/api.conf:

      proxy_set_header X-Forwarded-Host $host:$server_port;
      proxy_set_header X-Forwarded-Server $host;
      

IDP Configuration

1. Ensure that Single Sign On (SSO) configuration is completed on the Sysdig Platform side.

2. Retrieve the current SSO settings with the API:

   curl -v  -X GET -H "Accept: application/json" -H "Content-type: application/json" -H 'Authorization: bearer XXXXXX' https://<API ENDPOINT>/api/admin/auth/settings/{{settingsID}}| jq
   

3. In the JSON file obtained with the authenticationSettings object , add the following lines:

   "splitDnsSupport": true,
   "splitDnsOriginHostHeader": "x-forwarded-server",
   "splitDnsOriginSchemeHeader": "x-forwarded-proto"
   

4. (optional) If you are using OpenID Connect protocol for SSO, include settings.clientSecret , because it’s not returned with the API call:

   "clientSecret": "<Replace with your clientSecret>"
   

5. Update the authenticationSettings object with a PUT request to the same endpoint with the changes introduced in the previous steps. For example:

   curl -v -X PUT -H "Accept: application/json" -H "Content-type: application/json" -H 'Authorization: bearer xxxxxxx' https://<API ENDPOINT>/api/admin/auth/settings/1 -d'
   {
     "authenticationSettings": {
       "id": 1,
       "version": 5,
       "createdOn": 1577285950000,
       "modifiedOn": 1577350608000,
       "type": "openid",
       "scope": "SYSTEM",
       "settings": {
         "createUserOnLogin": true,
         "forbidPasswordLogin": false,
         "issuer": "https://<Replace with your issuer>.com",
         "clientId": "<Replace with your client_id>",
         "clientSecret": "<Replace with your client_secret>",
         "metadata": null,
         "splitDnsSupport": true,
         "splitDnsOriginHostHeader": "x-forwarded-server",
         "splitDnsOriginSchemeHeader": "x-forwarded-proto",
         "metadataDiscovery": true
       }
     }
   }'
   

   Replace <issuer>, <client_id>, and <client_secret> with your own.