Mapping LDAP Users to Sysdig Teams

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

How It Works

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

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

Process Overview

1. Configure Basic LDAP.

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

2. Download Helper Scripts.

3. Configure settings_mapping_simple.json.

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

Prerequisites

Configure Basic LDAP

• Have “super” admin credentials available.

  See Find the Super Admin Credentials and API Token.

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

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

Download Helper Scripts

Scripts and sample files are found in GitHub:

• Sample .json to modify: settings_mapping_simple.json

• Helper script: mapping_config.sh

Configure settings_mapping_simple.json

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

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

Structure of settings_mapping_simple.json

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

ldapTeamMapping Parameters

Each of the options in the first table is Required.

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

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

"teamRole": "ROLE_TEAM_EDIT"

ldapTeamMapping Parameters

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

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

LDAP Sync Process Settings

"defaultTeamRole": "ROLE_TEAM_EDIT"

teamDefinitions Settings

Options for Applying mapping_config.sh

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

For example:

mapping_config.sh -s settings_mapping_simple.json

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

mapping_config.sh Option Summary

Print Current Configuration

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

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

Apply New Settings -s

To apply new mapping settings, invoke mapping_config.sh with the -soption 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 -foption, which performs a PUT on the /api/admin/ldap/syncLdapendpoint:

# ./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 -roption, 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 -doption, optionally adding the -f option to force an immediate sync.

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

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

Sample Use Cases

The sample settings_mapping_simple.json illustrates some common use cases.

Consider a minimal Active Directory with the following users:

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

Mapping Users to Teams

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

Search Users

You can search users by both username and email alias attributes in the search option given in the Settings > Users page.

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 name 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 results in the creation of a team that has the same name as a non-mapped team that already exists (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 (for example, 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 the 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 (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 (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]"
]