BCCL now supports OAuth Authentication

We have just updated BCCL to support OAuth authentication, both “normal” OAuth and Service2Service authentication. Check this video for the details:

In this video, Erik demonstrates how to use OAuth authentication with BCCL (BC Command Line), a powerful tool for importing and exporting data from Business Central. With basic authentication being deprecated for Business Central in the cloud, OAuth is becoming the only way to authenticate. Erik walks through two different OAuth methods: interactive device code flow and site-to-site (service-to-service) authentication.

What is BCCL?

For those unfamiliar, BCCL stands for BC Command Line. It’s a tool that enables you to:

  • Export data out of Business Central
  • Import data into Business Central from XML, JSON, Excel, and CSV files
  • Perform various data operations from the command prompt
  • Integrate into scripts and automation workflows
  • Handle any data size with excellent performance

When you run bccl without parameters, you get a comprehensive list of available parameters. Traditionally, you’d use --url, --username, and --password for basic authentication. BCCL still supports basic authentication for Docker containers, on-premises installations, and older versions, but a new --auth parameter has been added for OAuth support.

Method 1: Interactive OAuth (Device Code Flow)

The first OAuth method uses an interactive device code flow, similar to what you might recognize from Visual Studio Code’s sign-in process.

Authenticating

To initiate the OAuth flow, simply run:

bccl --auth oauth

BCCL will display a message: “To sign in, use a web browser to open this page and enter this code.” You copy the provided code, navigate to the URL in your browser, paste the code, confirm the sign-in, and you’re authenticated.

It’s important to understand what happens here: you haven’t directly logged into Business Central yet. Instead, you’ve obtained an access token that will grant access when you connect to the correct Business Central instance — the one the token is valid for.

Using the Connection

Once authenticated, you connect to a web service by providing the URL. You can use the --remember function to store parameters so you don’t have to type them on every call:

bccl --url https://your-bc-url --remember

Now you can query Business Central. For example, to see what tasks BCCL can perform:

bccl -t task

This queries the app-based component inside Business Central and returns a list of available operations:

  • Delete All — Delete all records
  • Delete Data — Delete data using a supplied data file
  • Get Data — Retrieve data from a table
  • Get Mapping — Get a mapping file from a table
  • Mass Update — Perform mass updates
  • Post Purchase Document — Post purchase documents
  • Post Sales Document — Post sales documents
  • Upload Data — Upload data to Business Central
  • Run Codeunit — Execute a codeunit
  • Get Tables — List available tables
  • Get Task — List available tasks

To retrieve customer data in JSON format (the default):

bccl -t getdata --table 18

To get the same data as CSV:

bccl -t getdata --table 18 --format csv

The authentication remains valid until the token expires (typically within an hour). To manually clear the stored credentials and connection details:

bccl forget

Method 2: Site-to-Site (Service-to-Service) OAuth

The second method uses site-to-site (also known as service-to-service) authentication. This is a non-interactive method, making it ideal for automation scenarios where no user is present to complete a browser-based sign-in.

Azure App Registration Setup

Before using this method, you need to create an Azure App Registration:

  1. Go to the Azure Portal and create a new App Registration
  2. Note the Application (Client) ID
  3. Under API Permissions, add application-level access for API.ReadWrite.All (or the appropriate Business Central API permission)
  4. Grant admin consent for the registration
  5. Create a Client Secret and save the value

Think of the App Registration as creating a user: the Client ID is the username, and the Client Secret is the password. The key advantage is that it’s not an interactive process — the credentials can be stored and used in automated scripts.

Registering in Business Central

After creating the Azure App Registration, you must also register it inside Business Central:

  1. Navigate to Azure Active Directory Applications in Business Central
  2. Add the Application (Client) ID from your App Registration
  3. Assign the appropriate permissions

Authenticating with BCCL

With the App Registration in place, authenticate using:

bccl --auth sitetosite --clientid "bada-b60d-..." --clientsecret "RUW..." --tenantid "your-tenant-id"

Note the key difference from the interactive method: you must specify the tenant ID in addition to the client ID and client secret. It’s a good practice to wrap the client secret in quotes, as it may contain special characters that could interfere with command-line parsing.

Once authenticated, the workflow is identical — remember the URL, then run tasks:

bccl --url https://your-bc-url --remember
bccl -t task
bccl -t getdata --table 18 --format csv

And when finished:

bccl forget

Source Code: Storing Secrets in AL

When building AL extensions that need to work with OAuth credentials, you’ll need to manage client IDs and secrets. Here’s a simple example codeunit structure for storing these values (though in production, you’d want to use a more secure approach such as Isolated Storage or Azure Key Vault):

codeunit 50102 "AL Secret"
{
    procedure getclientId(): Text
    begin
        exit('secret santa');
    end;

    procedure getclientsecret(): Text
    begin
        exit('enter your own');
    end;
}

The app definition from the project:

{
  "id": "c24c8b76-1ae7-4b5f-8ef7-d71571e90f8f",
  "name": "BCOauth2",
  "publisher": "Erik Hougaard",
  "version": "1.0.0.0",
  "platform": "13.0.0.0",
  "application": "13.0.0.0",
  "showMyCode": true,
  "runtime": "2.0"
}

Important: The placeholder values in the secret codeunit are intentionally not real credentials. In a production environment, never hard-code secrets directly in source code. Use secure storage mechanisms like Business Central’s Isolated Storage or Azure Key Vault integration instead.

Summary

With basic authentication being phased out for Business Central in the cloud, BCCL now supports two OAuth authentication methods:

  • Interactive OAuth (Device Code Flow) — Great for manual use, works similarly to Visual Studio Code’s sign-in process. Just use --auth oauth and follow the browser prompts.
  • Site-to-Site OAuth (Service-to-Service) — Ideal for automation and scripts. Requires an Azure App Registration with a Client ID, Client Secret, and Tenant ID, plus registration in Business Central’s Azure Active Directory Applications.

Both methods provide secure, token-based access to Business Central. Erik also mentions that at e-focus, they’ve used BCCL extensively to build transformation tools for QuickBooks and Sage that transfer complete databases into Business Central — demonstrating the power and versatility of this command-line tool.

Picture of hougaard

hougaard