Script repository

Assign security role

Updated on: Jan 18, 2026, Views: 3876

Security roles

The following function can be used in PowerShell scripts to assign a security role to a user or group with a certain scope.

Parameters

  • $trusteeSid - the SID of the user or group that you want to assign the security role to.
  • $baseObjectDN - the distinguished name (DN) of the base directory object that defines the scope. For information on how to get the DN, see Get the DN of a directory object.
  • $scopeItemType - the type of the base object. For a list of possible values, see ADM_SCOPEBASEOBJECTTYPE_ENUM.
  • $inheritance - whether all descendants or only immediate children of the base directory object should be included into or excluded from the scope. For a list of values, see ADS_SCOPEENUM.
  • $exclude - Set to $true to exclude and to $false to include the item into the scope.
  • $rolePath - the ADS path of the security role you want to assign.

Sample usage

UpdateRoleAssignments -TrusteeSid "S-1-5-21-573937-2149998-410785" `
                      -BaseObjectDN "OU=Sales,DC=company,DC=com" `
                      -ScopeItemType "ADM_SCOPEBASEOBJECTTYPE_CONTAINER" `
                      -Inheritance "ADS_SCOPE_SUBTREE" `
                      -Exclude $False `
                      -RolePath "Adaxes://adaxesserver.company.com:12345/CN=My Role,CN=Security Roles,CN=Access Control,CN=Configuration Objects,CN=Adaxes Configuration,CN=Adaxes"

Function

function UpdateRoleAssignments
{
    Param(
        $trusteeSid,
        $baseObjectDN,
        $scopeItemType,
        $inheritance,
        $exclude,
        $rolePath
    )

    $role = $Context.BindToObject($rolePath)

    # Get role assignments.
    $assignments = $role.Assignments
    $scopeItems = $NULL

    foreach ($assignment in $assignments)
    {
        # Check whether the trustee is already present.
        if ($assignment.Trustee -ine $trusteeSid)
        {
            continue
        }
        
        # Get the assignment scope for the trustee.
        $scopeItems = $assignment.ActivityScopeItems
        break
    }

    if ($scopeItems -eq $NULL)
    {
        # Trustee is not yet present, add trustee.
        $assignment = $role.Assignments.Create()
        $assignment.Trustee = $trusteeSid
        $assignment.SetInfo()
        $assignments.Add($assignment)
        $scopeItems = $assignment.ActivityScopeItems
    }

    # Get the base object GUID.
    if ([System.String]::IsNullOrEmpty($baseObjectDN))
    {
        # All objects
	$baseObject = $NULL
        $baseObjectGuid = [Guid]::Empty
    }
    else
    {
        $baseObject = $Context.BindToObjectByDN($baseObjectDN)
        $baseObjectGuid = [Guid]$baseObject.Get("objectGuid")
    }

    # Check whether item already present in scope.
    $removeExistingItem = $False
    foreach ($item in $scopeItems)
    {
        $scopeBaseObjectGuid = [Guid]$item.Get("adm-ScopeBaseObjectGuid")

        if ($scopeBaseObjectGuid -ine $baseObjectGuid)
        {
            continue
        }

        if ($item.Type -ne $scopeItemType)
        {
            continue
        }

        if ($item.Inheritance -ne $inheritance)
        {
            continue
        }

        if ($item.Exclude -eq $exclude)
        {
            return
        }
        
        # Remove the item.
        $removeExistingItem = $True
        break
    }
    
    if ($removeExistingItem)
    {
        $scopeItems.Remove($item)
    }

    # Add a new item to the assignment scope.
    $scopeItem = $scopeItems.Create()
    $scopeItem.BaseObject = $baseObject
    $scopeItem.Type = $scopeItemType
    $scopeItem.Inheritance = $inheritance
    $scopeItem.Exclude = $exclude
    $scopeItem.SetInfo()
    
    $scopeItems.Add($scopeItem)
}

Comments 0

You must be signed in to comment.

    Got questions?

    Support Questions & Answers

    We use cookies to improve your experience.
    By your continued use of this site you accept such use.
    For more details please see our privacy policy and cookies policy.