This page gives you an overview of a feature that lets you filter users during synchronization. By specifying these groups, you can make sure that only relevant users are synced, depending on their membership in specific groups. Depending on the IdP you can define a server-side and/or a local filter. By setting up server-side filters, you can make the synchronization process more efficient and improve performance, especially when dealing with many users and groups on your IdP.

Server Side Filtering

Server Side Filtering is available for the Azure AD and Okta connectors starting with User Sync 2.10.0 and will be extended to other connectors in future releases.

Server-side filtering allows you to define custom filter expressions specific to the Identity Providers (IdPs) REST API.

Azure AD Server Side Filtering

To define a server filter expression for Azure AD, you can use the Microsoft Graph API's Groups endpoint filter query parameter. This filter expression allows you to search for required groups on Azure AD to narrow down the number of groups before processing them locally. Here are some examples of filter expressions for server-side filtering on Azure AD:

Filter by Group Name Starts With 'jira-'

To filter for groups whose names start with 'jira-', you can use the following filter expression:

startswith(displayName, 'jira-')

This expression will retrieve all groups from Azure AD whose display names start with 'jira-'.

Filter by Group ID

If you want to filter based on a specific group ID, you can use the following filter expression:

id eq 'GROUP-ID'

Replace 'GROUP-ID' with the desired UUID to filter for the group with that ID.

Filter by Group Name Equals 'demogroup'

To filter for a group with the exact name 'demogroup', use the following filter expression:

displayName eq 'demogroup'

Filter with multiple expressions

It is also possible to configure multiple expressions with and/or.  

startswith(displayName, 'jira-') or startswith(displayName, 'confluence-')

Please note that these examples are provided to demonstrate how to construct filter expressions based on different criteria. You can modify them according to your specific requirements and adjust the filter values as needed. For more comprehensive information on constructing filter expressions and utilizing the Groups endpoint in Azure AD, please refer to the Microsoft Graph API documentation.

Okta Server Side Filtering

To define a server filter expression for Okta, you can utilize the Okta API's Groups endpoint search query parameter. This search expression allows you to search for desired groups in Okta to narrow down the number of groups before processing them locally. Here are some examples of this expressions for server-side filtering on Okta:

Filter by Group Name Starts With 'jira-'

To search for groups whose names start with 'jira-', you can use the following filter expression:

profile.name sw "jira-"

This expression will retrieve all groups from Okta whose names start with 'jira-'.

Filter by Group ID

If you want to filter based on a specific group ID, you can use the following filter expression:

id eq "GROUP-ID"

Replace 'GROUP-ID' with the desired UUID to filter for the group with that ID.

Filter by Group Name Equals 'demogroup'

To filter for a group with the exact name 'demogroup', use the following filter expression:

profile.name eq "demogroup"

Filter with multiple expressions

It is also possible to configure multiple expressions using logical operators such as "and" or "or".

profile.name sw "jira-" or profile.name sw "confluence-"

Please note that these examples are provided to demonstrate how to construct search expressions based on different criteria. You can modify them according to your specific requirements and adjust the filter values as needed. For more comprehensive information on constructing filter expressions and utilizing the Groups endpoint in Okta, please refer to the Okta API documentation.

Local Filtering

Local filtering involves filtering the required groups after all groups have been fetched or server-side filtering is applied. This step is performed locally after the relevant group attributes have been fetched from the IdP. Please note that depending on the number of groups, this process may take some time. Users must be members of the specified groups to be synchronized. To configure local filtering, you have two options:

Option 1: Group Name-Based Filtering

1. If you leave the list of groups empty, all users will be synchronized unless filtered in the server-side filter or/and attribute mapping on the provisioning tab.
2. The group names are evaluated before applying any transformations from the attribute mapping, so make sure to use the group names exactly as they appear on the IdP.
3. Click on the edit button to open the edit mode. There you can enter an arbitrary amount of group names. The group name must match to one of the entered expressions to be handled as a required group.
4. Regular expressions can also be used. For example, you can use "jira-.*" to apply the filter to all groups starting with "jira-".

Option 2: Groovy-Based Filtering

1. The "isRequiredGroup()" function is called for every group, and it should return true if the group is a required group.
2. "groupData" contains the available group attributes from the IdP. 
3. You can define custom logic within the "isRequiredGroup()" function to determine the required groups based on your specific requirements.

Preview

The "Preview" feature allows you to test the combined settings from server-side and local filtering. It provides a preview of the result after applying the server-side filtering followed by the local filtering. This allows you to verify the filtering configuration before proceeding with the actual synchronization.

If you have any further questions or require assistance, please reach out to our support team for further guidance.