Add‑ADObjectAccessRule

SYNOPSIS

Adds typed access rules to bounded Active Directory object DACLs.

SYNTAX

Add-ADObjectAccessRule [-Server <String>] [-DistinguishedName] <Object[]>
 -AllowedBaseDistinguishedName <String> [-Credential <PSCredential>] -Account <Object[]> -AccessRights <Object>
 [-AccessControlType <AccessControlType>] [-InheritanceType <WindowsActiveDirectoryInheritance>]
 [-ObjectType <String>] [-InheritedObjectType <String>] [-TimeoutSeconds <Int32>] [-ThrottleLimit <Int32>]
 [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Prevalidates identities and a disposable OU boundary, adds idempotent common or object-specific ACEs, and revalidates object GUID before LDAP write.

EXAMPLES

EXAMPLE 1

Add-ADObjectAccessRule -Server dc01.example.test -DistinguishedName $dn -AllowedBaseDistinguishedName $ou -Account $sid -AccessRights ReadProperty -WhatIf

Previews adding an explicit read-property ACE inside the allowed OU.

EXAMPLE 2

Add-ADObjectAccessRule -DistinguishedName $dn -AllowedBaseDistinguishedName $ou -Account $sid -AccessRights 'ReadProperty, WriteProperty' -Confirm:$false -PassThru

Grants read and write property rights through an automatically located writable domain controller and returns the stored ACE.

EXAMPLE 3

Add-ADObjectAccessRule -DistinguishedName $dn -AllowedBaseDistinguishedName $ou -Account 'CONTOSO\Analysts', 'CONTOSO\Auditors' -AccessRights ReadProperty -Confirm:$false

Adds the same read-property ACE for two groups with one LDAP write.

EXAMPLE 4

Add-ADObjectAccessRule -DistinguishedName $ou -AllowedBaseDistinguishedName $ou -Account $sid -AccessRights 'ReadProperty, WriteProperty' -ObjectType 'employeeID' -InheritanceType Descendents -InheritedObjectType 'user' -Confirm:$false

Delegates read and write access to only the employeeID attribute on every descendant user object, without granting any other property.

EXAMPLE 5

Add-ADObjectAccessRule -DistinguishedName $ou -AllowedBaseDistinguishedName $ou -Account 'CONTOSO\HelpDesk' -AccessRights ExtendedRight -ObjectType 'Reset Password' -InheritanceType Descendents -InheritedObjectType 'user' -Confirm:$false

Delegates the Reset Password extended right to the help desk group on every descendant user object, the same scope the Delegation of Control wizard grants.

EXAMPLE 6

Add-ADObjectAccessRule -DistinguishedName $dn -AllowedBaseDistinguishedName $ou -Account 'CONTOSO\Contractors' -AccessRights GenericAll -AccessControlType Deny -Confirm:$false

Adds an explicit deny rule that blocks the contractors group from every right on the object. An inherited allow rule for the same group is not removed by this command, so review Get-ADObjectAccessRule before relying on the deny to be the deciding ACE.

EXAMPLE 7

Get-ADObject -SearchBase $ou -Filter "objectClass -eq 'organizationalUnit'" |
    Select-Object -ExpandProperty DistinguishedName |
    Add-ADObjectAccessRule -AllowedBaseDistinguishedName $ou -Account $sid -AccessRights ReadProperty -ThrottleLimit 4 -Confirm:$false

Grants the same read-property ACE to every organizational unit under the allowed OU, processing up to four targets concurrently.

PARAMETERS

-AccessControlType

Adds an Allow rule by default or an explicit Deny rule.

Type: AccessControlType
Parameter Sets: (All)
Aliases:
Accepted values: Allow, Deny

Required: False
Position: Named
Default value: Allow
Accept pipeline input: False
Accept wildcard characters: False

-AccessRights

Active Directory rights to add.

Type: Object
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Account

One or more account names, SIDs, identity references, or module identities.

Type: Object[]
Parameter Sets: (All)
Aliases: IdentityReference, ID

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-AllowedBaseDistinguishedName

The organizational unit that bounds every permitted mutation.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Credential

An optional credential used only for the direct LDAP bind to Server.

Type: PSCredential
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-DistinguishedName

One or more distinguished names to modify.

Type: Object[]
Parameter Sets: (All)
Aliases: Path

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

-InheritanceType

Controls directory inheritance for the new ACE.

Type: WindowsActiveDirectoryInheritance
Parameter Sets: (All)
Aliases:
Accepted values: None, All, Descendents, SelfAndChildren, Children

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-InheritedObjectType

Optionally scopes inherited application to an object-class GUID or to the schema class name that identifies it.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ObjectType

Optionally scopes the ACE to an object, property, or extended-right GUID, or to the schema class, attribute, property set, validated write, or extended right name that identifies it.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

Returns the stored explicit access rule after persistence.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Server

The explicit DNS name of the final writable domain controller. When it is omitted, one writable domain controller is located in the current computer's domain and pinned for the whole command.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ThrottleLimit

Limits concurrently processed immutable object targets from 1 through 64.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: [Math]::Max(1, [Math]::Min(8, [Environment]::ProcessorCount))
Accept pipeline input: False
Accept wildcard characters: False

-TimeoutSeconds

Sets the LDAP request timeout from 1 through 300 seconds.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 10
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

OUTPUTS

None

WindowsAccessControl.ADObjectAccessRule

NOTES

RELATED LINKS