Articles in this section

See more
Print

Microsoft 365 Users rule

  • Updated
Follow

Rule description

This is a generic rule to query for Microsoft 365 user accounts that satisfy the specified criteria.
You can limit user scope to a specific Azure AD Admin Unit and set the query criteria to return only the required users.

 

When to use this rule

Use this rule to return a specific set of Microsoft 365 users. Other rules may use this rule as a basis to accomplish many typical scenarios. Each of these rules can be configured to query for Microsoft 365 users and then perform some task against those users. Please, search for the "Microsoft 365 users" keyword on the Add Rule wizard to see the list of all available rule templates that query for Microsoft 365 users.

The Microsoft 365 Users rule is useful in these three main scenarios:

  • When you need a list of users in Microsoft 365.
  • When you need to filter Microsoft 365 users from the CSV file.
  • When you need full control over query parameters.

 

Query Section

Setting name Description
General Settings  

Limit scope to this Azure AD Administrative Unit

This setting defines the search query scope.

To improve query performance, limit the scope to a specific Azure Admin Unit.

Important: To test rule configuration, limit the rule scope to an Azure Admin Unit that contains test accounts or objects.

Query criteria

 

Query criteria are sent with the query and may improve query performance.

Tip: For different samples on the criteria builder, see KB20180410-1.

Post-query filter

 

To hide unwanted data based on criteria, not supported by the Microsoft 365 query criteria above, set the filtering conditions here.

Tip: For optimal performance, use the Query criteria above to filter objects whenever possible.

Properties to display

Each object property defined in this setting matches the column that will be displayed in the Cayosoft Web portal for this web query.

To display additional columns, add the required properties to the Properties to display list.

Tip: To add extension attribute 1 that is synchronized from AD you need to use a value like "OnPremisesExtensionAttributes/extensionAttribute1~Extension Attribute 1".

User account properties

  

Account state

Specify account state:

  1. Any
  2. Enabled
  3. Disabled

User type

Specify user type:

  1. Any 
  2. Member
  3. Guest

Account sync status

Specify account sync status:

  1. Any
  2. Synced
  3. Cloud-only

Modern MFA status

Specify modern MFA status:

  1. Any
  2. Configured - a user has at least one authentication method configured. 
  3. Not configured - a user doesn't have any authentication methods configured.
Important: Due to the current nature of the Microsoft API that returns this information, users will be processed one by one by this MFA status post-filter. Expect 10 minutes of processing per every 300 returned users if this filter is enabled. Reduce the number of users by using query criteria to reduce the rule execution time.

Administrator role

Specify administrator role:

  1. Any
  2. Global Administrator
  3. Or select a specific Administrator role from the picker dialog.

Date time properties

  

Minimum account age (hours)

 Specify the minimum account age for the Microsoft 365 user accounts.

Maximum account age (hours)

 Specify the maximum account age for the Microsoft 365 user accounts.

Last Microsoft 365 sign in (days ago) 

Set a minimum number of days past since a user signs in to Microsoft 365. Use 0 to disable this check.

Note: Using this parameter requires an Azure AD Premium P1/P2 license in the tenant.

Last password change (days ago)

 Set a minimum number of days past since a user changed the password.

Last sync time (days ago)

 Set a minimum number of days past the last sync time.

Extension Attributes 

  

Extension attribute1 - Extension attrbute15

If you use Microsoft 365 extension attributes to store additional information for user accounts, you could select these attributes and map them to Other Attributes.

How to add custom attributes to New Object and Object Properties wizards in Web Portal – Cayosoft Help Center.

Mailbox and Licensing filters

  

Mailbox type 

Specify mailbox type:

  1. Do not filter
  2. Any mailbox
  3. No mailbox
  4. User
  5. Shared
  6. Room
  7. Equipment

Include licensed users

Specify which users should be included:

  1. All users
  2. Licensed users only
  3. Unlicensed users only

Filter by licenses

You can filter users by assigned licenses and apps/services:

  1. License filter conditions are split into two groups: filter by licenses and filter by apps/services.
  2. Licenses can be filtered by ALL, ANY, and NOT:
    1. ALL - user must have all listed licenses assigned
    2. ANY - user must have at least one listed license assigned
    3. NOT - user must not have any listed licenses assigned.
  3. Apps/services filter conditions: ENABLED (all specified) and DISABLED (all specified):
    1. ENABLED (all specified) - user must have all listed apps/services
    2. DISABLED (all specified) - user must not have all listed apps/services.

Also, you can add filtering by inheritance of assigned applications and services:

  1. Filter by direct or inherited (GBL) assignments
  2. Filter by direct assignments only
  3. Filter by inherited assignments (GBL).

Organization Properties

  

DisplayName/Email starts with

EmployeeID starts with

Employee type

Job Title 

Division

Cost center

Department

City

State

Country 

Postal code

Usage location

 Specify organization properties for search.

Map to text file

  

Select data source

Specifies the text file to be imported.

The […] button allows the user to browse for the file and the Create/Edit button allows the creation or editing of the existing file in the built-in Data Source editor.

Separator used in file

 Specify the separator that is used in the CSV file.

Data source anchor attribute

 Select a column in the data source that contains the attribute value for identifying and mapping a user.

System anchor attribute

 Specify user anchor attribute.

Other Query Settings

  

System properties

 List of properties required for this rule to be executed correctly.

Sort by

Sort result objects list.

Limit result set

The maximum number of users returned from Microsoft 365 by default is 2000.

Tip: It is possible to change the default value in Microsoft 365 extension settings.

MS Graph query condition (OData)

By default, Query criteria are used. But when the MS Graph query condition is specified, it overrides the Query criteria setting.

See this article for examples: How to use Query Builder dialog for Query Criteria and Filter rule settings – Cayosoft Help Center.

MS Graph advanced queries

Enables consistency level eventually which uses an index that might not be up-to-date with recent changes to the object.

Initialization script

  

Script

Usually, rules use query criteria to limit the query search scope. It improves the performance of the executed rule.

Due to PowerShell limitations, it is not possible to use calculated expressions in query criteria. That is the point where the initialization script can help. You can initialize a global variable in this setting and then use it in query criteria.

Important: To use a variable, declared in the initialization script, in the query scope, it must be global: $global:<variable name>.

Example: Update AD users, created in the last ten days.

  1. Add this initialization script:
{$global:DatePeriod = (Get-Date).AddDays(-10)}
  1. Use $DatePeriod variable in the query criteria builder:

 

 

Output Section

This section defines the output format of this rule.

To get more information about this section, please see the Output section article.

 

Enforce/Schedule section

This section defines the schedule for how often to run the rule.

To get more information about this section, please see the Enforce/Schedule section article.

 

Change History

Version Notes
10.1.0 The rule has been added to the product.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.