This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

  • 1:
    • 2:
      • 2.1:
        • 2.2:
          • 2.3:
            • 2.4:
            • 3:
              • 3.1:
                • 3.2:
                  • 3.3:
                    • 3.4:
                    • 4:
                      • 4.1:
                        • 4.2:
                          • 4.3:
                            • 4.4:
                            • 5:
                              • 6:

                                Authentication and Authorization (On-Prem Options)

                                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:

                                TypeEnabled by DefaultIntegration Steps Required
                                User email/passwordYesNo
                                Google OAuthNoYes
                                SAMLNoYes
                                OpenID ConnectNoYes
                                LDAPNoYes

                                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)

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

                                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.

                                Config DetailOption
                                Client ID-i
                                Client Secret-e
                                Allowed Domains-a
                                Redirect URL-r

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

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

                                # ./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.

                                # Optional: OAuth allowed domains (comma separated list of domains) sysdigcloud.oauth.allowed.domains.list: "" # Optional: Sysdig Cloud Google OAuth Client ID sysdigcloud.google.oauth.client.id: "" # Optional: Sysdig Cloud Google OAuth Client Secret sysdigcloud.google.oauth.client.secret: ""

                                User Experience

                                Note the following requirements for successful Google OAuth login:

                                • The user must have already logged in successfully at least once to your environment (such as via email-based Invitation and having set an initial password)

                                • The user’s login username in the Sysdig platform must precisely match the user’s Google email address (that is, it cannot be a shortened/altered Google email alias)

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

                                If the user’s browser has not already successfully authenticated via Google and/or has multiple Google profiles known by their browser, they will be presented a Google page to select a profile and enter a password (if necessary) before being redirected back to your Sysdig environment.

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

                                2 -

                                SAML (On-Prem)

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

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

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

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

                                For specific IdP integration information, refer to:

                                See also Caveats, below.

                                Basic Enablement Workflow

                                Step

                                Options

                                Notes

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

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

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

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

                                Click SAML button

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

                                Type/bookmark a URL in browser

                                Monitor:https://HOSTNAME/api/saml

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

                                Log in from an IdP interface

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

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

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

                                Collect metadata URL (or XML) and test it.

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

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

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

                                 

                                Administrator Steps

                                Configure IdP

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

                                UI-Based: Configure SAML in Settings

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

                                To enable baseline SAML functionality:

                                Enter SAML Connection Settings

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

                                2. Select Authentication.

                                3. Select the SAML tab.

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

                                  It is strongly recommended that “Signed Assertion” and “Validate Signature” are enabled to ensure that the SAML SSO process is as secure as possible.

                                Connection SettingOptionsDescriptionSample Entry
                                MetadataURLThe URL provided at the end of the IdP configuration steps.
                                XMLAn option that can be used for an IdP that doesn’t support extracting metadata XML via URL.
                                Signed Assertionoff/onShould Sysdig check for assertions signed in responses (to assist in validating correct IdP).ON
                                Email ParameteremailName of parameter in the SAML response for user email ID. Sysdig uses this to extract the user’s email from the response.email
                                Validate Signatureoff/onSysdig backend should verify that the response is signed.ON
                                Verify Destinationoff/onFlag to control whether Sysdig should check the “destination” field in the SAMLResponse. Recommend ON, as a security measure. May be OFF in special cases, such as a proxy in front of the Sysdig back end.ON

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

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

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

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

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

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

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

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

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

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

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

                                Configure SAML Single Logout

                                Sysdig supports SAML Single Logout (SLO).

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

                                SLO Process

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

                                Caveats

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

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

                                Configure IdP

                                1. Configure logout URLs:

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

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

                                2. Choose HTTP Redirect as the binding method.

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

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

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

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

                                Configure Sysdig

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

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

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

                                3. Enter the SAML configuration.

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

                                5. Click Save.

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

                                Optional: Auto-creation of user records

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

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

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

                                User Experience

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

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

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

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

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

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

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

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

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

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

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

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

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

                                Caveats

                                • SAML Assertion Encryption/Decryption is not currently supported.

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

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

                                Setting

                                Value for Sysdig Monitor

                                Value for Sysdig Secure

                                Single sign on URL

                                https://HOSTNAME:PORT/api/saml/auth

                                https://HOSTNAME:PORT/api/saml/secureAuth

                                Audience URI (SP Entity ID)

                                https://HOSTNAME:PORT/api/saml/metadata

                                https://HOSTNAME:PORT/api/saml/metadata

                                Default RelayState

                                (optional - only configure if you intend to use IDP-initiated login flow)

                                #/&customer=CUSTOMER-ID-NUMBER

                                #/&customer=CUSTOMER-ID-NUMBER

                                You must include the port number in the IDP-side configuration, even though port 443 is the typical default for https:// URLs.

                                Email and Name Values

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

                                NameValue
                                emailuser.email
                                first nameuser.firstName
                                last nameuser.lastName

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

                                Only email is required. However, including first/last name is recommended, since these values will now be included in the records created in the Sysdig 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.

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

                                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.

                                Field

                                Value for Sysdig Monitor

                                Value for Sysdig Secure

                                RelayState

                                (optional - only configure if you intend to use IDP-initiated login flow)

                                #/&customer=CUSTOMER-ID-NUMBER

                                #/&customer=CUSTOMER-ID-NUMBER

                                Recipient

                                https://HOSTNAME:PORT/api/saml/auth

                                https://HOSTNAME:PORT/api/saml/secureAuth

                                ACS (Consumer) URL Validator

                                https://HOSTNAME:PORT

                                https://HOSTNAME:PORT

                                ACS (Consumer) URL

                                https://HOSTNAME:PORT/api/saml/auth

                                https://HOSTNAME:PORT/api/saml/secureAuth

                                You must include the port number in the IDP-side configuration, even though port 443 is the typical default for https:// URLs.

                                (Optional) If you want the user’s First Name and Last Name to be included in the records created in the Sysdig 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.

                                Field NameValue
                                first nameFirst Name
                                last nameLast Name

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

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

                                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.

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

                                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.

                                if you are on Sysdig Platform versions 2.4.1 or prior, contact Sysdig Support to help with user creation.

                                (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>/api/saml/auth

                                    If configuring Sysdig Secure in the US East, enter: https://<hostname>/api/smal/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 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. For example, for Sysdig Monitor in the EU, you use https://eu1.<hostname>.

                                    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

                                    This Results URL will be used in the metadata URL that you paste in the Metadata entry in the SAML connection settings .

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

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

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

                                3 -

                                OpenID Connect (On-Prem)

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

                                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

                                Step

                                Options

                                Notes

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

                                These are the OpenID Providers for which Sysdig has performed detailed interoperability testing and confirmed how to integrate using their standard docs. If your OpenID Provider is not listed (including ones that do not support OpenID Connect Discovery), it may still work with the Sysdig platform. Contact Sysdig Support for help.

                                2. Decide the login flow you want users to experience: 3 options

                                Click OpenID button

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

                                Type/bookmark a URL in browser

                                Replace <HOSTNAME> and <PORT> with that which specific to your deployment.

                                Log in from an IdP interface

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

                                You will need the following:

                                • Your Sysdig customer number and Customer Name.

                                • Redirect URLs:

                                  • https://<hostname>/api/oauth/openid/auth

                                  • https://<hostname>:<port>/api/oauth/openid/secureAuth

                                  Replace <hostname> with the hostname of your deployment.

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

                                Collect metadata URL (or XML) and test it.

                                If you intend to configure IDP-initiated login flow find your Customer Name. Contact Sysdig if you do not know the customer name corresponding to your account.

                                4a. Log in to Sysdig Monitor and configure authentication.

                                4b. Log in to Sysdig Secure and configure authentication.

                                • Log in to Sysdig Monitor Settings (as super admin) and enter the necessary configuration information in the UI. Save and Enable OpenID as your SSO.

                                • Log in to Sysdig Secure Settings (as super admin) and enter the necessary configuration information in the UI. Save and Enable OpenID as your SSO.

                                Administrator Steps

                                Configure IdP

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

                                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.

                                Connection SettingDescription
                                Client IDID provided by your IdP
                                Client SecretSecret provided by your IdP
                                Issuer URLURL provided by your IdP. Example:https://YOUR-ONELOGIN-DOMAIN.onelogin.com/oidc

                                Okta, OneLogin, and Keycloak support metadata auto-discovery, so these settings should be sufficient for those IdPs.

                                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.

                                Connection Setting

                                Description

                                Base Issuer

                                Required. Often the same Issuer URL, but can be different for providers that have a separate general domain and user-specific domain

                                (for example, general domain: https://openid-connect.onelogin.com/oidc, user-specific domain: https://sysdig-phil-dev.onelogin.com/oidc)f

                                Authorization Endpoint

                                Required. Authorization request endpoint

                                Token Endpoint

                                Required. Token exchange endpoint

                                JSON Web Key Set Endpoint

                                Required. Endpoint that contains key credentials for token signature verification

                                Token Auth Method

                                Authentication method.

                                Supported values:

                                client_secret_basic ,

                                client_secret_post . (case insensitive)

                                Select OpenID for SSO

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

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

                                Config DetailOption
                                Issuer URL-u
                                Client ID-i
                                Client Secret-e

                                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": "0oafpykpv7JMS4gMe0h7",
                                      "clientSecret": "ZctTGJMNJmuseEJHJGhvnb0pniZvz9Gf6RStxhHn",
                                      "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": "0oafpykpv7JMS4gMe0h7",
                                      "clientSecret": "ZctTGJMNJmuseEJHJGhvnb0pniZvz9Gf6RStxhHn",
                                      "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.

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

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

                                This article is specific to LDAP support of On-Premises Deployments version 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.

                                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.

                                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.

                                Whichever method is used, it will apply LDAP settings globally, to both Sysdig Monitor and Sysdig Secure.

                                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

                                Setting

                                Required

                                Description

                                server

                                Yes

                                URL of the directory server for the Sysdig platform to query. An example for LDAP over SSL:

                                ldaps://172.16.0.1:636

                                For cleartext LDAP:

                                ldap://176.16.0.1

                                Note that to use LDAPS, you'll also need to use the Replicated console (or equivalent approach in Kubernetes-based installs) to upload a Certificate Authority (CA) PEM-format certificate that the Sysdig platform will use to validate its SSL connection to the server. If you have a host with OpenSSL tools installed that can reach the directory server, you can obtain the certificate by running:

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

                                The command output will typically show the server certificate first and the CA certificate second, both in PEM format. Into a text file, paste the CA certificate portion of the output that looks like:

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

                                Under LDAP CA certificate in the PEM format in the Replicated console, click the "Choose File" button and browse to the file you just created to select and upload it. Note that when you click Save, the Sysdig platform will restart. This is the only setting related to LDAP that requires a platform restart.

                                Note: For environments using self-signed certificates, the openssl command shown above will return only one certificate.

                                managerDn

                                Yes

                                The distinguished name of a user that the Sysdig platform can authenticate as via LDAP in order to perform further queries about the users attempting to login to the Sysdig platform. Example:

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

                                This setting is required, as the Sysdig platform does not support connection to servers via anonymous bind.

                                managerPassword

                                Yes

                                The password for the managerDn.

                                rootDn

                                No

                                The distinguished name for the point in the LDAP tree below which all search queries will begin. Example:

                                dc=example,dc=local

                                referral

                                No

                                Defines whether the Sysdig platform will chase referrals found in LDAP query responses. If not specified, this will be set to "IGNORE" in your configuration and referrals will not be chased. See the section below on Multi-Server Directories for more details on this option.

                                Table_loginFilter

                                Setting

                                Required

                                Description

                                searchBase

                                Yes

                                A relative distinguished name (from the rootDn) below which queries about users should be performed. Example:

                                cn=Users

                                If specified as an empty string (""), the search will be performed across everything below the rootDn, in which case the rootDn setting must be configured.

                                Note that if the rootDn setting was not specified, the searchBase setting must provide a full distinguished name. Example:

                                cn=Users,dc=example,dc=local

                                searchFilter

                                No

                                An LDAP search filter (in RFC2254 format) that the Sysdig platform will use in constructing the query to identify the user record. The marker token {0} represents where the username will appear when LDAP queries are constructed. An example that targets the attribute sAMAccountName in Active Directory:

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

                                While this setting is optional, if not specified, no users will be able to authenticate via LDAP.

                                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)

                                This article is specific to LDAP support of On-Premises Deployments version 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 (see below).

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

                                Setting

                                Required

                                Description

                                server

                                Yes

                                URL of the directory server for the Sysdig platform to query. An example for LDAP over SSL:

                                ldaps://172.16.0.1:636

                                For cleartext LDAP:

                                ldap://176.16.0.1

                                Note that to use LDAPS, you'll also need to use the Replicated console (or equivalent approach in Kubernetes-based installs) to upload a Certificate Authority (CA) PEM-format certificate that the Sysdig platform will use to validate its SSL connection to the server. If you have a host with OpenSSL tools installed that can reach the directory server, you can obtain the certificate by running:

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

                                The command output will typically show the server certificate first and the CA certificate second, both in PEM format. Into a text file, paste the CA certificate portion of the output that looks like:

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

                                Under LDAP CA certificate in the PEM format in the Replicated console, click the "Choose File" button and browse to the file you just created to select and upload it. Note that when you click Save, the Sysdig platform will restart. This is the only setting related to LDAP that requires a platform restart.

                                Note: For environments using self-signed certificates, the openssl command shown above will return only one certificate.

                                managerDn

                                Yes

                                The distinguished name of a user that the Sysdig platform can authenticate as via LDAP in order to perform further queries about the users attempting to login to the Sysdig platform. Example:

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

                                This setting is required, as the Sysdig platform does not support connection to servers via anonymous bind.

                                managerPassword

                                Yes

                                The password for the managerDn.

                                rootDn

                                No

                                The distinguished name for the point in the LDAP tree below which all search queries will begin. Example:

                                dc=example,dc=local

                                referral

                                No

                                Defines whether the Sysdig platform will chase referrals found in LDAP query responses. If not specified, this will be set to "IGNORE" in your configuration and referrals will not be chased. See the section below on Multi-Server Directories for more details on this option.

                                The following settings are in the optional loginFilter section:s

                                Setting

                                Required

                                Description

                                searchBase

                                Yes

                                A relative distinguished name (from the rootDn) below which queries about users should be performed. Example:

                                cn=Users

                                If specified as an empty string (""), the search will be performed across everything below the rootDn, in which case the rootDn setting must be configured.

                                Note that if the rootDn setting was not specified, the searchBase setting must provide a full distinguished name. Example:

                                cn=Users,dc=example,dc=local

                                searchFilter

                                No

                                An LDAP search filter (in RFC2254 format) that the Sysdig platform will use in constructing the query to identify the user record. The marker token {0} represents where the username will appear when LDAP queries are constructed. An example that targets the attribute sAMAccountName in Active Directory:

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

                                While this setting is optional, if not specified, no users will be able to authenticate via LDAP.

                                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.

                                Setting

                                Required

                                Description

                                groupSearchBase

                                No

                                A relative distinguished name (from the rootDn) below which queries about groups should be performed. Example:

                                ou=Planets

                                groupSearchFilter

                                No

                                An LDAP search filter (in RFC2254 format) that the Sysdig platform will use in constructing the query to identify a group to which the user must belong. An example that only permits users that are in the Mars group in Active Directory:

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

                                If this setting is left blank, group membership is not required, and hence any user that successfully authenticates via LDAP using only username/password will be permitted to login to the Sysdig platform.

                                groupMembershipFilter

                                No

                                An LDAP search filter (in RFC2254 format) that the Sysdig platform will use to determine group membership. If no setting is specified, the following default filter is applied, which should work for most environments:

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

                                Download Helper Scripts

                                Scripts and sample files are found in GitHub:

                                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.

                                ldapTeamMapping Parameters

                                Setting

                                Description

                                ldapFilterSettings

                                Specifies which users in the directory would be targets of this mapping rule. Includes two elements:

                                - searchFilter (required): the Sysdig platform will use to identify the users that apply to this mapping rule.

                                - searchBase (optional): the distinguished name for the point in the LDAP tree below which all search queries for this group of users will begin.

                                Example:

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

                                teams

                                A list of names of Sysdig teams.

                                The group of mapped users found via the searchFilter will be made members of all these teams. The named team will be auto-created the first time synchronization is performed for a mapping rule that references it.

                                Example:

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

                                teamRole

                                Defines the Roles that will be assigned to users who are mapped to the Sysdig teams defined in this rule.

                                See options: Integrating Users and Teams via API

                                Example:

                                "teamRole": "ROLE_TEAM_EDIT"

                                usernameAttribute

                                The LDAP attribute containing the username for users that may be auto-created in the Sysdig database as a result of this rule.

                                If LDAP authentication is enabled, shorter non-email-based usernames (such as typically found in the sAMAccountName attribute of Active Directory) may be used.

                                Email-based usernames (such as mail in Active Directory) are also supported.

                                NOTE: If using LDAP/SAML Hybrid Authentication, you should use an email-based attribute for this setting to ensure successful matching against email-based usernames authenticated via SAML.

                                ldapTeamMapping Parameters

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

                                LDAP Sync Process Settings

                                Setting

                                Required

                                Description

                                dryRun

                                No

                                Options: true false

                                If set to true, the configuration will be applied, but any subsequent sync will perform the LDAP query and update the report/log without actually performing the changes.

                                If not specified in the config, dryRun is set to false.

                                The sample mapping configurations set it to true to help you avoid mistakes while getting acquainted with configuring LDAP mappings. A good workflow would be

                                - set dryRun to true when iterating new config changes,

                                - check the sync report to see if it achieves the desired state,

                                - apply the config again with dryRun set to false to trigger the actual changes to users/teams in the Sysdig database during the next sync.

                                maxAllowedMappedUsers

                                No

                                Options: A number 0 - 1000. Default = 100.

                                If specified, any sync that would result in greater than this number of LDAP-mapped users in the Sysdig database will be treated as a dry run. This is to protect against unintended creation of excess user counts as a result of syntax errors in filters. If not specified, will always be set to 100.

                                syncIntervalMinutes

                                No

                                Default value: 10 minutes

                                Set to 0 to disable sync completely

                                Defines how often the Sysdig platform will perform the queries defined in the mapping rules against your directory to ensure all user/team settings in the Sysdig database are current with recent updates to your directory.

                                syncTimeoutSeconds

                                No

                                Default value: 120 seconds

                                The maximum number of seconds to permit each LDAP synchronization operation to run. If the running time of a sync exceeds this amount, the backend log of the Sysdig platform will record an exception and all changes from the attempted sync will be rolled back.

                                teamDefinitions

                                Yes

                                An array that defines additional configurations for each Team referenced in the set of rules in the ldapTeamMapping array.

                                At minimum, this array must reference each Team by name in an element of the array, along with a Scope By setting (set to either "host" or "container") for that Team. Example:

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

                                See table below for full list of options.

                                LDAP Sync Process Settings

                                teamDefinitions Settings

                                Setting

                                Meaning

                                Description

                                id

                                ID of the team

                                A number, automatically generated. User cannot set.

                                name

                                Name of the team

                                Sysdig team name to be used (self-defined)

                                show

                                The scope to be shown

                                Options:

                                "host" or "container"

                                “container” if the team is based on scope of labels from containers, “host” if the team is based on scope of labels from hosts

                                products

                                Sysdig Monitor or Sysdig Secure

                                Options:

                                [“SDC”] for Monitor

                                [“SDS”] for Secure

                                Note that even though this field is an array, you CANNOT assign something like [“SDC”, “SDS”]. If you want to sync both Monitor and Secure teams; you need to set them up separately

                                theme

                                Color of the team

                                Optional, as per https://htmlcolorcodes.com/

                                defaultTeamRole

                                Default role when adding user to the team

                                Available with Sysdig Platform v 3.5.0

                                See options: Integrating Users and Teams via API

                                Example:

                                "defaultTeamRole": "ROLE_TEAM_EDIT"

                                canUseSysdigCapture

                                Team members allowed to take captures

                                Boolean value

                                canUseCustomEvents

                                Team members receive infrastructure events

                                Sysdig Monitor only

                                canUseAwsMetrics

                                Team members can access AWS Cloudwatch metrics

                                Sysdig Monitor only

                                entryPoint

                                Entry point for team members

                                Corresponds to UI element

                                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

                                Option

                                Description

                                no option defined

                                Will print the current configuration

                                -s (with json filename)

                                Apply new settings

                                -f

                                Force a sync

                                -r

                                Report current state

                                -d

                                Delete settings

                                Use with caution!

                                mapping_config.sh Option Summary

                                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.

                                Use with caution! This will trigger the deletion of all mapped teams and removal of mapped users from those teams.

                                # /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:

                                sAMAccountDistinguished Name
                                msmithCN=Mary Smith,CN=Users,DC=example,DC=local
                                mpetersonCN=Mary Peterson,CN=Users,DC=example,DC=local
                                jdoeCN=John Doe,CN=Users,DC=example,DC=local

                                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.

                                For SaaS environments, see Disable Password Authentication (SaaS) .

                                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.