Automatically change group membership using scripts

With the help of business rules, scheduled tasks and custom commands, you can automatically add and remove objects from groups. The standard way to do it is to use the Add to group and Remove from group actions.

For details, see Automate group membership management.

However, when the number of groups you need to manage is large, or when the rules for group membership are complex, to automate the process you will need to create a bulky structure of many actions and conditions that is hard to maintain and update. To avoid it, you can create a single action that will add and remove objects from groups using a PowerShell script.

To execute a PowerShell script in a business rule, custom command or scheduled task, add the Run a program or PowerShell script action to it.

 How { #how_to_add_action}

• Launch Adaxes Administration console.

• Select a business rule, custom command or scheduled task.

  

• Click Add new action set.

• Right-click Do nothing and then click Add Action in the context menu.

  

• In the Add Action dialog, select Run a program or PowerShell script.

  

• To open the script editor, click the Edit button.

• If a script is executed in a business rule and its execution can take a long time, it is recommended to run the script asynchronously. To do it, select the Execute asynchronously option.

  

  If the option is selected, the business rule will not wait until the script is finished, and as a result, users will not wait long until the operation completes. Take into account that if an error occurs during asynchronous execution of a script, it will not be displayed in the Execution Log of the operation.

• Click the button to provide a custom description for the action.

To get the properties of the object the script is executed for, you can use value references (e.g. %username%). Before executing the script, Adaxes will replace the value references with corresponding property values of the object.

$department = "%department%"
$title = "%title%"

After replacing value references, the script will look as follows:

$department = "Sales"
$title = "Manager"

Also, to get the object properties you can use a variable called $Context. It is a predefined PowerShell variable of type ExecuteScriptContext.

$department = $Context.TargetObject.Get("department")
$title = $Context.TargetObject.Get("title")

For more details, see Server-side scripting.

Example 1 – Add users with Sales department to the Sales Staff group and users located in OU New York to the New York Office group

Import-Module Adaxes

$userDN = "%distinguishedName%"

# If the department is 'Sales', the user must be a member of the 'Sales Staff' group.
$department = "%department%"
$salesStaffGroup = Get-AdmGroup "Sales Staff"
if ($department -eq "Sales")
{
    # Add the user to the 'Sales Staff' group.
    Add-AdmGroupMember $salesStaffGroup $userDN -ErrorAction SilentlyContinue
}
else
{
    # Remove the user from the 'Sales Staff' group.
    Remove-AdmGroupMember $salesStaffGroup $userDN -Confirm:$false `
        -ErrorAction SilentlyContinue
}

# If the user is located under organizational unit 'New York', add the user to
# the 'New York Office' group.
$newYorkOUDN = "OU=New York,DC=example,DC=com"
$dn = New-Object "Softerra.Adaxes.Ldap.DN" $userDN
$userOUDN = $dn.Parent.ToString()
$newYorkGroup = Get-AdmGroup "New York Office"
if ($newYorkOUDN -eq $userOUDN)
{
    # Add the user to the 'New York Office' group.
    Add-AdmGroupMember $newYorkGroup $userDN -ErrorAction SilentlyContinue
}
else
{
    # Remove the user from the 'New York Office' group.
    Remove-AdmGroupMember $newYorkGroup $userDN -Confirm:$false `
        -ErrorAction SilentlyContinue
}

Example 2 – Remove a user from all groups

Import-Module Adaxes

$user = Get-AdmUser "%distinguishedName%" -Properties MemberOf

if ($user.MemberOf -ne $null)
{
    foreach ($groupDN in $user.MemberOf)
    {
        Remove-AdmGroupMember $groupDN -Members $user -Confirm:$false
    }
}

Example 3 – Remove a user from all mail-enabled groups

Import-Module Adaxes

$username = "%username%"
$domainName = $null

Get-AdmPrincipalGroupMembership $username -Server $domainName -AdaxesService localhost |
Get-AdmGroup -Properties mail -Server $domainName | Where {$_.mail -ne $null} |
Remove-AdmGroupMember -Member $username -Server $domainName -Confirm:$false

See also

• Adaxes SDK
• Adaxes script repository

---