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

# Azure & Dynamics Setup

> Register an Azure AD app and wire it to a Dynamics 365 Application User so OpenCX can create incidents and live work items.

Before you paste anything into OpenCX, you need four values from Azure AD and Dynamics 365: **tenant ID**, **application (client) ID**, **client secret**, and your **environment URL**. You also need an <Tooltip tip="A Dataverse user that represents a non-interactive app, not a human. OpenCX authenticates as this user when calling the Dynamics Web API.">Application User</Tooltip> in Dynamics mapped to the Azure AD app and carrying a security role. Work through the steps below in order — the last step (Application User) only works after the Azure AD app exists.

## Before you start

<AccordionGroup>
  <Accordion title="Dynamics 365 with Customer Service or Omnichannel enabled" icon="check">
    OpenCX writes `incident` records, and for chat channels creates `oc_liveworkitem` records in **Omnichannel for Customer Service**. If you only plan to use phone/email handoffs, Customer Service Enterprise is enough. For web/SMS/WhatsApp handoffs, make sure Omnichannel is provisioned on the environment.
  </Accordion>

  <Accordion title="Global admin or Privileged Role Administrator in Azure AD" icon="user-shield">
    You'll register an app, create a client secret, and grant admin consent on API permissions. Any of those three steps needs tenant-level admin rights.
  </Accordion>

  <Accordion title="Power Platform admin on the target Dynamics environment" icon="user-gear">
    You'll create an Application User and assign a security role inside the Dynamics environment. Environment Admin or System Administrator on the env is enough.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Register an app in Azure AD">
    Open the [Azure Portal → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and click **New registration**.

    | Field                   | Value                                                               |
    | ----------------------- | ------------------------------------------------------------------- |
    | Name                    | `OpenCX Dynamics Integration` (or any name you'll recognize)        |
    | Supported account types | **Accounts in this organizational directory only** (single tenant)  |
    | Redirect URI            | Leave blank — OpenCX uses client credentials, not interactive OAuth |

    After it's created, copy the **Directory (tenant) ID** and **Application (client) ID** from the **Overview** page.
  </Step>

  <Step title="Create a client secret">
    In the new app, go to **Certificates & secrets → Client secrets → New client secret**. Name it `opencx` and pick an expiry (24 months is the longest Azure allows).

    <Warning>
      Copy the **Value** (not the Secret ID) immediately. Azure shows it once; after you leave the page it's hidden forever and you'll need to make a new secret.
    </Warning>
  </Step>

  <Step title="Grant Dynamics API permissions">
    Go to **API permissions → Add a permission → Dynamics CRM → Delegated permissions → `user_impersonation`**. Add it, then click **Grant admin consent for `<your tenant>`**. The status column should flip to **Granted**.
  </Step>

  <Step title="Create an Application User in Dynamics">
    Open the [Power Platform admin center](https://admin.powerplatform.microsoft.com/environments) → your environment → **Settings → Users + permissions → Application users → New app user**.

    | Field         | Value                                                                   |
    | ------------- | ----------------------------------------------------------------------- |
    | App           | Pick the Azure AD app you just registered (search by name or client ID) |
    | Business unit | The root business unit of the environment                               |

    Save. The Application User row now represents OpenCX inside Dynamics.
  </Step>

  <Step title="Assign a security role">
    Still on the Application User you just created, click **Manage roles** and attach a role. Two common choices:

    * **System Administrator** — simplest path; grants everything OpenCX needs and more.
    * **Custom role** — minimum privileges: `Read` on `Contact`, `Queue`, `SystemUser`; `Create` + `Write` + `Append To` on `Incident` and `Annotation`; `Create` on `Omnichannel Live Work Item` if you're using chat channels.

    Without a role, every Dynamics API call OpenCX makes returns **401 Unauthorized** even though the token exchange succeeds.
  </Step>

  <Step title="Copy your environment URL">
    Open Dynamics 365 in your browser and copy the URL up to `.dynamics.com` (example: `https://yourorg.crm.dynamics.com`). No trailing slash, no path.

    You'll use this exact string as the `scope` prefix during OAuth — a typo here will break credential verification in OpenCX.
  </Step>
</Steps>

## What you should have at the end

* **Tenant ID** (GUID from the app's **Overview** page)
* **Application (client) ID** (GUID from the same page)
* **Client secret value** (the one Azure showed once)
* **Environment URL** (e.g. `https://yourorg.crm.dynamics.com`)
* **Application User** inside Dynamics, mapped to the Azure AD app, carrying a security role

Take those four values to [Connect to OpenCX](/integrations/dynamics-365/connect) to finish wiring up the integration.

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect to OpenCX" icon="plug" href="/integrations/dynamics-365/connect">
    Paste credentials into the OpenCX dashboard and run Test & Save.
  </Card>

  <Card title="Conversations in Dynamics 365" icon="diagram-project" href="/integrations/dynamics-365/conversations">
    Routing, incident contents, contact dedupe, and observability.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/integrations/dynamics-365/troubleshooting">
    Token 200 but verify fails, 403 on incident create, missing roles.
  </Card>

  <Card title="Dynamics 365 overview" icon="building" href="/integrations/dynamics-365/overview">
    What the integration unlocks across every channel.
  </Card>
</CardGroup>