Attribute-based application provisioning with scoping filters
The objective of this article is to explain how to use scoping filters to define attribute-based rules that determine which users are provisioned to an application.
Scoping filter use cases
A scoping filter allows the Azure Active Directory (Azure AD) provisioning service to include or exclude any users who have an attribute that matches a specific value. For example, when provisioning users from Azure AD to a SaaS application used by a sales team, you can specify that only users with a "Department" attribute of "Sales" should be in scope for provisioning.
Scoping filters can be used differently depending on the type of provisioning connector:
Outbound provisioning from Azure AD to SaaS applications. When Azure AD is the source system, user and group assignments are the most common method for determining which users are in scope for provisioning. These assignments also are used for enabling single sign-on and provide a single method to manage access and provisioning. Scoping filters can be used optionally, in addition to assignments or instead of them, to filter users based on attribute values.
The more users and groups in scope for provisioning, the longer the synchronization process can take. Setting the scope to sync assigned users and groups, limiting the number of groups assigned to the app, and limiting the size of the groups will reduce the time it takes to synchronize everyone that is in scope.
Inbound provisioning from HCM applications to Azure AD and Active Directory. When an HCM application such as Workday is the source system, scoping filters are the primary method for determining which users should be provisioned from the HCM application to Active Directory or Azure AD.
By default, Azure AD provisioning connectors do not have any attribute-based scoping filters configured.
Scoping filter construction
A scoping filter consists of one or more clauses. Clauses determine which users are allowed to pass through the scoping filter by evaluating each user's attributes. For example, you might have one clause that requires that a user's "State" attribute equals "New York", so only New York users are provisioned into the application.
A single clause defines a single condition for a single attribute value. If multiple clauses are created in a single scoping filter, they're evaluated together by using "AND" logic. This means all clauses must evaluate to "true" in order for a user to be provisioned.
Finally, multiple scoping filters can be created for a single application. If multiple scoping filters are present, they're evaluated together by using "OR" logic. This means that if all the clauses in any of the configured scoping filters evaluate to "true", the user is provisioned.
Each user or group processed by the Azure AD provisioning service is always evaluated individually against each scoping filter.
As an example, consider the following scoping filter:
According to this scoping filter, users must satisfy the following criteria to be provisioned:
- They must be in New York.
- They must work in the Engineering department.
- Their company employee ID must be between 1,000,000 and 2,000,000.
- Their job title must not be null or empty.
Create scoping filters
Scoping filters are configured as part of the attribute mappings for each Azure AD user provisioning connector. The following procedure assumes that you already set up automatic provisioning for one of the supported applications and are adding a scoping filter to it.
Create a scoping filter
In the Azure portal, go to the Azure Active Directory > Enterprise Applications > All applications section.
Select the application for which you have configured automatic provisioning: for example, "ServiceNow".
Select the Provisioning tab.
In the Mappings section, select the mapping that you want to configure a scoping filter for: for example, "Synchronize Azure Active Directory Users to ServiceNow".
Select the Source object scope menu.
Select Add scoping filter.
Define a clause by selecting a source Attribute Name, an Operator, and an Attribute Value to match against. The following operators are supported:
a. EQUALS. Clause returns "true" if the evaluated attribute matches the input string value exactly (case sensitive).
b. NOT EQUALS. Clause returns "true" if the evaluated attribute doesn't match the input string value (case sensitive).
c. IS TRUE. Clause returns "true" if the evaluated attribute contains a Boolean value of true.
d. IS FALSE. Clause returns "true" if the evaluated attribute contains a Boolean value of false.
e. IS NULL. Clause returns "true" if the evaluated attribute is empty.
f. IS NOT NULL. Clause returns "true" if the evaluated attribute isn't empty.
g. REGEX MATCH. Clause returns "true" if the evaluated attribute matches a regular expression pattern. For example: ([1-9][0-9]) matches any number between 10 and 99 (case sensitive).
h. NOT REGEX MATCH. Clause returns "true" if the evaluated attribute doesn't match a regular expression pattern. It will return "false" if the attribute is null / empty.
i. Greater_Than. Clause returns "true" if the evaluated attribute is greater than the value. The value specified on the scoping filter must be an integer and the attribute on the user must be an integer [0,1,2,...].
j. Greater_Than_OR_EQUALS. Clause returns "true" if the evaluated attribute is greater than or equal to the value. The value specified on the scoping filter must be an integer and the attribute on the user must be an integer [0,1,2,...].
k. Includes. Clause returns "true" if the evaluated attribute contains the string value (case sensitive) as described here.
- The IsMemberOf filter is not supported currently.
- The members attribute on a group is not supported currently.
- Filtering is not supported for multi-valued attributes.
- Scoping filters will return "false" if the value is null / empty.
Optionally, repeat steps 7-8 to add more scoping clauses.
In Scoping Filter Title, add a name for your scoping filter.
Select OK again on the Scoping Filters screen. Optionally, repeat steps 6-11 to add another scoping filter.
Select Save on the Attribute Mapping screen.
Saving a new scoping filter triggers a new full sync for the application, where all users in the source system are evaluated again against the new scoping filter. If a user in the application was previously in scope for provisioning, but falls out of scope, their account is disabled or deprovisioned in the application. To override this default behavior, refer to Skip deletion for user accounts that go out of scope.
Common scoping filters
|userPrincipalName||REGEX MATCHfirstname.lastname@example.org||All users with userPrincipal that has the domain @domain.com will be in scope for provisioning|
|userPrincipalName||NOT REGEX MATCHemail@example.com||All users with userPrincipal that has the domain @domain.com will be out of scope for provisioning|
|department||EQUALS||sales||All users from the sales department are in scope for provisioning|
|workerID||REGEX MATCH||(1[0-9][0-9][0-9][0-9][0-9][0-9])||All employees with workerIDs between 1000000 and 2000000 are in scope for provisioning.|
- Automate user provisioning and deprovisioning to SaaS applications
- Customize attribute mappings for user provisioning
- Write expressions for attribute mappings
- Account provisioning notifications
- Use SCIM to enable automatic provisioning of users and groups from Azure Active Directory to applications
- List of tutorials on how to integrate SaaS apps