Skip to main content

Setup Guide

This guide walks you through registering an application in Microsoft Entra ID, granting it Dynamics 365 Finance and Operations API permissions, and adding it as a user in your Dynamics 365 Finance environment to obtain the credentials needed for the Microsoft Dynamics 365 Finance Fiscal connector.

Prerequisites​

  • A Microsoft Dynamics 365 Finance & Operations environment (cloud-hosted, sandbox, or trial), with System administrator access.
  • Access to the Microsoft Entra ID (Azure AD) tenant associated with that environment, with permissions to register applications and grant admin consent.

Step 1: Register an application in Microsoft Entra ID​

  1. Sign in to the Azure portal and navigate to Microsoft Entra ID → App registrations → New registration.
  2. Give the application a name (e.g., d365-fiscal-integration), select the account type appropriate for your organization, and select Register.
  3. On the application's Overview page, note the Application (client) ID and Directory (tenant) ID: both values are required by the connector.
tip

Use a dedicated application registration for each integration so that credentials can be rotated and audited independently of other integrations.

Step 2: Create a client secret​

  1. In the registered application, go to Certificates & secrets → Client secrets → New client secret.
  2. Add a description and choose an expiry period.
  3. Select Add, then immediately copy the secret Value (not the Secret ID).
note

The client secret value is shown only once. If you lose it, you must create a new client secret.

Step 3: Grant Dynamics 365 Finance and Operations API permissions​

  1. In the registered application, go to API permissions → Add a permission → APIs my organization uses.
  2. Search for Dynamics ERP (the Microsoft Dynamics 365 Finance and Operations API) and select it.
  3. Choose Application permissions, select the Dynamics ERP application role required for working with the fiscal calendar and financial dimension framework (.default is not selected here — it is the token-request scope shown in Step 5), and select Add permissions.
  4. Select Grant admin consent for <your tenant> and confirm.
note

Granting admin consent requires Global Administrator or Privileged Role Administrator permissions in the tenant. If you do not have these permissions, ask your tenant administrator to complete this step.

Step 4: Register the application in Dynamics 365 Finance​

  1. Sign in to your Dynamics 365 Finance environment and create a service account: open System administration → Users → New, set a User ID and User name, and assign the security roles required for working with the fiscal calendar and financial dimension framework (for example, General ledger manager or Financial dimension administrator, or a custom role covering the entities you intend to use), then select Save.
  2. Go to System administration → Setup → Microsoft Entra applications and select New. Enter the Application (client) ID from Step 1 as the Client Id, give the entry a descriptive Name, and map it to the User ID you just created. Do not paste the client ID into the user's Identity provider object ID or Azure AD object ID field — that does not establish the required Finance application registration mapping.
tip

Assign only the security roles that the integration actually needs. This limits the entities and operations the application's access token can be used against.

Step 5: Locate your service URL​

The serviceUrl required by the connector is the OData data root of your Dynamics 365 Finance and Operations environment:

https://<your-org>.operations.dynamics.com/data

You can find the base environment URL in the Microsoft Dynamics Lifecycle Services (LCS) portal, or from your browser's address bar when signed in to the environment. Append /data to the base environment URL to form the serviceUrl.

The tokenUrl follows the standard Microsoft Entra ID v2.0 token endpoint format, using the Directory (tenant) ID from Step 1:

https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

The scopes value required by the connector's OAuth2ClientCredentialsGrantConfig is the base environment URL (not the /data-suffixed OData root used for serviceUrl) followed by /.default:

https://<your-org>.operations.dynamics.com/.default
tip

Store the tenant ID, client ID, client secret, service URL, and scopes as configurable values (for example, in a Config.toml file) rather than hard-coding them in source files.

What's next​