Certify a group based on the group creation date

Scenario

Set up Cayosoft Administrator to introduce fixed-period certification for AD groups via the AD Groups Certification Review rule. Using a daily scheduled rule, Cayosoft Administrator can automatically create certification tasks for groups based on their creation date (the whenCreated attribute) and a preset interval. Refer to the proposed scenario:

• I need to enforce group certification based on the group creation date in our AD environment. I want Cayosoft Administrator to establish a group certification cadence using fixed x-month-long cycles starting from the group creation date based on the whenCreated attribute. Any new certification tasks for the affected groups must follow the x-month-long cycle even if there were no prior certification events. Additionally, there must be a catch-up window in the event of a technical issue; during the defined window, Cayosoft Administrator must provide an opportunity to certify a group even if the initial certification task creation did not occur on-the-dot.

IMPORTANT    The script is based on the whenCreated attribute. If a group in the scope does not have the attribute, it won't get a certification item even if it fits the specified values.

Supported rules

The scenario applies only to the AD Groups Certification Review rule.

Additional information

The article provides two initialization script options required to fulfill the scenario. Both scripts share the same placeholders. Review the placeholders and replace the values based on your needs:

• Specify a $certIntervalMonths value to limit the list of affected groups based on their creation date. E.g., when set to 6 and the certification campaign runs on October 9th, the campaign will include groups created on October 9th or April 9th of any prior year.

• Specify a $catchUpDays value to define the catch-up window. If Cayosoft Administrator is unable to create a certification task immediately in the event of a technical issue, a certification task will still be created within the catch-up window after the failed attempt. E.g., when set to 3, the rule creates a certification task within 3 days after the failed task creation attempt.

• Specify a $lookBackYears value to define the earliest group creation date. E.g., when set to 30, the rule applies the script to all groups in the OU that were created in the last 30 years from the date of the run.

To implement a script, copy and paste it to the Initialization script section of the rule. Refer to the following sections to learn more about the differences.

Option #1

Use the following script to add the date filter to the existing Query criteria parameters in your rule. When you use this script, no additions to the LDAP filter field are expected; otherwise, the LDAP additions will override the rule settings.

{
$certIntervalMonths = 6 #months
$catchUpDays = 1 #days
$lookBackYears = 30 #year

$curDate = (Get-Date).Date
###
$lookBackMonths = $lookBackYears * 12
$numberOfIntervals = [int]($lookBackMonths/$certIntervalMonths)

$m = $certIntervalMonths
$d = $catchUpDays
$n = $numberOfIntervals

$or = 1..$n | %{
  $i = $_
  $start = $curDate.AddMonths(-($i * $m))
  $end   = $start.AddDays($d)

  $s = $start.ToUniversalTime().ToString('yyyyMMddHHmmss.0Z')
  $e = $end.ToUniversalTime().ToString('yyyyMMddHHmmss.0Z')

  "(whenCreated -ge '$s' -and whenCreated -le '$e')"
} #%

$global:Datefilter = "($($or -join ' -or '))"


if ((-not [string]::IsNullOrWhiteSpace("$FormCMDFilter")) -and ('*' -ne "$FormCMDFilter".Trim()))
{
  $part1 = $FormCMDFilter.ToString().Trim()
  $filterFix = [string]::Format('({0}) -and ({1})', $part1, $Datefilter)
  $global:FormCMDFilter = [Scriptblock]::Create($filterFix)
}
else { $global:FormCMDFilter = [Scriptblock]::Create($Datefilter) }
if ([Cayo.CALog]::IsEnabled) { CayoWriteLog("[Initialization script][1] FormCMDFilter: $FormCMDFilter") }
}

Option #2

Use the following script when you plan to implement additional LDAP filter parameters.

{
$certIntervalMonths = 6 #months
$catchUpDays = 1 #days
$lookBackYears = 30 #year

$curDate = (Get-Date).Date
###
$lookBackMonths = $lookBackYears * 12
$numberOfIntervals = [int]($lookBackMonths/$certIntervalMonths)

$m = $certIntervalMonths
$d = $catchUpDays
$n = $numberOfIntervals

$or = 1..$n | %{
  $i = $_
  $start = $curDate.AddMonths(-($i * $m))
  $end   = $start.AddDays($d)

  $s = $start.ToUniversalTime().ToString('yyyyMMddHHmmss.0Z')
  $e = $end.ToUniversalTime().ToString('yyyyMMddHHmmss.0Z')

  "(&(whenCreated>=$s)(whenCreated<=$e))"
} #%

$DateFilter = "(|$($or -join ''))"

if (-not [string]::IsNullOrWhiteSpace($FormLdapFilter))
{
  $filterFix = [string]::Format("(&({0})({1}))", $DateFilter, $FormLdapFilter)
  $global:FormLdapFilter = $filterFix
}
else { $global:FormLdapFilter = $DateFilter }
if ([Cayo.CALog]::IsEnabled) { CayoWriteLog("[Initialization script][1] FormLdapFilter: $FormLdapFilter") }
}

Steps

RECOMMENDED     Test the rule on a separate OU with a small number of groups to confirm the rule configuration before you apply the workflow to the production OUs.

1. Create a copy of the AD Groups Certification Review rule. In the main console page, navigate to New > Rule > Show all templates > AD Groups Certification Review > Next. Define the rule output, name, description, location, and complete the wizard by clicking Finish.

2. Define a rule scope to limit the target groups using the Limit scope to this domain or OU setting.

3. Define the query criteria by picking the target group type. E.g., in the Query criteria setting, pick the Security option to limit the query to only security groups.

4. Confirm that whenCreated attribute is listed in the Properties to display setting. If omitted on purpose, add it to the the System properties setting.

   IMPORTANT    If you leave out the whenCreated attribute, the rule won't create certification items for groups.

5. Copy and paste the appropriate script in the Initialization script field. Verify that the placeholder values are correct.

6. Set the Certification period setting to ensure one certification item per group per cadence interval; if a certification item exists, no duplicate will be created. To set an interval in months, append m to the number, e.g., 6m for 6 months. The period must be longer than a review can stay open, and shorter than the interval minus the review's expiration.

7. Set up and review the Action items as needed.

8. Run the rule in the test OU. Verify the correct operation and introduce changes, if needed. When ready, switch to production OUs.

9. Set the rule to run daily via the Schedule tab to allow Cayosoft Administrator to create certification items for groups on due days.

Notes

• When referring to months, the initialization script uses a definition of a calendar month, e.g., from June 8th to July 8th, or July 8th to August 8th. When the target month is shorter, the last day of the month is picked; for a group created on February 29th, 2024, Cayosoft Administrator will create a certification task on February 28th, 2025.

• The script evaluates dates and reports groups in UTC.

• The script does not affect the remediation process; use the rule settings to define the process.

• Groups that have a certification item won't get a new item when you run the rule with the script.