> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Scoped Access

> Restrict Microsoft 365 integration to specific users with Application Access Policies

<Tabs>
  <Tab title="Setup">
    <Card title="When to Use This" icon="lock">
      By default, Microsoft Graph application permissions grant access to **all users** in your tenant. Use Application Access Policies to restrict Parable's access to a specific group of users.
    </Card>

    ## Overview

    This guide walks you through restricting your existing Microsoft 365 integration to only access data from a defined subset of users — such as a specific team or department.

    <Info>
      **Prerequisite:** Complete the standard [App Registration setup](/connectors/microsoft/microsoft-365/app-registration/setup) first. This guide adds restrictions to an existing app registration.
    </Info>

    ## The Approach

    You can't limit permissions during token creation. Instead, you:

    1. **Create a mail-enabled security group** containing the users Parable should access
    2. **Apply an Application Access Policy** that restricts your app to only that group

    <Warning>
      Application Access Policies require **PowerShell** — this cannot be configured in the Azure portal.
    </Warning>

    ## Setup Guide

    <Steps>
      <Step title="Create a Mail-Enabled Security Group">
        1. Go to [Microsoft 365 admin center](https://admin.microsoft.com) or [Entra ID portal](https://entra.microsoft.com)
        2. Navigate to **Groups** → **Active groups**
        3. Click **Add a group**
        4. Select **Mail-enabled security** as the group type

        | Field         | Value                                   |
        | ------------- | --------------------------------------- |
        | Name          | `Parable-Access-Group`                  |
        | Description   | Users accessible by Parable integration |
        | Email address | `parable-access@yourdomain.com`         |

        <Warning>
          A regular security group won't work — it **must** be mail-enabled.
        </Warning>

        5. Add the users you want Parable to access as members
      </Step>

      <Step title="Connect to Exchange Online PowerShell">
        Open PowerShell as administrator and run:

        ```powershell theme={null}
        # Install the module (first time only)
        Install-Module -Name ExchangeOnlineManagement

        # Import and connect
        Import-Module ExchangeOnlineManagement
        Connect-ExchangeOnline -UserPrincipalName your-admin@yourdomain.com
        ```
      </Step>

      <Step title="Create the Application Access Policy">
        Run this command, replacing the placeholder values:

        ```powershell theme={null}
        New-ApplicationAccessPolicy `
          -AppId "YOUR_CLIENT_ID" `
          -PolicyScopeGroupId "parable-access@yourdomain.com" `
          -AccessRight RestrictAccess `
          -Description "Restricts Parable to specified user group"
        ```

        | Parameter             | Value                                      |
        | --------------------- | ------------------------------------------ |
        | `-AppId`              | Your app's **Client ID** from Azure        |
        | `-PolicyScopeGroupId` | Email address of your security group       |
        | `-AccessRight`        | `RestrictAccess` (enforces the limitation) |

        <Info>
          The policy can take up to **30 minutes** to become fully active.
        </Info>
      </Step>

      <Step title="Verify the Policy">
        Test access for users inside and outside the group:

        ```powershell theme={null}
        # Should return "Granted"
        Test-ApplicationAccessPolicy `
          -Identity included.user@yourdomain.com `
          -AppId "YOUR_CLIENT_ID"

        # Should return "Denied"
        Test-ApplicationAccessPolicy `
          -Identity excluded.user@yourdomain.com `
          -AppId "YOUR_CLIENT_ID"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## Managing the Policy

    ### View Existing Policies

    ```powershell theme={null}
    Get-ApplicationAccessPolicy | Format-List
    ```

    ### Remove a Policy

    ```powershell theme={null}
    Remove-ApplicationAccessPolicy -Identity "PolicyIdentity"
    ```

    ### Update Group Membership

    Simply add or remove users from your mail-enabled security group. Changes propagate automatically — no policy update needed.

    ## Understanding Permission Types

    | Type            | Description                        | Scoping                                           |
    | --------------- | ---------------------------------- | ------------------------------------------------- |
    | **Delegated**   | Acts on behalf of a signed-in user | Inherently scoped to that user                    |
    | **Application** | Acts with its own identity         | Tenant-wide by default — use policies to restrict |

    Application Access Policies only affect **Application permissions**. They tell Microsoft: "Even though this app *could* access all mailboxes, only allow access to members of this group."

    ## Troubleshooting

    | Issue                           | Solution                                 |
    | ------------------------------- | ---------------------------------------- |
    | Policy not taking effect        | Wait up to 30 minutes for propagation    |
    | Test returns unexpected result  | Verify user is in the correct group      |
    | Can't create mail-enabled group | Ensure you have Exchange Online licenses |
    | PowerShell connection fails     | Verify admin credentials and MFA         |

    <Accordion title="Common Scenarios">
      ### Restricting to multiple teams

      Add users from multiple teams to a single mail-enabled security group, or create multiple groups and apply separate policies.

      ### Excluding specific users

      Application Access Policies work as allowlists, not blocklists. Create a group containing only the users you want to include.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Application Access Policies" icon="book" href="https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access">
        Microsoft's official scoping documentation
      </Card>

      <Card title="New-ApplicationAccessPolicy" icon="terminal" href="https://learn.microsoft.com/en-us/powershell/module/exchange/new-applicationaccesspolicy">
        PowerShell cmdlet reference
      </Card>
    </CardGroup>
  </Tab>
</Tabs>