Getting started with Devart ODBC Driver for Dynamics 365

Quick start: Connect to Microsoft Dynamics 365 with ODBC

To connect to Microsoft Dynamics 365 using the Devart ODBC Driver:

1. Download and install the Driver for Windows, macOS, or Linux.
2. Activate the Driver using your activation key, or continue with the 30-day trial. On Windows and macOS this is a step in the installer; on Linux, run the activator afterwards.
3. Create an ODBC data source (DSN) and select Devart ODBC Driver for Dynamics 365.
4. Configure the connection by specifying the Dynamics server and authenticating either via OAuth 2.0 or with your Dynamics user ID and password.
5. Use the DSN in your ODBC-compatible application to connect to Microsoft Dynamics 365 and work with its data.

The following sections provide detailed installation and configuration instructions for each supported operating system.

Prerequisites

Before you begin, make sure your environment meets the following requirements:

• Operating system: 32-bit or 64-bit Windows (including Windows Terminal Server), macOS x64 or ARM (Apple silicon), 64-bit Linux.
• ODBC driver manager: Included with Windows. On macOS, install iODBC. On Linux, install unixODBC.
• Connection details: Microsoft Dynamics 365 instance URL and valid account credentials.
• DSN configuration tool (optional): On macOS and Linux, you can use Devart ODBC Administrator to create and manage data sources through a graphical interface. The tool is distributed separately from the Driver and is available on the Devart website. Alternatively, configure data sources manually in the odbc.ini file.
• Activation key: A purchased version of the Driver requires an activation key. For evaluation purposes, you can use the trial version, which is valid for 30 days from installation.
• Administrator rights: Required to install the Driver on all supported operating systems.

For a complete list of supported database servers, operating systems, and third-party tools, see the ODBC Driver for Dynamics 365 compatibility page.

Install the ODBC Driver

Installing the Devart ODBC Driver for Microsoft Dynamics 365 is straightforward. All you need to do is download the package for your operating system and follow the installation instructions.

Install the Driver on Windows

1. Download the ODBC Driver for Dynamics 365 from the Devart website, open it, and click Next.

2. Read the License Agreement, select I accept the agreement, and click Next.

3. On the Select Destination Location page, keep the default folder or click Browse to choose another one, and click Next.

4. On the Select Components page, select the components to install, then click Next.

5. On the Select Start Menu Folder page, specify the folder for the Driver shortcuts. To skip creating a Start Menu folder, select Don't create a Start Menu folder. Click Next, then click Install.

6. On the License Information page, select Input activation key and enter your key. You can find it in the registration email or your Customer Portal. To open the Customer Portal, click Get Activation Key.

If the activation key is saved on your computer, click Load Activation Key and select the corresponding file.

To evaluate the Driver without a purchased key, select Trial evaluation.

7. Click Next, then click Finish to complete the installation.

Install the Driver on macOS

1. Download the ODBC Driver for Microsoft Dynamics 365 PKG file from the Devart website and double-click the package to run it.

Note

macOS may block the installation package because Apple cannot verify it. If this happens, allow the package manually:

1. Dismiss the warning.
2. Open System Settings > Privacy & Security. On macOS 12 and earlier, open System Preferences > Security & Privacy > General.
3. Find the message about the blocked package, and click Open Anyway.
4. Confirm that you want to open the package, and enter your administrator password if prompted.

2. In the installer, click Continue.

3. Read the license agreement and click Agree.

4. On the Registration page, select Input activation key and enter your key, or click Load Activation Key and select the file that contains it. To evaluate the Driver without a purchased key, select Trial evaluation. Click Continue.

5. On the Installation Type page, click Install. To choose which components to install, click Customize first. When the installation finishes, click Close.

You can also activate the Driver later from the Terminal. Navigate to /Library/ODBC/Devart/Dynamics and run the activator with your key.

cd /Library/ODBC/Devart/Dynamics
sudo ./dynamicsodbcactivator -a <your_activation_key>

Install the Driver on Linux

On Linux, the Driver requires the unixODBC driver manager, which must be installed separately. Follow the track that matches the package format of your distribution.

DEB-based distributions, such as Ubuntu and Debian

The commands below apply to Ubuntu 26.04 LTS, 24.04 LTS, and 22.04 LTS.

1. Install the unixODBC driver manager.

cd ~/Downloads
sudo apt-get update
sudo apt-get install -y unixodbc odbcinst

2. Download the DEB package from the Devart website.

3. Open a terminal, navigate to the folder that contains the package, and install the package and its required dependencies.

cd ~/Downloads
sudo apt-get install -y ./devartodbcdynamics_amd64.deb

4. Activate the Driver. Navigate to the folder where it is installed, /usr/share/devart/odbcdynamics, and run the activator with your key.

cd /usr/share/devart/odbcdynamics
sudo ./dynamicsodbcactivator -a <your_activation_key>

5. Verify that the Driver is registered.

odbcinst -q -d

The output should include [Devart ODBC Driver for Dynamics 365].

Then verify that the DSN created during installation is registered.

odbcinst -q -s

The output should include the automatically created DSN.

RPM-based distributions, such as CentOS, RHEL, and Fedora

The commands below apply to CentOS Stream 9.

1. Install the unixODBC driver manager:

sudo dnf install unixODBC

2. Download the RPM package.

3. Open a terminal, navigate to the folder that contains the package, and install the package and its required dependencies.

cd ~/Downloads
sudo dnf install ./devart-odbc-dynamics.x86_64.rpm

4. Activate the Driver. Navigate to the installation folder and run the activator with your key:

cd /usr/local/devart/odbcdynamics
sudo ./dynamicsodbcactivator -a <your_activation_key>

5. Verify that the Driver is registered:

odbcinst -q -d

The output should include [Devart ODBC Driver for Dynamics 365].

Then verify that the DSN created during installation is registered:

odbcinst -q -s

The output should include the automatically created DSN.

Configure an ODBC data source

In this guide, you create a Data Source Name (DSN) for the ODBC connection and verify the connection details. A DSN stores connection settings, such as the server URL and credentials that applications use to connect to Dynamics 365. Applications can also connect without a DSN, by passing the same parameters in a connection string.

Configure a DSN on Windows

1. In Windows Search, enter ODBC Data Sources, and open the ODBC Data Source Administrator that matches the bitness of your application.

2. Select the User DSN, System DSN, or File DSN tab, and click Add:

• User DSN — Available only to the user who creates it.
• System DSN — Available to all users on the computer.
• File DSN — Stores connection settings in a file that can be shared between computers where the required ODBC driver is installed.

3. In the Create New Data Source dialog, select Devart ODBC Driver for Dynamics 365, and click Finish.

4. In the Devart ODBC Driver for Dynamics 365 Configuration dialog, enter a Data Source Name and an optional Description. In the Server field, enter the URL of the Dynamics 365 instance to which you are going to connect.

5. To authenticate, you can use either OAuth 2.0 authentication (the default method) or your user ID and password.

If you are authenticating via OAuth 2.0:

• Click Sign in to Dynamics 365 to obtain the Refresh Token.

• Sign in to your Microsoft account with access to Dynamics 365 and grant the necessary permissions.
• The Refresh Token field is filled automatically. Select Save Token to store it.

If you are authenticating with your user ID and password:

• Select User ID and Password in the Authentication field and enter your credentials.

6. Optional: Click Test Connection to verify the connection settings.

7. Click OK to save the DSN settings.

To fine-tune metadata, timeout, and compatibility behavior, use the Advanced Settings tab of the same dialog. For details, see Advanced connection options.

Configure a DSN on macOS

DSNs are managed in Devart ODBC Administrator, a graphical tool that is distributed separately from the Driver. Download and install it before you continue.

1. Open Devart ODBC Administrator (root), select the System DSN tab (recommended), and click Add. Enter your password when prompted.

2. In the Choose a driver dialog, select Devart ODBC Driver for Dynamics 365 and click OK.

3. In the Devart ODBC Driver for Dynamics 365 Configuration dialog that opens, enter a Data Source Name, an optional Description, and your connection parameters. The ODBC Driver for Dynamics 365 supports OAuth 2.0 authentication and authentication with a User ID and password.

If you are using OAuth 2.0:

• Enter the server address of your Dynamics 365 instance and click Sign in to Dynamics 365.

• Sign in with your Dynamics 365 credentials. The Refresh Token field is filled automatically.

If you are using your Dynamics 365 user ID and password:

• Enter the server address of your Dynamics 365 instance, your User ID, and password.

4. Optional: Click Test Connection to verify the connection details.

5. Click OK to save the DSN settings.

To configure a DSN by editing the odbc.ini file, see Connect on macOS in the documentation.

Configure a DSN on Linux

As on macOS, Devart ODBC Administrator is distributed separately from the Driver. Download and install it from the Devart website before you continue.

cd ~/Downloads
sudo apt-get install -y ./devartodbcadministrator_amd64.deb

1. Open Devart ODBC Administrator (root), select the System DSN tab, and click Add.

2. In the Choose a driver dialog, select Devart ODBC Driver for Dynamics 365 and click OK.

3. Enter a Data Source Name, an optional Description, and the connection parameters: the Dynamics 365 server address, your User ID, and password.

4. Optional: Click Test Connection to verify the connection settings.

5. Click OK to save the DSN settings.

Alternatively, define the DSN in /etc/odbc.ini. The installation creates a sample DSN named DEVART_DYNAMICS that you can adjust:

[DEVART_DYNAMICS]
Driver=Devart ODBC Driver for Dynamics 365
Data Source=your_dynamics_server_url
User ID=your_dynamics_user_id
Password=your_dynamics_password
Authentication=Login

To verify the data source from a terminal, connect to it with isql, the command-line tool provided by unixODBC. Replace <your_dsn_name> with the name of your DSN:

isql -v <your_dsn_name>

Connect to Dynamics 365 using a connection string

In addition to using a DSN, you can connect to Dynamics 365 by specifying the connection parameters directly in an ODBC connection string. This type of connection is known as a DSN-less connection.

The following table summarizes when to use each connection method:

For a DSN-less connection, use the following connection string as a starting point:

DRIVER={Devart ODBC Driver for Dynamics 365};Server=https://dynamicsaccount.crm.dynamics.com;User ID=your_dynamics_username;Password=your_dynamics_password

Replace the placeholder values with your connection details:

• Server — the hostname of the Dynamics 365 server.
• User ID — your Dynamics 365 username.
• Password — your Dynamics 365 password.

For OAuth 2.0 authentication, use the following connection string configuration.

DRIVER={Devart ODBC Driver for Dynamics 365};Authentication=OAuth;Server=https://dynamicsaccount.crm.dynamics.com;Refresh Token=your_dynamics_refresh_token

Replace the placeholder values with your connection details:

• Server — the hostname of the Dynamics 365 server.
• Refresh Token — the Refresh Token for your Dynamics 365 account.

You can also connect via a proxy server; in this case, use the following connection string.

DRIVER={Devart ODBC Driver for Dynamics 365};Server=https://dynamicsaccount.crm.dynamics.com;User ID=your_dynamics_username;Password=your_dynamics_password;Proxy Server=your_proxy_server;Proxy Port=8080;Proxy User=your_proxy_username;Proxy Password=your_proxy_password

Replace the placeholder values with your connection details:

• Server — the hostname of the Dynamics 365 server.
• User ID — your Dynamics 365 username.
• Proxy Server — the hostname or IP address of the proxy server.
• Proxy Port — the proxy port.
• Proxy User — the proxy username.
• Proxy Password — the proxy password.

You can also specify advanced connection parameters to configure connection timeout, string types, ODBC behavior, and other Driver settings.

For the complete list of supported options, see Dynamics 365 ODBC connection string parameters.

For examples of using a connection string in different programming languages, see Connect to Dynamics 365 from programming languages.

Troubleshooting

If you cannot connect to Dynamics 365 through the Devart ODBC Driver, use the following solutions to resolve common connection issues.

"Product is not activated or has been deactivated" error

This error occurs when the Driver has not been activated or its activation is no longer valid. Activation is required for both purchased and trial versions.

• Windows: Open the DSN configuration dialog, go to the License tab, click Input Activation Key, and enter your activation key.
• macOS and Linux: In Devart ODBC Administrator, select the DSN and click Configure. On the License tab of the configuration dialog, click Input Activation Key and enter your activation key. Alternatively, run the dynamicsodbcactivator utility from the Driver installation folder with your activation key.

After activation, test the connection again.

ODBC data source not found or Driver not available

If your application cannot find the DSN or the Devart ODBC Driver for Dynamics 365, check the application and Driver bitness.

A 32-bit application cannot use a DSN created in the 64-bit ODBC Data Source Administrator, and a 64-bit application cannot use a DSN created in the 32-bit administrator.

Make sure that:

• The DSN is created in the ODBC administrator that matches your application's bitness.
• The corresponding 32-bit or 64-bit version of the Driver is installed.
• The application is configured to use the correct DSN.

Cannot connect to the Dynamics 365 server

If the Driver cannot reach the Dynamics 365 server, verify the server and network settings:

• Make sure the Server field contains the correct host name.
• Verify that the Dynamics 365 server is reachable from the client computer.
• Check that your firewall allows outbound connections to the Dynamics 365 server.

Login or connection fails

If the Dynamics 365 server is reachable but authentication fails, check the connection credentials:

• Check the Authentication setting. The Driver supports OAuth and username/password authentication; ensure the required parameters for the selected method are provided.
• Verify the User ID and Password.
• Sign in to Dynamics 365 again and generate or save a valid refresh token through the Driver's configuration dialog.
• Ensure that the authenticated user has access to the Dynamics 365 environment.
• If Save Password is cleared, the application must provide the password at runtime. Applications that cannot display a password prompt may fail to connect.

Dynamics 365 connection times out

If the server is available but the connection takes too long to establish, increase Connection Timeout on the Advanced Settings tab. The default connection timeout is 15 seconds.

Also check the network connection and make sure the Dynamics 365 server is not overloaded or temporarily unavailable.

Additional resources

After you install and configure Devart ODBC Driver for Dynamics 365, use the following resources to continue setting up and working with your connections:

• Connection string parameters — Browse the complete list of connection options for configuring server access, timeouts, IP version, ODBC behavior, and other Driver settings.
• Advanced features — Explore the advanced features of Devart ODBC Driver and how to enable and use them.
• Dynamics 365 integrations — Find step-by-step guides for connecting BI, reporting, analytics, and other ODBC-compatible tools to Dynamics 365.
• Use the Driver from programming languages — Connect to Dynamics 365 from applications written in Python, C#, C/C++, Go, Node.js, PHP, R, Visual Basic, and other supported languages.
• ODBC Driver for Dynamics 365 documentation — Explore installation, configuration, connectivity, and advanced Driver features.