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:

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.

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

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