New-ApplicationAccessPolicy

This cmdlet is available only in the cloud-based service.

Use the New-ApplicationAccessPolicy cmdlet to restrict or deny access to a specific set of mailboxes by an application that uses APIs (Outlook REST, Microsoft Graph, or Exchange Web Services (EWS)). These policies are complementary to the permission scopes that are declared by the application.

Note: We recommend that you use the Exchange Online PowerShell V2 module to connect to Exchange Online PowerShell. For instructions, see Connect to Exchange Online PowerShell.

For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.

Syntax

New-ApplicationAccessPolicy
   -AccessRight <ApplicationAccessPolicyRight>
   -AppId <String[]>
   -PolicyScopeGroupId <RecipientIdParameter>
   [-Confirm]
   [-Description <String>]
   [-WhatIf]
   [<CommonParameters>]

Description

You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.

You can create a limited number of policies in your organization based on a fixed amount of space. If your oganization runs out of space for these policies, you'll see the error: "The total size of App Access Policies exceeded the limit." To maximize the number of policies and reduce the amount of space that's consumed by the policies, set a one space character description for the policy. This method will allow aproximately 300 policies (versus a previous limit of 100 policies).

While scope-based resource access like Mail.Read or Calendar.Read is effective to ensure that the application can only read email or events within a mailbox and not do anything else, application access policies allow admins to enforce limits that are based on a list of mailboxes. For example, apps developed for one country shouldn't have access to data from other countries. Or, or a CRM integration application should only access calendars in the Sales organization and no other departments.

Every API request using the Outlook REST APIs or Microsoft Graph APIs to a target mailbox done by an application is verified using the following rules (in the same order):

  1. If there are multiple application access policies for the same Application and Target Mailbox pair, DenyAccess policy is prioritized over a RestrictAccess policy.
  2. If a DenyAccess policy exists for the Application and Target Mailbox, then the app's access request is denied (even if there exists a RestrictAccess policy).
  3. If there are any RestrictAccess policies that match the Application and Target Mailbox, then the app is granted access.
  4. If there are any Restrict policies for the Application, and the Target Mailbox is not a member of those policies, then application is denied access to the target mailbox.
  5. If none of the above conditions are met, then the application is granted access to the requested target mailbox.

Examples

Example 1

New-ApplicationAccessPolicy -AccessRight DenyAccess -AppId "3dbc2ae1-7198-45ed-9f9f-d86ba3ec35b5", "6ac794ca-2697-4137-8754-d2a78ae47d93" -PolicyScopeGroupId "Engineering Staff" -Description "Engineering Group Policy"

This example creates a new application access policy with the following settings:

  • AccessRight: DenyAccess
  • AppIDs: 3dbc2ae1-7198-45ed-9f9f-d86ba3ec35b5 and 6ac794ca-2697-4137-8754-d2a78ae47d93
  • PolicyScopeGroupId: Engineering Staff
  • Description: Engineering Group Policy

Example 2

New-ApplicationAccessPolicy -AccessRight RestrictAccess -AppId "e7e4dbfc-046f-4074-9b3b-2ae8f144f59b" -PolicyScopeGroupId EvenUsers@AppPolicyTest2.com -Description "Restrict this app's access to members of security group EvenUsers."

This example creates a new application access policy with the following settings:

  • AccessRight: RestrictAccess
  • AppIDs: e7e4dbfc-046f-4074-9b3b-2ae8f144f59b
  • PolicyScopeGroupId: EvenUsers@AppPolicyTest2.com
  • Description: Restrict this app's access to members of security group EvenUsers.

Example 3

New-ApplicationAccessPolicy -AccessRight DenyAccess -AppId "e7e4dbfc-046f-4074-9b3b-2ae8f144f59b" -PolicyScopeGroupId OddUsers@AppPolicyTest2.com -Description "Deny this app access to members of security group OddUsers."

This example creates a new application access policy with the following settings:

  • AccessRight: DenyAccess
  • AppIDs: e7e4dbfc-046f-4074-9b3b-2ae8f144f59b
  • PolicyScopeGroupId: OddUsers@AppPolicyTest2.com
  • Description: Deny this app access to members of security group OddUsers.

Parameters

-AccessRight

The AccessRight parameter specifies the restriction type that you want to assign in the application access policy. Valid values are:

  • RestrictAccess: Allows the associated app to only access data that's associated with mailboxes specified by the PolicyScopeGroupID parameter.
  • DenyAccess: Allows the associated app to only access data that's not associated with mailboxes specified by the PolicyScopeGroupID parameter.
Type:ApplicationAccessPolicyIdParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Online, Exchange Online Protection
-AppId

The Identity parameter specifies the GUID of the apps to include in the policy. To find the GUID value of an app, run the command Get-App | Format-Table -Auto DisplayName,AppId.

You can specify multiple app GUID values separated by commas or you can specify * to indicate all applications.

Type:String[]
Position:Named
Default value:None
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Online, Exchange Online Protection
-Confirm

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

  • Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false.
  • Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.
Type:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Online, Exchange Online Protection
-Description

The Description parameter specifies a description for the policy. If the value contains spaces, enclose the value in quotation marks (").

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Online, Exchange Online Protection
-PolicyScopeGroupID

The PolicyScopeGroupID parameter specifies the recipient to define in the policy. You can use any value that uniquely identifies the recipient. You can also specify a mail enabled security group to restrict/deny access to more than one user mailbox. For example:

  • Name
  • Distinguished name (DN)
  • Display name
  • Email address
  • GUID

This parameter only accepts recipients that are security principals (users or groups that can have permissions assigned to them). The following types of recipients are not security principals, so you can't use them with this parameter:

  • Discovery mailboxes
  • Dynamic distribution groups
  • Distribution groups
  • Shared mailboxes

To verify that a recipient is a security principal, use the syntax Get-Recipient -Identity <RecipientIdentity> | Select-Object IsValidSecurityPrincipal.

If you need to scope the policy to shared mailboxes, you can add them to a mail enabled security group.

Type:RecipientIdParameter
Position:Named
Default value:None
Accept pipeline input:True
Accept wildcard characters:False
Applies to:Exchange Online, Exchange Online Protection
-WhatIf

The WhatIf switch doesn't work on this cmdlet.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
Applies to:Exchange Online, Exchange Online Protection

Inputs

Outputs