OAuth2 Migration for BC16-18

This guide describes the migration-specific steps for Business Central 16-18.
For the general OAuth 2.0 setup (Azure AD, BC configuration) see the Setup Documentation.

1. Delivery

The OAuth 2.0 changes are located in the branch release/2.3_OAuth2.0.

Step Description Responsibility
1 Clone repository, build app from branch release/2.3_OAuth2.0 Project developer
2 For DMS version > 2.3: Apply OAuth changes via Cherry-Pick Project developer
3 Compile and deploy app in the project Project developer
4 Azure AD + BC setup per Setup Documentation Project developer / Consultant

Note: Support from the DMS product team is only provided against billable effort. Implementation is the responsibility of the project team.


2. Code Changes

This section is relevant for project developers who need to cherry-pick the changes onto higher DMS versions.

2.1 New AL Objects

Object No. Type File Purpose
5306005 Table OAuthApplication.Table.al OAuth app configurations
5306005 Enum OAuthGrantType.Enum.al Auth Code, Client Credentials, Refresh Token
5306001 Enum OAuthApplicationStatus.Enum.al Disconnected, Connected, Error
5306006 Page OAuthApplicationCard.Page.al Card page for OAuth app configuration
5306003 Page OAuthApplications.Page.al List page of all OAuth apps
5306007 Page OAuthConsentDialog.Page.al Browser-based Authorization Code Flow
5306031 Codeunit OAuthImplementation.Codeunit.al Token acquisition, refresh, parsing

2.2 Modified AL Objects

Object File Change
Table 5306002 – CCS DMS Credential Credential.Table.al New field OAuth Application Code (Code[20])
Enum 5306012 – CCS DMS Credential Type CredentialType.Enum.al New value OAuth 2.0
Page 5306002 – CCS DMS Credentials Credentials.Page.al OAuth fields with conditional visibility, action "OAuth Applications"
Codeunit 5306012 – CCS DMS Bearer Container BearerContainer.Codeunit.al New case branch for OAuth 2.0 token acquisition

2.3 Key Code Snippets

New field in Credential table:

field(50; "OAuth Application Code"; Code[20])
{
    Caption = 'OAuth 2.0 Code';
    TableRelation = "CCS DMS OAuth Application";
}

New Credential type:

value(1; "OAuth 2.0")
{
    Caption = 'OAuth 2.0';
}

Token acquisition in Bearer Container:

Credential.Type::"OAuth 2.0":
    GetOAuthAppRequestToken(Credential);

3. Migration Steps

3.1 Azure AD App Registration

Create a Microsoft Entra ID App Registration following this guide:

Important: For BC 16-18, only the Authorization Code Flow is supported. Client Credentials cannot be used with this version.

3.2 BC Setup

Follow the guide: Add OAuth application and DMS credentials

Summary:

  1. Create OAuth Application → Request token → Status Connected
  2. Create Credential with type OAuth 2.0 → Link OAuth Application
  3. Switch Document Libraries to new Credential → Test Connection

3.3 Migrating Existing Document Libraries

  1. Migrate step by step: Switch a test library first
  2. Change Credential Code to the new OAuth credential
  3. Run Test Connection
  4. Functional test: Verify upload, download, metadata
  5. On success: Switch remaining libraries
  6. Delete old ACS credentials after stable operation

4. Troubleshooting

Common Errors

Error Cause Solution
AADSTS50011: Reply URL mismatch Redirect URI incorrect Check in Azure AD: https://businesscentral.dynamics.com/OAuthLanding.htm
AADSTS7000215: Invalid client secret Secret expired/incorrect Generate new secret and update in OAuth Application
AADSTS65001: Not consented Admin Consent missing Azure AD → API Permissions → "Grant admin consent"
Access denied (403) No permission on site Check Delegated Permissions (AllSites.Manage or AllSites.FullControl), grant Admin Consent
Unauthorized (401) Token expired Run "Request Access Token" again
Target Host not found Target Host incorrect Enter domain without https://

Debug Workflow

  1. OAuth Application Card → Status must be Connected
  2. Credential → Type OAuth 2.0, OAuth 2.0 Code filled in
  3. Document Library → Credential Code correctly linked
  4. Azure AD → Permissions present, Admin Consent granted, Secret valid

5. Checklist

  • [ ] App built and deployed from branch release/2.3_OAuth2.0 (cherry-pick if needed)
  • [ ] Azure AD App Registration created – Authorization Code only (Guide)
  • [ ] OAuth Application created in BC, token requested → Status: Connected (Guide)
  • [ ] Credential with type OAuth 2.0 created and linked to OAuth Application
  • [ ] Document Libraries switched over, Test Connection successful
  • [ ] Functional test completed (Upload, Download, Metadata)
  • [ ] Old ACS credentials deactivated (delete after stable operation)
  • [ ] Users informed (Authorization Code: one-time sign-in per session)