Articles in this section

See more
Print

AD Users | Enforce License rule (New)

  • Updated
Follow

Rule description

This hybrid rule queries the specified Active Directory scope and for each user that satisfies specific criteria assigns the selected Microsoft 365 license and its' applications and services to the Microsoft 365 account with an identical UserPrincipalName (UPN).

The rule allows assigning/unassigning required Microsoft 365 licenses to the users and updating applications and services in the licenses that are already assigned. Also, assigned licenses can be ignored or unassigned by setting All other licenses to Ignore or Unassign.

Ignore value means that if a user already has assigned options from this plan, these options will be preserved. If a user doesn't have the options from this plan, these options won't be assigned.

Unassign means that the license itself and all its' apps/services will be unassigned.

 

When to use this rule

These are some typical license assignment scenarios, supplied with the recommendations on an optimal configuration for the rule settings.

  1. Assign Microsoft 365 license to newly created user accounts that have not been licensed:

    1. You can configure the rule to assign a license to recently created accounts only. For more information on how to do this, please see the Initialization script setting described below.
    2. Specify Limit AD scope setting value.
    3. Set the Include licensed users to Licenses users only to enforce licenses only to unlicensed users.
    4. Set the Exclude MS 365 disabled users setting to Yes to exclude Microsoft 365 disabled user accounts.
    5. Set the Exclude AD disabled users setting to Yes to exclude disabled Active Directory user accounts.
    6. As usage location is mandatory to assign a license to a Microsoft 365 user account, set the Change UsageLocation only if not set setting to Yes and pick a value for the Usage Location setting. 
    7. For the License options setting, select the licenses to be assigned and configure its apps/services.
  2. Ensure that all users in the scope have specific licenses and apps/services assigned, and other conflicting applications and services are revoked:
    1. Set  Include licensed users to All users.
    2. Set the Exclude MS 365 disabled users setting and Exclude AD disabled users setting to Yes to only include live user accounts.
    3. For the License options setting, select the licenses to be assigned and configure their apps/services. Set Unassign for conflicting licenses. Set Ignore setting for all other licenses.

  3. Add or remove license applications and services in bulk, to all users in the specified scope:

    1. Set Include licensed users to All users.
    2. Set the Exclude MS 365 disabled users setting and Exclude AD disabled users setting to Yes to only include live user accounts.
    3. For the License options setting, select the licenses to be updated and configure their apps/services.
    4. Set Ignore setting for all the other licenses.

Rule configuration:

  1. Query section: limit the query scope and set the query criteria

  2. Action section: specify license options to enforce to Microsoft 365 users

  3. Select Ignore for all the other licenses to exclude them from the rule execution and preserve its current assignment state on users.

 

Query Section

Setting name Description
General Settings  

Limit AD scope to this domain or OU

This setting defines the search query scope.

To improve query performance, limit the scope to specific OU.

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

Query criteria

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

Filter

Microsoft 365 filter

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

Example: Filter by the found object Distinguished Name.

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

Exclude MS365 disabled users

This setting allows to exclude Microsoft 365 disabled users from the rule scope or to include them.

Exclude AD disabled users

This setting allows to exclude AD-disabled users from the rule scope or to include them.

Exclude shared mailboxes

This setting allows to exclude shared mailboxes from the rule scope or to include them.

Include licensed users

This setting allows to include only licensed or unlicensed users or all users.

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

Other Query Settings

  

Properties to display

To display additional Microsoft 365 properties for each object found by the query, add those properties to the list.

System properties

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

Sort by

Sort result objects list.

Maximum number of users

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

Tip: It is possible to change the default value in Microsoft 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.

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 query criteria builder:

 

Action Section

Setting name Description

License options

Select which Microsoft 365 licenses and apps/services should be updated for the users:

  1. Assign - license and its apps and services will be assigned to the users.
  2. Assign (partially) - license and some of its apps and services will be assigned to the users.
  3. Update apps - license should be already assigned to the users and only its' apps and services will be updated. If the license is not assigned its apps and services won't be updated for the users.
  4. Unassign - license and its apps and services will be revoked.
  5. Ignore - license and its apps and services won't be taken into consideration. Those users that have this license and its apps and services assigned would preserve them. Those users that don't have this license and its apps and services assigned would preserve that state.

License's apps and services can be set to Enable, Disable or Ignore.

All other licenses settings mean all other licenses that are not specified in License options. They can be ignored or unassigned.

Change UsageLocation only if not set

Specify whether to keep the current user's usage location or change it to a new one.

Usage Location

Select the usage location.

Important: If Microsoft 365 user accounts don't have a location attribute set, Microsoft 365 license won't be applied to them, and the rule will stop with the error.

If you use Usage Location from AD value for this setting, you must be sure all Active Directory user accounts, that fall under this rule, have the country set.

If the country that is specified for the Active Directory user account is different from the value of the usage location that is specified in this rule then the Country\region setting will be empty when you open Microsoft 365 License web action for the user. That is to info the administrator that Contry\region is different for Active Directory and Microsoft 365 user accounts.

 

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
9.1.0 The rule has been added to the product.

 

Related articles

Comments

0 comments

Please sign in to leave a comment.