17.4 Microsoft Entra ID App Registrations & OAuth 2.0 Integration

17.4 Microsoft Entra ID App Registrations & OAuth 2.0 Integration

Security is paramount when integrating external software with enterprise ERP data. In Dynamics 365 Business Central SaaS, Microsoft has completely deprecated and disabled legacy Web Service Access Keys (Basic Authentication). All modern REST API and OData integrations must authenticate using OAuth 2.0 backed by Microsoft Entra ID (formerly Azure Active Directory). For the MB-820 exam, developers must understand the end-to-end integration lifecycle: registering applications in Entra ID, configuring application permissions, establishing service-to-service (S2S) authorization inside Business Central, executing the Client Credentials token grant, and consuming endpoints with JWT bearer tokens.

1. Modern Authentication Architecture: Why OAuth 2.0?

Legacy authentication relied on transmitting usernames and static Web Service Access Keys inside HTTP Authorization: Basic headers. This approach suffered from severe security vulnerabilities: credentials could be intercepted, keys could not be scoped to specific permissions or expiration dates, and multi-factor authentication (MFA) was unsupported.

+-------------------------------------------------------------------------+
|                        EXTERNAL INTEGRATION SERVICE                     |
|                 (Nightly ETL Daemon / E-Commerce Backend)               |
+-----------------------------------┬-------------------------------------+
                                    │ 1. POST /oauth2/v2.0/token
                                    │    (client_id + client_secret)
                                    ▼
+-------------------------------------------------------------------------+
|                    MICROSOFT ENTRA ID (AZURE AD)                        |
|                                                                         |
|   - Authenticates Client ID & Client Secret / Certificate               |
|   - Validates Dynamics 365 Business Central API Permissions             |
|   - Issues Cryptographically Signed JWT Bearer Access Token             |
+-----------------------------------┬-------------------------------------+
                                    │ 2. Returns Access Token
                                    │    (expires_in: 3599s)
                                    ▼
+-------------------------------------------------------------------------+
|                        EXTERNAL INTEGRATION SERVICE                     |
+-----------------------------------┬-------------------------------------+
                                    │ 3. HTTP GET/POST /api/v2.0/...
                                    │    Header: [Authorization: Bearer <JWT>]
                                    ▼
+-------------------------------------------------------------------------+
|                 BUSINESS CENTRAL CLOUD SERVER (NST)                     |
|                                                                         |
|   1. Validate JWT Token Signature & Expiry with Microsoft Entra ID      |
|   2. Lookup Client ID in Microsoft Entra Applications (Page 9860)       |
|   3. Verify Application State is 'Enabled'                              |
|   4. Apply Assigned Permission Sets & User Groups                       |
|   5. Execute Business Central AL Logic & Return Data Payload            |
+-------------------------------------------------------------------------+

OAuth 2.0 Permission Types in Entra ID

1. Delegated Permissions (user_impersonation): Used when an interactive human user logs in (e.g., a single-page web app or mobile app). The application accesses Business Central on behalf of the signed-in user. Effective permissions are the intersection of the user's Business Central permissions and the app's delegated permissions.
2. Application Permissions (API.ReadWrite.All / Automation.ReadWrite.All): Used for non-interactive background daemons, automated batch integrations, and headless middleware. The application authenticates directly as a Service Principal without any user presence. Application permissions require Admin Consent in Microsoft Entra ID.

2. Step-by-Step Microsoft Entra ID App Registration

To enable service-to-service communication, administrators configure an App Registration in the Microsoft Entra admin center (or Azure Portal):

Step 1: Register Application

• Navigate to Microsoft Entra ID > App registrations > New registration.
• Enter a descriptive name (e.g., Contoso eCommerce S2S Connector).
• Select Supported Account Types: Accounts in this organizational directory only (Single tenant).

Step 2: Capture Application Identifiers

Record the generated identifiers from the Overview page:

• Application (client) ID: A GUID uniquely identifying the app (e.g., 11111111-2222-3333-4444-555555555555).
• Directory (tenant) ID: A GUID identifying the Microsoft Entra tenant (e.g., aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee).

Step 3: Create Client Secret or Certificate

• Navigate to Certificates & secrets > Client secrets > New client secret.
• Provide a description, select an expiration period (e.g., 180 days, 365 days), and click Add.
• Important: Copy the client secret Value immediately. Entra ID masks this value permanently after navigating away.
• Production Best Practice: For mission-critical production environments, prefer X.509 Certificates over client secrets to prevent secret expiration outages and credential leakage.

Step 4: Configure API Permissions

• Navigate to API permissions > Add a permission > Select Dynamics 365 Business Central.
• Choose Application permissions (for headless daemons).
• Check API.ReadWrite.All (provides full read/write access to Business Central standard and custom API endpoints).
• Click Grant admin consent for [TenantName] to activate the permissions.

3. Authorizing Service Principals in Business Central (Page 9860)

Registering the app in Microsoft Entra ID alone is not sufficient to access Business Central. Administrators must authorize the application inside Business Central to establish role-based access control (RBAC).

+-------------------------------------------------------------------------+
|            BUSINESS CENTRAL: MICROSOFT ENTRA APPLICATIONS (Page 9860)   |
+-------------------------------------------------------------------------+
|  Client ID:       11111111-2222-3333-4444-555555555555                  |
|  Description:     Contoso eCommerce S2S Connector                       |
|  State:           Enabled                                               |
|  App ID URI:      api://11111111-2222-3333-4444-555555555555            |
+-------------------------------------------------------------------------+
|  ASSIGNED PERMISSION SETS                                               |
|  - D365 BASIC          (Read/Write basic tenant tables)                 |
|  - D365 AUTOMATION     (Execute API operations & Web Services)          |
|  - CONTOSO INTEGRATION (Custom permission set for custom API pages)     |
+-------------------------------------------------------------------------+

Configuration Procedure in Business Central

1. In the Business Central Web Client, search for and open Microsoft Entra Applications (Page 9860).
2. Click New to create a new application record.
3. In the Client ID field, paste the Application (client) ID GUID copied from Entra ID. Business Central contacts Entra ID and automatically populates the Description with the app's display name.
4. In the User Groups or User Permission Sets FastTab, assign the required permission sets (e.g., D365 AUTOMATION, D365 BASIC, or custom extension permission sets).
5. In the General FastTab, change the State field from Disabled to Enabled.

Exam Watchout — License Consumption of Service Principals: Service Principals registered via the Microsoft Entra Applications page do not consume paid named user licenses in Business Central! Microsoft provides dedicated Service-to-Service (S2S) capacity for automated integrations, subject to standard cloud API request rate limits (e.g., 600 requests/minute per client).

4. OAuth 2.0 Client Credentials Grant Token Flow

External applications authenticate non-interactively using the OAuth 2.0 Client Credentials Grant flow by submitting an HTTP POST request to the Microsoft identity platform token endpoint.

1. Token Request Specification

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=11111111-2222-3333-4444-555555555555
&client_secret=YourClientSecretValueHere~Abc123
&scope=https://api.businesscentral.dynamics.com/.default

Key Parameters Explained

• grant_type: Must be set to client_credentials.
• client_id: The Application (client) ID GUID from Entra ID.
• client_secret: The client secret value generated in Entra ID.
• scope: Must be set to https://api.businesscentral.dynamics.com/.default. The /.default suffix instructs Entra ID to include all static Application permissions granted and consented to in the app registration.

2. Token Response Payload

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6..."
}

3. Calling Business Central APIs with the Bearer Token

External clients include the returned access_token in the HTTP Authorization header prefixed with Bearer :

GET https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/custom/integrations/v2.0/companies({companyId})/customCustomers
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6...
Accept: application/json

Common Integration Error Troubleshooting

• HTTP 401 Unauthorized: The access token is expired, invalid, signed by an untrusted tenant, or omitted from the Authorization header.
• HTTP 403 Forbidden: The application authenticated with Entra ID successfully, but inside Business Central, the Client ID is either not registered on Page 9860, its State is Disabled, or it lacks the required Permission Sets to access the requested table or API page.
• HTTP 429 Too Many Requests: The client has exceeded the tenant web service rate limits. The client must inspect the Retry-After response header and implement exponential backoff.