Set-SPOTenantRestrictedAppAccessControlList

Module:
Microsoft.Online.SharePoint.PowerShell Module

Adds or removes application IDs in the tenant-wide Application Restrictions deny list in one atomic update.

Syntax

Default (Default) 

Set-SPOTenantRestrictedAppAccessControlList
    [-AddRestrictedAppIds <Guid[]>]
    [-RemoveRestrictedAppIds <Guid[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

Use the Set-SPOTenantRestrictedAppAccessControlList cmdlet to change the tenant-wide deny list for Application Restrictions.

Application Restrictions adds a SharePoint authorization boundary for applications that already have Microsoft Entra consent and SharePoint permissions. It never grants permissions and it doesn't replace Entra consent. A request must pass both the existing permission model and Application Restrictions.

Both parameters are applied in one atomic update that preserves the tenant enforcement switch. At least one of -AddRestrictedAppIds or -RemoveRestrictedAppIds is required, and the same ID can't appear in both parameters. Removals are applied before additions.

You supply application IDs only. You don't identify whether an ID is a regular application or a parent agent blueprint: the backend classifies each added ID and stores it in the appropriate internal list. A parent agent blueprint ID on the tenant deny list blocks the blueprint application itself and every current or future agent app created from that blueprint.

Added IDs are classified by using Microsoft Graph. Microsoft first-party and core applications and IDs that can't be classified are rejected. A bulk add is all-or-none: if any supplied ID is rejected, no IDs are persisted. Removals don't use Microsoft Graph, so stale or deleted application IDs can always be removed.

The combined tenant deny list has a hard maximum of 100 application IDs.

Configuration and enablement are orthogonal: list changes never turn the tenant switch on or off. Use Enable-SPOTenantRestrictedAppAccessControl and Disable-SPOTenantRestrictedAppAccessControl to change enforcement.

Removing the last entry leaves an enabled switch with an empty deny list, which denies nothing. That state is allowed because it's legitimate during cleanup, but the cmdlet warns and points you to Disable-SPOTenantRestrictedAppAccessControl or Clear-SPOTenantRestrictedAppAccessControlPolicy for turning Application Restrictions off explicitly.

The tenant scope is deny-only and has a single list, so there's no mode cmdlet, no -ListType parameter, and no separate clear-list cmdlet.

Tenant Application Restrictions administration is isolated from the general-purpose Get-SPOTenant and Set-SPOTenant cmdlets. Application Restrictions isn't exposed as a Tenant property, so Get-SPOTenant doesn't return the policy and Set-SPOTenant can't change it.

For permissions and the most current information about Windows PowerShell for SharePoint Online, see the online documentation at Intro to SharePoint Online Management Shell.

Examples

Example 1

Set-SPOTenantRestrictedAppAccessControlList -AddRestrictedAppIds 11111111-1111-1111-1111-111111111111

This example adds one application ID to the tenant deny list. The backend classifies the ID and stores it as either a regular application or a parent agent blueprint. The tenant enforcement switch isn't changed.

Example 2

Set-SPOTenantRestrictedAppAccessControlList -AddRestrictedAppIds 11111111-1111-1111-1111-111111111111, 22222222-2222-2222-2222-222222222222 -RemoveRestrictedAppIds 33333333-3333-3333-3333-333333333333

This example adds two application IDs and removes a third in a single atomic update. The removal is applied before the additions. If either added ID is a first-party or core application or can't be classified, the complete operation fails and nothing is persisted.

Example 3

Set-SPOTenantRestrictedAppAccessControlList -RemoveRestrictedAppIds 33333333-3333-3333-3333-333333333333 -Confirm:$false

This example removes an application ID without prompting for confirmation, which is useful in automation. Removals don't call Microsoft Graph, so an ID for a deleted or stale application can still be removed. Suppressing the prompt doesn't bypass validation, authorization, auditing, or first-party protection.

Example 4

Set-SPOTenantRestrictedAppAccessControlList -AddRestrictedAppIds 44444444-4444-4444-4444-444444444444 -WhatIf

This example shows what would happen if the application ID were added, without changing the stored tenant policy.

Parameters

-AddRestrictedAppIds

Applicable: SharePoint Online

Specifies the application IDs to add to the tenant deny list. Each supplied ID is classified by using Microsoft Graph and stored internally as either a regular application or a parent agent blueprint. First-party or core applications and unclassifiable IDs are rejected, and the add is all-or-none.

At least one of -AddRestrictedAppIds or -RemoveRestrictedAppIds is required, and an ID can't appear in both parameters. The combined tenant deny list can't exceed 100 IDs.

Parameter properties

Type:

System.Guid[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Confirm

Applicable: SharePoint Online

Prompts you for confirmation before running the cmdlet. This cmdlet uses ConfirmImpact.High, so it prompts by default. Use -Confirm:$false to suppress the prompt in automation. Suppressing the prompt doesn't bypass validation, authorization, auditing, or first-party protection.

Parameter properties

Type:System.Management.Automation.SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-RemoveRestrictedAppIds

Applicable: SharePoint Online

Specifies the application IDs to remove from the tenant deny list. Removals are applied before additions and don't use Microsoft Graph, so stale or deleted application IDs can always be removed.

At least one of -AddRestrictedAppIds or -RemoveRestrictedAppIds is required, and an ID can't appear in both parameters.

Parameter properties

Type:

System.Guid[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WhatIf

Applicable: SharePoint Online

Shows what would happen if the cmdlet runs. The cmdlet isn't run.

Parameter properties

Type:System.Management.Automation.SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

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

Inputs

None

Outputs

None

This cmdlet doesn't return an output object. Use Get-SPOTenantRestrictedAppAccessControl to read the resulting tenant policy.

Notes

  • Adds and removes are applied as one atomic update. Removals are applied before additions.
  • A bulk add is all-or-none. If any supplied ID is a first-party or core application or can't be classified, no IDs are persisted.
  • The combined tenant deny list has a hard maximum of 100 application IDs.
  • The administrator supplies IDs only. The backend classifies each added ID and stores it as either a regular application or a parent agent blueprint.
  • A parent agent blueprint ID blocks the blueprint application and every current or future agent app created from it.
  • Configuration and enablement are orthogonal: list changes never flip the tenant switch.
  • Removing the last entry leaves an enabled switch with an empty deny list that denies nothing. The cmdlet warns and points to Disable-SPOTenantRestrictedAppAccessControl or Clear-SPOTenantRestrictedAppAccessControlPolicy.
  • Use Set-SPOSiteRestrictedAppAccessControlList to change the lists for an individual site.