Edit

Share via

Limiting application permissions to specific Exchange Online mailboxes

  • Article

Administrators who want to limit app access to specific mailboxes can create an application access policy by using the New-ApplicationAccessPolicy PowerShell cmdlet. This article covers the basic steps to configure access control. These steps are specific to Exchange Online resources and don't apply to other Microsoft Graph workloads.

Background

Some apps call Microsoft Graph using their own identity and not on behalf of a user. These apps are usually background services or daemon apps that run on a server without the presence of a signed-in user. These apps make use of OAuth 2.0 client credentials grant flow to authenticate and are configured with application permissions, which by default enables such apps to access all mailboxes in an organization on Exchange Online. For example, the Mail.Read application permission allows apps to read mail in all mailboxes without a signed-in user.

Important

By default, apps that have been granted application permissions to the following data sets can access all the mailboxes in the organization:

  • Calendars
  • Contacts
  • Mail
  • Mailbox settings

Administrators can configure application access policy to limit app access to specific mailboxes.

There are scenarios where administrators might want to limit an app to only specific mailboxes and not all Exchange Online mailboxes in the organization. Administrators can identify the set of mailboxes to permit access by putting them in a mail-enabled security group. Administrators can then limit third-party app access to only that set of mailboxes by creating an application access policy for access to that group.

As further described in the Supported permissions and other resources section, application access policy restricts mailbox access for apps that are granted any of the Microsoft Graph or Exchange Web Services permission scopes that the policy supports.

Configure ApplicationAccessPolicy

To configure an application access policy and limit the scope of application permissions:

  1. Connect to Exchange Online PowerShell. For details, see Connect to Exchange Online PowerShell.

  2. Identify the app's client ID and a mail-enabled security group to restrict the app's access to.

  3. Create an application access policy.

    Run the following command, replacing the arguments for AppId, PolicyScopeGroupId, and Description.

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

  4. Test the newly created application access policy.

    Run the following command, replacing the arguments for Identity and AppId.

    Test-ApplicationAccessPolicy -Identity user1@contoso.com -AppId e7e4dbfc-046-4074-9b3b-2ae8f144f59b

    The output of this command indicates whether the app has access to User1's mailbox.

Note

Changes to application access policies can take longer than 1 hour to take effect in Microsoft Graph REST API calls, even when Test-ApplicationAccessPolicy shows positive results.

Supported permissions and other resources

Administrators can use ApplicationAccessPolicy cmdlets to control mailbox access of an app that is granted any of the following Microsoft Graph application permissions or Exchange Web Services permissions.

Microsoft Graph application permissions:

  • Mail.Read
  • Mail.ReadBasic
  • Mail.ReadBasic.All
  • Mail.ReadWrite
  • Mail.Send
  • MailboxSettings.Read
  • MailboxSettings.ReadWrite
  • Calendars.Read
  • Calendars.ReadWrite
  • Contacts.Read
  • Contacts.ReadWrite

Exchange Web Services permission scope: full_access_as_app.

For more information about configuring application access policy, see the PowerShell cmdlet reference for New-ApplicationAccessPolicy.

Handling API errors

You might encounter the following error when an API call is denied access due to a configured application access policy.

{
    "error": {
        "code": "ErrorAccessDenied",
        "message": "Access to OData is disabled.",
        "innerError": {
            "request-id": "2f038156-cf40-403d-8e46-831fe42a8229",
            "date": "2019-05-24T10:16:21"
        }
    }
}

If the Microsoft Graph API calls from your app return this error, work with the Exchange Online administrator for the organization to ensure that your app has permission to access the mailbox resource.

Related content