> ## 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.

# App Registration

> Connect Parable to Microsoft 365 via Azure AD App Registration

export const platform_1 = "Microsoft Graph"

export const limit_0 = "10,000 requests per 10 minutes per app; throttling returns 429 with Retry-After header"

export const platform_0 = "Azure"

export const role_0 = undefined

<Tabs>
  <Tab title="Setup">
    <Card title="What You'll Need" icon="key">
      | Credential        | What it is                 |
      | ----------------- | -------------------------- |
      | **Tenant ID**     | Azure AD tenant identifier |
      | **Client ID**     | Application (client) ID    |
      | **Client Secret** | Generated client secret    |
    </Card>

    ## Overview

    Create an Azure AD app registration to connect Parable to Microsoft 365 using OAuth 2.0 client credentials. This enables secure, automated access without user sign-in.

    ## Prerequisites

    <Info>
      **Setup access in {platform_0}.** These steps require **{role_0}**, or a colleague with equivalent permissions who can create credentials for you.

      If that is not you, ask your {platform_0} administrator.
    </Info>

    * **Global Administrator** or **Application Administrator** role in Azure AD
    * Permission to grant admin consent for API permissions

    ## Setup Guide

    <Steps>
      <Step title="Access Azure Portal">
        1. Navigate to <a href="https://portal.azure.com" target="_blank" rel="noopener noreferrer">Azure Portal</a>
        2. Go to **Azure Active Directory** → **App registrations**
        3. Click **New registration**
      </Step>

      <Step title="Register Application">
        | Field                   | Value                                           |
        | ----------------------- | ----------------------------------------------- |
        | Name                    | `Parable Integration`                           |
        | Supported account types | Accounts in this organizational directory only  |
        | Redirect URI            | Leave blank (not needed for client credentials) |

        Click **Register**
      </Step>

      <Step title="Note Application Details">
        From the **Overview** page, copy:

        * **Application (client) ID**
        * **Directory (tenant) ID**
      </Step>

      <Step title="Create Client Secret">
        1. Go to **Certificates & secrets**
        2. Click **New client secret**
        3. Add description: `Parable Integration Secret`
        4. Select expiration (recommend: 24 months)
        5. Click **Add**

        <Warning>
          Copy the secret **Value** immediately — it won't be shown again!
        </Warning>
      </Step>

      <Step title="Configure API Permissions">
        1. Go to **API permissions**
        2. Click **Add a permission** → **Microsoft Graph**
        3. Select **Application permissions**
        4. Add these permissions:

        | Permission           | Purpose                    |
        | -------------------- | -------------------------- |
        | `User.Read.All`      | Read all user profiles     |
        | `Directory.Read.All` | Read directory data        |
        | `AuditLog.Read.All`  | Read audit logs            |
        | `Reports.Read.All`   | Read usage reports         |
        | `Mail.Read`          | Read mail (if needed)      |
        | `Calendars.Read`     | Read calendars (if needed) |
      </Step>

      <Step title="Grant Admin Consent">
        1. Click **Grant admin consent for \[Your Org]**
        2. Confirm the consent dialog

        <Info>
          All permissions should show a green checkmark indicating consent was granted.
        </Info>
      </Step>

      <Step title="Enter values in the form">
        1. **Tenant ID**, **Client ID**, and **Client Secret**: Paste the Directory (tenant) ID, Application (client) ID, and client secret value.
        2. Click **Save & test connection**.
      </Step>
    </Steps>

    <Card title="Need to restrict access?" icon="shield-halved" href="/connectors/microsoft/microsoft-365/app-registration/scoped-access">
      By default, this grants access to all users in your tenant. See **Scoped Access** to limit Parable to specific users or teams.
    </Card>
  </Tab>

  <Tab title="Reference">
    ## Verify Your Setup

    <CodeGroup>
      ```bash Get Access Token theme={null}
      curl -X POST "https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "client_id={CLIENT_ID}" \
        -d "client_secret={CLIENT_SECRET}" \
        -d "scope=https://graph.microsoft.com/.default" \
        -d "grant_type=client_credentials"
      ```

      ```bash Test API Access theme={null}
      curl -H "Authorization: Bearer {ACCESS_TOKEN}" \
        "https://graph.microsoft.com/v1.0/users?\$top=5"
      ```
    </CodeGroup>

    <Check>
      **Success!** If you received a `200 OK` response with valid data, your credentials are configured correctly. You can now proceed to configure this connector in Parable.
    </Check>

    <Tip>
      Enter **Tenant ID**, **Client ID**, and **Client Secret** in the connector form, then click **Save & test connection**.
    </Tip>

    ## Permissions Reference

    | Permission           | Data Accessed                          |
    | -------------------- | -------------------------------------- |
    | `User.Read.All`      | User profiles, managers, photos        |
    | `Directory.Read.All` | Groups, org hierarchy, devices         |
    | `AuditLog.Read.All`  | Sign-in logs, directory audits         |
    | `Reports.Read.All`   | Usage reports (Teams, Email, OneDrive) |
    | `Mail.Read`          | Email metadata and content             |
    | `Calendars.Read`     | Calendar events and availability       |

    <Tip>
      **Rate Limits:** {platform_1} enforces rate limits of **{limit_0}**.

      Parable handles rate limiting automatically with exponential backoff, but initial syncs of large datasets may take longer due to these limits.
    </Tip>

    ## Troubleshooting

    | Error           | Meaning               | Solution                                      |
    | --------------- | --------------------- | --------------------------------------------- |
    | `AADSTS700016`  | App not found         | Verify Client ID and Tenant ID                |
    | `AADSTS7000215` | Invalid client secret | Regenerate client secret                      |
    | `AADSTS65001`   | Consent not granted   | Grant admin consent for permissions           |
    | `403 Forbidden` | Missing permission    | Add required API permission and grant consent |

    <Accordion title="Common Issues">
      ### "Insufficient privileges to complete the operation"

      Ensure admin consent was granted for all required permissions. Check **API permissions** in the app registration.

      ### Token expires quickly

      Access tokens are valid for \~1 hour. Implement proper token refresh using the client credentials flow.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Microsoft Graph API" icon="book" href="https://docs.microsoft.com/en-us/graph/overview">
        Official Graph API documentation
      </Card>

      <Card title="App Registration" icon="key" href="https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app">
        Azure AD app registration guide
      </Card>
    </CardGroup>
  </Tab>
</Tabs>