titledescriptionupdated_date
Microsoft 365 API (Restricted access)How to restrict Microsoft 365 API access to a subset of users of the tenant.2025-10-24T16:45:21Z

See also Microsoft 365 API document.

You can’t restrict a token’s access to a subset of users during its creation. Instead, you grant the token broad permissions and then create a policy on the server side (in Exchange Online) that restricts what that specific application is allowed to access.

The tool for this is called an Application Access Policy.

Here’s the breakdown of how it works and how to set it up.

What we need

  • Client ID
  • Client Secret
  • Tenant ID
  • API Token

The Concept: Application vs. Delegated Permissions

First, it’s crucial to understand the two types of permissions in Microsoft Graph:

  • Delegated Permissions: The application acts on behalf of a signed-in user. The app can only do what the user can do. This isn’t what you want, as your third party won’t have each salesperson sign in.
  • Application Permissions: The application acts on its own, with its own identity (a “service principal”). By default, when you grant application permissions like Mail.Read or Calendars.Read, it applies to all mailboxes in the entire tenant. This is the problem you need to solve.

The solution is to use an Application Access Policy to create a rule that says: “Even though this application could access all mailboxes, I am only allowing it to access mailboxes of users who are members of this specific group (e.g., ‘Sales Team’).”

Step-by-Step Guide to Restrict Access

This process requires using PowerShell, as it cannot be configured through the Azure/Entra ID portal interface.

Step 1: Create a Mail-Enabled Security Group

This group will define which users your third-party application can access.

  1. Go to the Microsoft 365 admin center or Entra ID (Azure AD) portal.
  2. Navigate to Groups -> Active groups.
  3. Click Add a group.
  4. Choose the group type Mail-enabled security. This is important; a regular security group won’t work.
  5. Name it something descriptive, like ThirdParty-Sales-Access-Group.
  6. Add all the salespeople you want the third party to have access to as members of this group.

Step 2: Set Up the App Registration in Entra ID

This is the identity your third-party service will use to get the token.

  1. Go to the Microsoft Entra admin center.
  2. Navigate to Identity -> Applications -> App registrations.
  3. Click New registration.
  4. Give it a name (e.g., “Third-Party Mail Service”) and register it.
  5. Go to API permissions.
    • Click Add a permission -> Microsoft Graph.
    • Select Application permissions.
    • Add the permissions you need, for example: Mail.Read, Calendars.Read, Contacts.Read.
    • Click Grant admin consent for [Your Tenant]. The status for all permissions should turn into a green checkmark. ✅
  6. Go to Certificates & secrets.
    • Create a New client secret.
    • Copy the secret’s Value immediately. You’ll give this, along with the Application (client) ID and Directory (tenant) ID from the app’s Overview page, to the third party.

Step 3: Create the Application Access Policy via PowerShell

This is the core step where you link the app registration to the security group.

  1. Connect to Exchange Online PowerShell. If you’ve never done this, open PowerShell as an administrator and run:

    Install-Module -Name ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-ExchangeOnline -UserPrincipalName your-admin-email@yourdomain.com

  2. Create the Application Access Policy. Use the following command, replacing the placeholder values:

    • AppId: Your App Registration’s Application (client) ID.
    • PolicyScopeGroupId: The email address of the mail-enabled security group you created.
    • Description: A helpful note for your future self.
    New-ApplicationAccessPolicy -AppId "00001111-2222-3333-4444-555566667777" -PolicyScopeGroupId "ThirdParty-Sales-Access-Group@yourdomain.com" -AccessRight RestrictAccess -Description "Restricts the Third-Party Mail Service app to the sales team mailboxes."

    The -AccessRight RestrictAccess is the key part that enforces the limitation.

  3. (Optional but Recommended) Test the Policy. You can verify that the policy is configured correctly using this command. It will tell you if the app has access to a specific user’s mailbox.

    • Test against a user inside the group (should return Granted):
      Test-ApplicationAccessPolicy -Identity sales.user@yourdomain.com -AppId "00001111-2222-3333-4444-555566667777"
    • Test against a user outside the group (should return Denied):
      Test-ApplicationAccessPolicy -Identity other.user@yourdomain.com -AppId "00001111-2222-3333-4444-555566667777"

    It can take up to 30 minutes for the policy to become fully active after you create it.

Useful documentation