OAuth2 Migration for NAV2018

1. Azure AD App Registration

Link to the objects: ccdms-NAV-legacy

1.1 Create App

  1. https://portal.azure.com → Entra ID → App Registrations → New
  2. Name: "NAV DMS SharePoint Integration"
  3. Account type: Single tenant
  4. Certificates & secrets → New client secret (12-24 months)

Important values to note:

  • Client ID: e.g. 1415a3c5-eba6-4a3d-8722-978c8087e3f2
  • Tenant ID: e.g. dacdf289-3262-4ade-8367-123e57b6d515
  • Client Secret: Displayed only once!

1.2 Permissions

  1. API permissions → Add permission → SharePoint
  2. Delegated permissions → AllSites.FullControl ✓
  3. Grant admin consent ✓

1.3 Authentication

Authentication → Advanced settings → Allow public client flows: Yes ✓


2. SharePoint Configuration

Site URL

Format: https://[tenant].sharepoint.com/sites/[sitename]/[locale]/item
Example: https://m365x31509830.sharepoint.com/sites/dms/en-US/item

User Permissions

  • SharePoint: Minimum "Contribute", recommended "Full Control"
  • No MFA (ROPC does not support MFA)

3. NAV Server Setup

3.1 Dependencies

The following DLLs must be placed in the NAV Add-ins folder (C:\Program Files\Microsoft Dynamics NAV\180\Service\Add-ins):

DLL Size Description
CosmoConsult.DMS.SharePoint.Communication.1.0.1.0.dll 245 KB DMS SharePoint Integration with OAuth2 support
Microsoft.Bcl.AsyncInterfaces.dll 28 KB Async/Await Support
Microsoft.Identity.Client.dll 1.8 MB MSAL (Microsoft Authentication Library)
Microsoft.IdentityModel.Abstractions.dll 20 KB Identity Model Abstractions
Microsoft.SharePoint.Client.dll 1.1 MB SharePoint CSOM Client
Microsoft.SharePoint.Client.Runtime.dll 309 KB SharePoint CSOM Runtime
Newtonsoft.Json.dll 712 KB JSON Serialization
System.Buffers.dll 24 KB System Buffers
System.Formats.Asn1.dll 105 KB ASN.1 Encoding/Decoding
System.IO.Pipelines.dll 86 KB I/O Pipelines
System.Memory.dll 145 KB Memory/Span APIs
System.Numerics.Vectors.dll 110 KB Numerics Vectors
System.Runtime.CompilerServices.Unsafe.dll 19 KB Runtime Compiler Services
System.Text.Encodings.Web.dll 88 KB Text Encodings
System.Text.Json.dll 779 KB JSON Serialization (System)
System.Threading.Tasks.Extensions.dll 28 KB Task Extensions

Note: All DLLs must be compatible with .NET Framework 4.6.2 or higher.


4. NAV Code Changes (Overview)

4.1 New Table Fields

TAB5306012 - User Credential:

  • Authentication Type (Option: Standard/OAuth2)
  • OAuth2 Tenant ID, Client ID, Client Secret (encrypted), Scope

TAB5306000 - DMS Setup:

  • Enable Debug Messages (Boolean)

4.2 COD5306003 - SharePoint Management

Key changes:

AppendDocumentLibrary:

  • OAuth2 Credentials block with flowType='delegated'
  • Username/Password BEFORE oauth2 node
  • Three URL formats: webUrl, server, site (Backward Compatibility)

REST API Parsing:

  • SharePointListToTempTable: Child Elements instead of Attributes (<Title> instead of Title="...")
  • XPath without namespace: //List instead of //sharepoint:List
  • GetAdditionalSPListInfo: REST format <Result><List><Title>

Debug Functions:

  • LogDebugXML in all SharePoint operations
  • REQUEST and RESPONSE logging when debug mode is enabled

4.3 Pages

PAG5306000 - DMS Setup: Debug Messages Checkbox
PAG5306019 - User Credential: OAuth2 fields (only visible when Auth Type = OAuth2)


5. NAV Configuration

5.1 DMS Setup

Page 5306000 → Enable Debug Messages (for testing only)

5.2 Server Configuration

Page 5306001 - DMS Server List:

  • Code: e.g. "SPOAUTH"
  • SharePoint URL: https://m365x31509830.sharepoint.com
  • Type: SharePoint Online

5.3 User Credentials

Page 5306019 - User Credential List:

  1. Authentication Type: OAuth2
  2. Username: admin@M365x31509830.onmicrosoft.com
  3. Password: User password (stored encrypted)
  4. OAuth2 Tenant ID: dacdf289-3262-4ade-8367-123e57b6d515
  5. OAuth2 Client ID: 1415a3c5-eba6-4a3d-8722-978c8087e3f2
  6. OAuth2 Client Secret: Secret from Azure AD (stored encrypted)
  7. OAuth2 Scope: https://m365x31509830.sharepoint.com/AllSites.FullControl

5.4 Document Library

Page 5306005 - Document Libraries:

  1. Server Code: SPOAUTH (created previously)
  2. Relative URL: /sites/dms/en-US/item
  3. Actions → Select List Name: Select list from SharePoint (e.g. "Manuals")
  4. Actions → Update Fields: Import SharePoint fields
  5. Actions → Test Connection: Test the connection

6. Troubleshooting

Common Errors

Error Cause Solution
Access denied (0x80070005) Application Permissions Use Delegated Permissions + ROPC
Node 'server' not found Missing URL nodes webUrl, server AND site nodes are required
Could not load Microsoft.IdentityModel.Abstractions DLL missing Place DLL in NAV Add-ins folder + restart NAV Service
List not found Wrong Library Identifier Use Display Name instead of "No."
No execution command found cmd attribute missing Check CreateServiceNode, cmd must be present
Inner Exception: “Error while sending the request” Invalid URL The “Relative URL” field must start with a “/”.
Example:
sites/[site]/dms (WRONG)
/sites/[site]/dms -> (RIGHT)

Debug Workflow

  1. DMS Setup → Enable Debug Messages
  2. Execute operation (e.g. Test Connection)
  3. Check REQUEST XML:
    • Credentials complete?
    • flowType='delegated'?
    • All URL nodes present?
  4. Check RESPONSE XML:
    • <Error> node?
    • REST format (Child Elements)?

Minimal XML for GetList

<services guid="{...}">
  <service cmd="GetList" guid="{...}">
    <webUrl>https://m365x31509830.sharepoint.com/sites/dms/en-US/item</webUrl>
    <server>https://m365x31509830.sharepoint.com</server>
    <site>/sites/dms/en-US/item</site>
    <credentials>
      <username>admin@M365x31509830.onmicrosoft.com</username>
      <password>encrypted_value</password>
      <oauth2>
        <clientId>1415a3c5-eba6-4a3d-8722-978c8087e3f2</clientId>
        <tenantId>dacdf289-3262-4ade-8367-123e57b6d515</tenantId>
        <flowType>delegated</flowType>
        <scope>https://m365x31509830.sharepoint.com/AllSites.FullControl</scope>
        <clientSecret>decrypted_value</clientSecret>
      </oauth2>
    </credentials>
  </service>
</services>

7. Important Notes

SOAP vs. REST API

SOAP (old): Attributes <List Title="..." ID="..." />
REST (new): Child Elements <List><Title>...</Title><ID>...</ID></List>

XML Structure Critical

  • flowType='delegated' is mandatory
  • Username/Password BEFORE oauth2 node
  • Three URL formats for backward compatibility

Security

  • Client Secret is stored encrypted
  • ROPC does not support MFA
  • Admin Consent for SharePoint Permissions is required

8. Checklist

Azure Setup

  • [ ] App Registration created
  • [ ] Client Secret saved
  • [ ] Delegated Permissions (AllSites.FullControl)
  • [ ] Admin Consent granted
  • [ ] Public Client Flow enabled
  • [ ] All required DLLs placed in Add-ins folder
  • [ ] NAV Service restarted
  • [ ] Server Configuration created
  • [ ] User Credentials configured with OAuth2
  • [ ] Document Library set up
  • [ ] Connection Test successful