OAuth Authentication

OAuth Authentication uses the OAuth 2.0 Device Code Flow to provide interactive browser-based authentication for cloud Business Central. This method is ideal when you are running BCCL manually and want to authenticate with your own Microsoft 365 identity. This page explains how the device code flow works, how to use it, and how BCCL manages token caching.

How the Device Code Flow Works

The Device Code Flow is designed for devices and applications that cannot open a browser themselves (like a command-line tool). Instead of redirecting you to a login page directly, BCCL displays a code that you enter in your browser. Here is the step-by-step process:

BCCL requests a device code from Microsoft's OAuth endpoint (https://login.microsoftonline.com/.../oauth2/v2.0/devicecode)
BCCL displays a message containing a URL and a one-time code, for example:

   To sign in, use a web browser to open the page https://microsoft.com/devicelogin
   and enter the code ABCD1234 to authenticate.

You open the URL in any browser on any device (it does not have to be the same machine)
You enter the code and sign in with your Microsoft 365 credentials
BCCL detects the successful login and receives an access token
The access token is cached in isolated storage for reuse

BCCL polls Microsoft's token endpoint every 5 seconds while waiting for you to complete the browser login. If you do not complete the login within approximately 8 minutes (100 polling attempts), the request times out.

Parameters

OAuth Authentication uses the following command-line parameters:

Parameter	Long Form	Required	Description
Auth method	`--auth`	Yes	Must be `OAuth`
Client ID	`--clientid`	No	Azure AD Application ID (uses built-in BCCL app if omitted)
Tenant ID	`--tenantid`	No	Azure AD Tenant ID (for cross-tenant partner access)
Web Service URL	`-w` / `--wsurl`	Yes	The BCCL codeunit web service URL

About the Client ID

BCCL includes a built-in Azure AD application registration for the device code flow. If you do not specify --clientid, BCCL uses its own registered application. This works for most scenarios.

You only need to specify a custom --clientid if your organization requires all application access to go through a company-managed App Registration, or if you need specific API permissions beyond the default.

About the Tenant ID

The --tenantid parameter is optional for standard OAuth authentication. When omitted, BCCL uses the "Common" endpoint, which means you can log in with any Microsoft 365 account and Microsoft routes you to the correct tenant.

However, if you have a BCCL Partner license, you can specify --tenantid to authenticate against a specific customer's tenant. This enables cross-tenant delegate administration scenarios. Only Partner licenses support this feature; commercial licenses do not.

BCCL's OAuth sign-in requires admin consent in the customer's Microsoft Entra ID (Azure AD) tenant before any user can authenticate. Until consent is granted, the sign-in attempt fails with an admin-approval or consent-required message in the sign-in window. This is not caused by one specific missing API permission that a user or MSP can add manually; the requirement is admin consent, granted as a whole when an administrator signs in or consents. Do not try to hand-pick individual permissions or scopes.

There are two supported ways to grant it.

This is the easiest method and does not require the administrator to prepare anything in the Azure Portal in advance:

Start the BCCL sign-in as usual, so that the Microsoft sign-in window in which the consent error appears is open.
In that sign-in window, click the link "Have an admin account? Sign in with that account".
Sign in with a Microsoft Entra ID account that has administrator rights in the tenant.
Accept the consent prompt.

Consent is then granted for the tenant, and normal (non-admin) users can sign in to BCCL afterwards.

An administrator can alternatively grant the consent in the Azure Portal under Enterprise Applications.

Important: the BCCL application is not listed under Enterprise Applications before consent has been granted. If the administrator (or the customer's MSP) looks there and finds no entry for BCCL, that is expected. The administrator does not need to create or register an app manually. Use the in-product method above instead; granting consent that way creates the enterprise application entry.

Symptom	Cause and resolution
Sign-in fails, asks for approval, or you wonder "what permission am I missing?"	The app has not been granted admin consent in the tenant. An administrator must consent, either via the "Have an admin account? Sign in with that account" link in the sign-in window or via Azure Portal → Enterprise Applications. No individual permission needs to be requested from the MSP.
"I can't find BCCL in the list of Enterprise Applications in the Azure Portal. Do we need to create the app?"	No. The app is not listed until consent has been granted. Have the administrator use the admin sign-in link in the BCCL sign-in window instead.

Confirmed on BCCL app version 3 with Business Central 27.x.

First-Time Authentication

When you authenticate with OAuth for the first time, you need to provide the web service URL and trigger the device code flow:

BCCL --auth OAuth -w "https://api.businesscentral.dynamics.com/v2.0/{tenantid}/{env}/WS/{company}/Codeunit/bccl" --remember

BCCL displays a message like:

To sign in, use a web browser to open the page https://microsoft.com/devicelogin
and enter the code BXYZ9876 to authenticate.

Open https://microsoft.com/devicelogin in your browser, enter the code, sign in with your Microsoft 365 account, and approve the permissions if prompted. Once the login completes, BCCL prints a confirmation and the access token is saved.

If you included --remember, your connection settings (URL, auth method) are also saved, so the next time you only need task-specific parameters.

Subsequent Runs

After the first authentication, BCCL caches the access token in isolated storage at BCCL/BCCL.token.json. On subsequent runs within one hour, BCCL reuses the cached token without prompting you to log in again:

BCCL -t tables
BCCL -t getdata -s table=18 -f json -o customers.json

When running with --verbose, BCCL shows information about the cached token:

Active OAuth Access Token found, remaining authentication time: 00:42:15

After one hour, the cached token expires. The next time you run BCCL, it prompts you with a new device code to authenticate again.

After Initial Auth (No Browser Needed)

Once you have authenticated and the token is cached, you can run any BCCL command without specifying authentication parameters:

BCCL -t tables
BCCL -t getdata -s table=18 -f csv -o output.csv
BCCL -t mapping -s table=27 -o items-mapping.json

BCCL automatically detects the cached token and uses it. When the token expires after one hour, BCCL initiates a new device code flow.

Token Caching Details

The OAuth access token is stored in .NET isolated storage:

Detail	Value
Storage type	User-scoped isolated storage
File path within storage	`BCCL/BCCL.token.json`
Token lifetime	1 hour from the time of authentication
Expiry check	Based on the file's last-write timestamp plus 1 hour
Scope	`https://api.businesscentral.dynamics.com/user_impersonation`

The token file contains only the raw access token string (not a JSON object). BCCL checks the file's timestamp to determine whether the token is still valid. If the file is older than one hour, BCCL ignores it and requests new authentication.

Step-by-Step Example

Here is a complete walkthrough of setting up OAuth for the first time:

Step 1: Get Your Web Service URL

Open Business Central in your browser
Search for Web Services (Alt+Q)
Find the bccl codeunit and copy its SOAP URL

Step 2: Authenticate and Remember

BCCL --auth OAuth -w "https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/production/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" --remember

BCCL displays: To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ABCD1234 to authenticate.
Open the URL in your browser
Enter the code ABCD1234
Sign in with your Microsoft 365 credentials
Approve the permissions if prompted
Return to the terminal where BCCL confirms authentication

Step 4: Run Commands

After authentication, BCCL confirms:

Access to Business Central authenticated for 1 hour.
If your operation runs longer than 1 hour, please use S2S authentication instead.

Now run any command without re-authenticating:

BCCL -t tables
BCCL -t getdata -s table=18 -f json -o customers.json

Step 5: Re-Authenticate When Token Expires

After one hour, run BCCL again. It detects the expired token and starts a new device code flow automatically.

Cross-Tenant Authentication (Partner License)

If you have a BCCL Partner license, you can authenticate against a customer's tenant by specifying --tenantid:

BCCL --auth OAuth --tenantid "customer-tenant-id-guid" -w "https://api.businesscentral.dynamics.com/v2.0/customer-tenant-id-guid/production/WS/CRONUS%20Canada%2C%20Inc./Codeunit/bccl" -t tables

When you specify --tenantid, the device code flow is scoped to that specific tenant. The login page prompts for credentials from that tenant rather than the "Common" endpoint.

Note: Only Partner licenses support cross-tenant authentication. If you attempt to use --tenantid with a commercial license, BCCL displays the message: "Only the BCCL Partner license supports delegate admins and cross-tenant calls."

OAuth vs. S2S: Choosing the Right Cloud Method

Consideration	OAuth	S2S
User interaction	Required (browser login)	None
Token lifetime	1 hour, no auto-refresh	Renewed during a run at about 80% of the token's lifetime
Long-running operations	Limited to 1 hour (or the tenant-defined period)	Supported (tokens refresh during the run when the S2S parameters are on the command line)
Windows service mode	Not supported	Supported
Scheduled tasks	Not practical	Ideal
Cross-tenant (Partner)	Supported	Not supported
Azure AD App required	No (uses built-in)	Yes
Setup complexity	Minimal	Moderate (Azure AD config)

Besides the 1-hour token lifetime, OAuth access can also stop working after a period predefined by the tenant administrators. Because OAuth cannot be renewed without interaction, it is unsuitable for long-running or scheduled transfers; a long SQL replication run under OAuth can fail part-way through or show intermittent No connection could be made because the target machine actively refused it ... (api.businesscentral.dynamics.com:443) messages. S2S, by contrast, can re-authenticate while the operation is still running.

If your operations always complete within one hour and you are at the keyboard, OAuth is the simpler choice. If you need unattended operation or your tasks may run longer, use S2S Authentication and put all parameters on a single command line; see Running Long or Unattended Transfers Reliably.

Troubleshooting

Problem	Solution
"Login request timed out, aborting"	You did not complete the browser login within the timeout period. Run the command again and complete the login promptly.
"Only the BCCL Partner license supports delegate admins"	You specified `--tenantid` but do not have a Partner license. Remove `--tenantid` or obtain a Partner license.
Token expires during operation	OAuth tokens are valid for 1 hour and do not auto-refresh. For longer operations, switch to S2S authentication.
Long transfer fails or shows connection errors partway through	Switch to S2S authentication; S2S can re-authenticate during an ongoing operation. Pass all parameters on a single command line rather than using `--remember` plus a separate task command.
Sign-in window asks for admin approval / consent	Admin consent has not been granted in the tenant. See "Admin Consent" above.
Browser login succeeds but BCCL does not proceed	Ensure your firewall allows BCCL to reach `https://login.microsoftonline.com`. Check with `--verbose` for details.
"OAuth authentication failed, aborting"	The device code flow did not complete. Check that the device code was entered correctly and that you approved all permission prompts.

Use --verbose (-v) with any command to see detailed information about the OAuth flow, including token acquisition timing and cache status.