Assign Tags via LDAP Filters
Overview
In addition to the manual assignment of Tags, Silverback also offers several options to automate the assignment of tags to specific device parameters or specific groups of people. A classic case of automated tag distribution to specific groups of people or other parameters is based on an Active Directory or other LDAP systems. By using LDAP filters, you have a very granular and powerful way to make specific configurations or applications available to specific roles, people, or simple properties.
As these filters can be very simple or complex, we want to provide you within this guide a basic of understanding of the Auto Population option with the usage of LDAP Filters. The first step is always to have an created Tag with enabling the Auto Population option to define your specific distribution targets. With enabling the Auto Population option, the LDAP Base DN and Filter options will expand and can be used and modified as highlighted in the following chapters.
Requirements
- For on-premise customers, successfully configured the LDAP connection
- For cloud-customers, successfully set up and configured the Cloud Connector and successfully configured the LDAP connection
Create or edit a Tag
- Login to your Silverback Management Console as an Administrator
- Navigate to Tags
- Press New Tags or edit an existing Tag
- For new Tags: Enter a Name, enable at least one Feature and one Device Type and Press Save
Create your LDAP Filter
- Now enable the Auto Population checkbox
- Enter now your LDAP Base DN and note that this marks the highest hierarchy point in your directory for starting any search.
- e.g. DC=imagoverum,DC=com
- Now it is time to enter your LDAP filter and you will find some simple and common filters below:
- Please note at this point that usernames that are displayed as the output within a filter are based on the configured LDAP attribute Username field in the Web Settings. If you have sAMAccountName set as the Username in the Web Settings, and you create a search with the LDAP Filter by the userPrincipalName, then the user will be found by the UPN in your directory and the used username for device enrollments and assigning Tags in Silverback will be the sAMAccountName.
| Target | LDAP Filter | Assignment |
|---|---|---|
| All Users | (userPrincipalName=*) | The Tag will be assigned to all users that are below the configured the LDAP Base DN. You can use Object Classes and Object Categories to narrow down the search, e.g. with (&(objectClass=user)(samaccountname=*)). |
| User Principal Name attribute | (userPrincipalName=maria.miller@imagoverum.com) | The Tag will be assigned to all devices that are enrolled with the username that will be found in the directory for the userPrincipalName maria.miller@imagoverum.com. |
| Any other specific attribute | (sAMAccountName=maria.miller) | The Tag will be assigned to all devices that are enrolled with the username that was found with the sAMAccountName attribute. |
| Users present in a single group | (MemberOf=CN=Marketing, OU=Groups, DC=imagoverum, DC=com) | The Tag will be assigned to all usernames that are members of the Marketing Group. |
| Users present in multiple groups | (&(memberOf=CN=Marketing, OU=Groups,DC=imagoverum, DC=com)(memberOf=CN=Frankfurt,OU=Groups,DC=imagoverum, DC=com)) | The Tag will be assigned to all usernames that are members of the Marketing and the Frankfurt Group. |
- After adding your first LDAP Filter, press the magnifier icon to review the Top 10 Results as it will provide you an indication if the LDAP Filter is working in general
- When you receive an Error, press OK and adjust the syntax and try again. The error message The LDAP server is unavailable may be somewhat confusing in this case, but it is usually due to incorrect syntax.
- Now Press OK to close the Top 10 Results and press Save.
Depending on the size of your organization, please note at this point that you can narrow down the filters with Object Classes and Object Categories that are mentioned in the additional Examples section.
Review Assignment
One step to review the automatic assignment process is to enroll a device with a username that is included in the appropriate LDAP filter. Once the device is enrolled, navigate to Devices, open the Device Overview, and scroll down to the Assigned Tag list. The second option is to simply open the Device Overview of an already enrolled device with a username that is contained in the corresponding LDAP filter and press Refresh. The tag should be automatically assigned and added to the Assigned Tag list when the device is online and checks in.
Please keep in mind that the automatic tag assignment always occurs when the device checks in automatically or when you force check-in with an update. This means that it will take some time for all devices to be checked in and for them to be equipped with the Tag(s).
Operators and Examples
Operators
LDAP filters consist of one or more criteria that can be combined using operators. The operators are always placed in front of the operands (i.e. the criteria). The search criteria must be enclosed in parentheses, and then the entire term must be enclosed in parentheses again. There are 3 logical operators which can be used in LDAP to perform simple and more complex searches:
& - AND – ((This) AND (this))
| - OR – ((This) OR (This))
! – NOT – (Everything that is NOT This)
Combinations
To combine them, you can use the following structure:
- AND Operation: (& (C1) (C2)) or with more criteria: (&(C1) (C2) (C3) (C4))
- OR Operation: (| (C1) (C2)) or with more criteria: (|(C1) (C2) (C3) (C4))
- Nested Operation: (|(& (...C1...) (...C2...))(& (...C3...) (...C4...))) which means: (C1 AND C2) OR (C3 AND C4)
Examples
The following sample filters can be used as a template to start with and then be expanded as needed:
| Operator | Filter | Output |
|---|---|---|
| AND Operator | (&(memberOf=CN=Marketing, OU=Groups,DC=imagoverum, DC=com)(memberOf=CN=Frankfurt,OU=Groups,DC=imagoverum, DC=com)) | This filter returns only usernames that exist in both the Marketing group and the Frankfurt group. |
| (&(memberOf=CN=Marketing, OU=Groups,DC=iamgoverum, DC=com)(memberOf=CN=Frankfurt,OU=Groups,DC=imagoverum, DC=com)(givenName=Maria)) | This filter returns only those usernames that exist in both the Marketing group and the Frankfurt group, and where the givenName is Maria. | |
| OR Operator | (|(memberOf=CN=Marketing, OU=Groups,DC=imagoverum, DC=com)(memberOf=CN=Frankfurt,OU=Groups,DC=imagoverum, DC=com)) | This filter will return all usernames in both groups. |
| (|(cn=andy*)(cn=maria*)(cn=vincent*)) | This filter will return all usernames where the common name starts with "andy", "maria", or "vincent" | |
| NOT Operator | (&(objectclass=user)(memberOf=CN=Marketing,OU=Groups,DC=imagoverum, DC=com)(!(memberOf=CN=Frankfurt,OU=Groups,DC=imagoverum,DC=com))) | This filter will return all usernames from users that are in the Marketing group, but not in the Frankfurt group. |
| (&(objectclass=user)(sAMAccountName=maria.miller)(!(memberOf=CN=Frankfurt,OU=Groups,DC=imagoverum,DC=com))) | This filter will return all usernames from users that have maria.miller as sAMAccountName and are not in the Frankfurt group. |
For more filter examples, please refer to Active Directory: LDAP Syntax Filters on Microsoft TechNet Wiki Archive.
Object Class and Object Category
Use the Object Class and Object Category filter that makes your intent most clear.
| Object Type | Filter | Output |
|---|---|---|
| Object Class | (&(objectClass=user)(memberOf=CN=Marketing, OU=Groups,DC=imagoverum, DC=com)) | The objectClass of a user object is to identify the top, person, organizationalPerson, and user classes. The example filter will limit to the user class to search for user (and computer) objects that exist in the Marketing group. |
| Object Category | (&(objectCategory=person)(objectClass=user)(memberOf=CN=Marketing, OU=Groups,DC=imagoverum, DC=com)) | With the objectCategory person you will filter additionally for the real users that are part of the Marketing group. |
For additional information, please refer to Filter on objectCategory and objectClass on Microsoft TechNet Wiki Archive.
Nested Groups
If your organization has nested security groups within OUs, performing the searches from the above examples will not identify any of the members within the nested security groups. To achieve this, the following Matching rule OID with the value 1.2.840.113556.1.4.1941 must be included to tell the search filter to follow the chain of ancestry objects all the way to the root and find a match.
| Nested Groups | Filter | Output |
|---|---|---|
| Included Security Groups | (&(memberOf:1.2.840.113556.1.4.1941:=CN=Frankfurt,OU=Groups,DC=imagoverum, DC=com)) | With the matching rule OID in front as a special extended match operator that walks the chain of ancestry in objects all the way to the root until it finds a match. This filter will return all usernames that are directly added into the Frankfurt group or through security groups that are added into the Frankfurt group. |
Additional Information
- Use the enabled Attribute Editor in Active Directory Users and Computers to easily locate the distinguished name of a Group to get an easier understanding of the naming structure
- Start with simple filters and review the results before creating a more complex filter
- Created LDAP Filters can be reused within other Tags by pressing the Show All Items icon next to the LDAP Filter box
- You can mix Device Variables and LDAP Filters. When you add as an example, the Device Variable Key OS Version with the Device Variable Value 14.0.0 and with an LDAP Filter, both parameters will be used to assign the Tag. This means that all devices with an operating system 14.0.0 will receive the assignment when the user is at the same time present in the LDAP Filter as an and operation.
- If you have stored local users in your system and at the same time have an LDAP connection, then devices of local users are also included in the assignment via the LDAP filter, as the username is the decisive attribute for the assignment.
- In addition, the Ignore empty results might be an interesting option for you and for additional information, please refer to Tags Guide Part I: Create and Deploy.
- In urgent scenarios, you might speed up the assigning process by changing something in a system tag, such as enabling an unimportant restriction and Push the Tag to devices from the Definition tab. This will force devices to check in as soon as possible, and you can undo the change shortly thereafter.