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.
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 organization 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 approximately 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):
- If there are multiple application access policies for the same Application and Target Mailbox pair, DenyAccess policy is prioritized over a RestrictAccess policy.
- 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).
- If there are any RestrictAccess policies that match the Application and Target Mailbox, then the app is granted access.
- 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.
- 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
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 |
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 |
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 |
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 |
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 |
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 |
フィードバック
フィードバックの送信と表示