Connect Dynamics 365#
Difficulty: heaviest. Dynamics 365 (Dataverse) is the most involved system to connect — not because Forge makes it hard, but because Microsoft's security model requires several distinct pieces to line up: an Entra (Azure AD) app, an Application User inside Dataverse, the right security role, and an alternate key on each table. This guide documents every irreducible step, and calls out exactly where Forge can provision on your behalf so you never touch the Entra portal.
Auth at a glance#
| Method | OAuth 2.0 client-credentials (app-only) |
| What you create | An Entra app registration + a Dataverse Application User + a security role + a table alternate key |
| Where Forge helps | Forge stores the secret, fetches/caches tokens, and does native alternate-key upsert; the irreducible setup is the Microsoft side |
What you'll need#
- An Entra (Azure AD) tenant and a Dataverse environment (
https://yourorg.crm.dynamics.com). - Admin rights in both Entra and the Power Platform admin center.
The pieces, and why each exists#
| Piece | Why it's needed |
|---|---|
| Entra app registration | The identity Forge authenticates as (client id + secret + tenant id). |
| Application User in Dataverse | An Entra app is not automatically a Dataverse user. Dataverse only honors a request from an app that's been added as an Application User in that environment. |
| Security role | The Application User has zero access until a role grants it. Read/write/delete on your tables requires a role with those privileges. |
| Alternate key | Dataverse upsert keys on a column, not your external id, unless the table has an alternate key declared on the column Forge writes the external id into. |
Steps#
1. Register the Entra app#
- Entra admin center → App registrations → New registration. Name it (e.g. "Forgeworks integration"), single-tenant.
- Copy the Application (client) ID and Directory (tenant) ID.
- Certificates & secrets → New client secret. Copy the secret value immediately — it's shown once.
2. Add the app as an Application User in Dataverse#
- Power Platform admin center → your environment → Settings → Users + permissions → Application users → New app user.
- Add the app you just registered (search by the client id).
3. Assign a security role — the step everyone misses#
Warning: An Application User with no role can authenticate but every read
returns 403 prvReadAccount (or similar) and every write fails. This is the
single most common Dynamics setup failure. Assign a role with create / read /
write / delete on your target tables. For a full proof, the
System Administrator role removes all ambiguity.
Assign the role to the Application User from the same screen.
4. Declare an alternate key on each table#
For Forge to upsert by your external id, the target table needs an alternate key on the column that holds it (for example a custom column cr555_forgeexternalid). Power Platform → Tables → (your table) → Keys → New key on that column. Dataverse then accepts PATCH .../entityset(cr555_forgeexternalid='<id>') as a create-or-update — no search race.
5. Connect in Forge#
In Connections → Dynamics 365 → Connect, enter the environment URL (https://yourorg.crm.dynamics.com), the tenant id, client id, and client secret. Forge fetches and caches an app-only token and verifies with a WhoAmI call.
Gotchas#
- Role is the #1 trap (see step 3). If reads return 403 right after a clean connect, the Application User is missing its security role — not a credential problem.
- The client secret is shown once. Copy it at creation; otherwise regenerate.
- Alternate key column must match. The column name in the connection config must be the exact schema name of the alternate-key column.
- Native upsert via alternate key means no search-then-write race — provided the key exists. Without it, upsert can't key on your external id at all.
What Forge should provision for you#
Microsoft requires a human admin for the Entra app, the client secret, and the Application User — those are deliberately gated. But several steps should be automated by Forge so a customer never hand-walks them, and are on the roadmap:
- Alternate-key creation on a target table (Forge knows the column it writes; it can declare the key via the Dataverse metadata API).
- A guided, validated connect flow that runs
WhoAmI, then a probing read, and tells you precisely which piece is missing — "authenticated, but no security role on Account" — instead of a raw403 prvReadAccount. - A role-and-privilege checklist surfaced in the console, so the role step can't be silently skipped.
Note: Dynamics 365 is fully live-verified — both halves — against a real Dataverse environment: WhoAmI → alternate-key upsert → read-back → source capture → delete → confirm-gone. The only friction in that run was step 3 (the Application User needed its System Administrator role) — which is exactly why it's called out so loudly here.