Set-AmsComputerAuthorizationRule

SYNOPSIS

Sets the properties of an AMS authorization rule

SYNTAX

None (Default)

Set-AmsComputerAuthorizationRule -Id <String> [-JitGroupName <String>] [-JitMaximumAccessDuration <TimeSpan>]
 [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>] [-LapsAllowExtension] [-Description <String>]
 [-RuleExpiryDate <DateTime>] [-Disable] [-Enable] [-Notes <String>]
 [-UserRequestReasonRequirement <AuditReasonFieldState>] [-NotificationChannelsSuccess <String[]>]
 [-NotificationChannelsFailure <String[]>] [-AutoDcLocator] [-DoNotUseRemoteDcLocator] [-SiteName <String>]
 [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to a Microsoft Entra tenant

Set-AmsComputerAuthorizationRule -Id <String> -AadTenantId <String> [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to a Microsoft Entra group

Set-AmsComputerAuthorizationRule -Id <String> -AadTenantId <String> -AadGroupId <String>
 [-JitGroupName <String>] [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension]
 [-LapsMaximumAccessDuration <TimeSpan>] [-LapsAllowExtension] [-Description <String>]
 [-RuleExpiryDate <DateTime>] [-Disable] [-Enable] [-Notes <String>]
 [-UserRequestReasonRequirement <AuditReasonFieldState>] [-NotificationChannelsSuccess <String[]>]
 [-NotificationChannelsFailure <String[]>] [-AutoDcLocator] [-DoNotUseRemoteDcLocator] [-SiteName <String>]
 [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to a Microsoft Entra computer

Set-AmsComputerAuthorizationRule -Id <String> -AadTenantId <String> -AadComputerId <String>
 [-JitGroupName <String>] [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension]
 [-LapsMaximumAccessDuration <TimeSpan>] [-LapsAllowExtension] [-Description <String>]
 [-RuleExpiryDate <DateTime>] [-Disable] [-Enable] [-Notes <String>]
 [-UserRequestReasonRequirement <AuditReasonFieldState>] [-NotificationChannelsSuccess <String[]>]
 [-NotificationChannelsFailure <String[]>] [-AutoDcLocator] [-DoNotUseRemoteDcLocator] [-SiteName <String>]
 [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to an AD computer

Set-AmsComputerAuthorizationRule -Id <String> -AdComputer <String> [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to an AD group

Set-AmsComputerAuthorizationRule -Id <String> -AdGroup <String> [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to an AD container

Set-AmsComputerAuthorizationRule -Id <String> -AdContainer <String> [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to an AMS computer

Set-AmsComputerAuthorizationRule -Id <String> -AmsComputerId <String> [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Set the rule target to an AMS group

Set-AmsComputerAuthorizationRule -Id <String> -AmsGroupId <String> [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Modify the rule ACL

Set-AmsComputerAuthorizationRule -Id <String> [-AddPrincipalsAllowedJit <Object[]>]
 [-RemovePrincipalsAllowedJit <Object[]>] [-AddPrincipalsDeniedJit <Object[]>]
 [-RemovePrincipalsDeniedJit <Object[]>] [-AddPrincipalsAllowedLaps <Object[]>]
 [-RemovePrincipalsAllowedLaps <Object[]>] [-AddPrincipalsDeniedLaps <Object[]>]
 [-RemovePrincipalsDeniedLaps <Object[]>] [-AddPrincipalsAllowedLapsHistory <Object[]>]
 [-RemovePrincipalsAllowedLapsHistory <Object[]>] [-AddPrincipalsDeniedLapsHistory <Object[]>]
 [-RemovePrincipalsDeniedLapsHistory <Object[]>] [-AddPrincipalsAllowedBitLocker <Object[]>]
 [-RemovePrincipalsAllowedBitLocker <Object[]>] [-AddPrincipalsDeniedBitLocker <Object[]>]
 [-RemovePrincipalsDeniedBitLocker <Object[]>] [-AddPrincipalsAllowedRapidLapsLogin <Object[]>]
 [-RemovePrincipalsAllowedRapidLapsLogin <Object[]>] [-AddPrincipalsDeniedRapidLapsLogin <Object[]>]
 [-RemovePrincipalsDeniedRapidLapsLogin <Object[]>] [-AddPrincipalsAllowedRapidLapsElevation <Object[]>]
 [-RemovePrincipalsAllowedRapidLapsElevation <Object[]>] [-AddPrincipalsDeniedRapidLapsElevation <Object[]>]
 [-RemovePrincipalsDeniedRapidLapsElevation <Object[]>] [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

Modify the rule authorization script

Set-AmsComputerAuthorizationRule -Id <String> [-AuthorizationScriptPath <String>] [-JitGroupName <String>]
 [-JitMaximumAccessDuration <TimeSpan>] [-JitAllowExtension] [-LapsMaximumAccessDuration <TimeSpan>]
 [-LapsAllowExtension] [-Description <String>] [-RuleExpiryDate <DateTime>] [-Disable] [-Enable]
 [-Notes <String>] [-UserRequestReasonRequirement <AuditReasonFieldState>]
 [-NotificationChannelsSuccess <String[]>] [-NotificationChannelsFailure <String[]>] [-AutoDcLocator]
 [-DoNotUseRemoteDcLocator] [-SiteName <String>] [-DomainControllerName <String>] [<CommonParameters>]

DESCRIPTION

This cmdlet allows you to modify the properties of an authorization rule, such as updating the target of the rule, adding and removing authorized users, and configuring LAPS and JIT settings.

EXAMPLES

Example 1

PS C:\> Set-AmsComputerAuthorizationRule -Id '8a2ac32c-3fe8-478f-9550-9e6630d8f07a' -AddPrincipalsAllowedJit 'DOMAIN\user1'

Adds the specified principal to the list of allowed JIT users

Example 2

PS C:\> Set-AmsComputerAuthorizationRule -Id '8a2ac32c-3fe8-478f-9550-9e6630d8f07a' -AuthorizationScriptPath "C:\scripts\authz.ps1"

Updates the rule to use the specified authorization script

Example 3

PS C:\> Set-AmsComputerAuthorizationRule -Id '8a2ac32c-3fe8-478f-9550-9e6630d8f07a' -AdGroup "DOMAIN\AccountingServers"

Targets the rule to the `AccountingServers` AD group

PARAMETERS

-AadComputerId

The object ID of a Microsoft Entra computer

Type: String
Parameter Sets: Set the rule target to a Microsoft Entra computer
Aliases:

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

-AadGroupId

The object ID of a Microsoft Entra group

Type: String
Parameter Sets: Set the rule target to a Microsoft Entra group
Aliases:

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

-AadTenantId

The tenant ID of a registered Microsoft Entra tenant

Type: String
Parameter Sets: Set the rule target to a Microsoft Entra tenant, Set the rule target to a Microsoft Entra group, Set the rule target to a Microsoft Entra computer
Aliases:

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

-AdComputer

The fully qualified name or SID of an Active Directory computer

Type: String
Parameter Sets: Set the rule target to an AD computer
Aliases:

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

-AdContainer

The DN of an Active Directory container object such as an organizational unit

Type: String
Parameter Sets: Set the rule target to an AD container
Aliases:

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

-AdGroup

The fully qualified name or SID of an Active Directory group

Type: String
Parameter Sets: Set the rule target to an AD group
Aliases:

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

-AddPrincipalsAllowedBitLocker

Principals to add to the allow BitLocker access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsAllowedJit

Principals to add to the allow JIT access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsAllowedLaps

Principals to add to the allow LAPS access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsAllowedLapsHistory

Principals to add to the allow LAPS history access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsDeniedBitLocker

Principals to add to the deny BitLocker access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsDeniedJit

Principals to add to the deny JIT access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsDeniedLaps

Principals to add to the deny LAPS access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsDeniedLapsHistory

Principals to add to the deny LAPS history access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AmsComputerId

The object ID of an AMS-registered computer

Type: String
Parameter Sets: Set the rule target to an AMS computer
Aliases:

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

-AmsGroupId

The SID of an AMS group

Type: String
Parameter Sets: Set the rule target to an AMS group
Aliases:

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

-AuthorizationScriptPath

The path to the authorization script to import

Type: String
Parameter Sets: Modify the rule authorization script
Aliases:

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

-Description

A description of the rule

Type: String
Parameter Sets: (All)
Aliases:

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

-Disable

Indicates if the rule should be disabled

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-Enable

Indicates if the rule should be enabled

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-Id

The unique ID of the rule

Type: String
Parameter Sets: (All)
Aliases:

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

-JitAllowExtension

Specifies if the user is allowed to extend their JIT access request before it expires

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-JitGroupName

The name of the group that users will be added to when granted access to this role

Type: String
Parameter Sets: (All)
Aliases:

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

-JitMaximumAccessDuration

The maximum amount of time the user can request access to this computer via JIT

Type: TimeSpan
Parameter Sets: (All)
Aliases:

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

-LapsAllowExtension

Specifies if the user is allowed to extend their LAPS access request before it expires

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-LapsMaximumAccessDuration

The maximum amount of time the user can request access to this computer's LAPS password before it is changed

Type: TimeSpan
Parameter Sets: (All)
Aliases:

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

-Notes

A custom field to store notes

Type: String
Parameter Sets: (All)
Aliases:

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

-NotificationChannelsFailure

A list of channel IDs or names that should be notified when a user is denied access by this rule

Type: String[]
Parameter Sets: (All)
Aliases:

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

-NotificationChannelsSuccess

A list of channel IDs or names that should be notified when a user is granted access by this rule

Type: String[]
Parameter Sets: (All)
Aliases:

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

-RemovePrincipalsAllowedBitLocker

Principals to remove from the allow BitLocker access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsAllowedJit

Principals to remove from the allow JIT access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsAllowedLaps

Principals to remove from the allow LAPS access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsAllowedLapsHistory

Principals to remove from the allow LAPS history access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsDeniedBitLocker

Principals to remove from the deny BitLocker access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsDeniedJit

Principals to remove from the deny JIT access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsDeniedLaps

Principals to remove from the deny LAPS access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsDeniedLapsHistory

Principals to remove from the deny LAPS history access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RuleExpiryDate

A date and time when this rule will expire, expressed in local time

Type: DateTime
Parameter Sets: (All)
Aliases:

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

-UserRequestReasonRequirement

Specifies if the user must provide a reason for the request, if they can optionally provide a reason, or are not prompted at all for a reason

Type: AuditReasonFieldState
Parameter Sets: (All)
Aliases:
Accepted values: Hidden, Optional, Required

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

-AutoDcLocator

Specifies that the AMS service should automatically find a domain controller to perform the JIT operation against

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DomainControllerName

The name of a domain controller to use when performing the JIT operation against

Type: String
Parameter Sets: (All)
Aliases:

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

-DoNotUseRemoteDcLocator

Specifies that the AMS service should not attempt to use the target computer's DCLocator service to find a domain controller to perform the JIT operation against

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-SiteName

The name of the site to use when trying to find a domain controller to perform the JIT operation against

Type: String
Parameter Sets: (All)
Aliases:

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

-AddPrincipalsAllowedRapidLapsElevation

Principals to add to the allow RapidLAPS elevation access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsAllowedRapidLapsLogin

Principals to add to the allow RapidLAPS login access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsDeniedRapidLapsElevation

Principals to add to the deny RapidLAPS elevation access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-AddPrincipalsDeniedRapidLapsLogin

Principals to add to the deny RapidLAPS login access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsAllowedRapidLapsElevation

Principals to remove from the allow RapidLAPS elevation access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsAllowedRapidLapsLogin

Principals to remove from the allow RapidLAPS login access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsDeniedRapidLapsElevation

Principals to remove from the deny RapidLAPS elevation access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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

-RemovePrincipalsDeniedRapidLapsLogin

Principals to remove from the deny RapidLAPS login access list

Type: Object[]
Parameter Sets: Modify the rule ACL
Aliases:

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.