Setup a AX Connection using AX Connection Manager

SSIS Integration Toolkit AX Connection Manager is an SSIS connection manager that can be used to establish connections with Microsoft Dynamics 365 Finance & Operations or Microsoft Dynamics AX Server. 

AX connection manager allows you to specify how you want to connect to your 365/AX server. 

To add a AX connection to your SSIS package, right-click in the Connection Manager area, and choose "New Connection..." from the context menu. You will be prompted the following window, where you can choose the "DynamicsAX" item to add the connection.

new connetion

Add AX Connection Manager

AX Connection Manager contains the following three pages which configure how to connect to Microsoft Dynamics AX server.

  • General
  • Advanced Settings
  • More Info 

General page

The General page of AX Connection Manager allows you to specify the general settings of the connection. Specifically, this is where you enter authentication information for your Dynamics AX connection.

AX Connection Manager - Business Connector

Connection API (since v9.0)
The Connection API drop-down allows you to specify which connection API you want to use to build the connection. It includes two types of APIs:
  • Business Connector: Microsoft Dynamics AX (4.0 – 2012 R3)
  • OData: Microsoft Dynamics 365 Operations & Financials
Connection API - Business Connector

Microsoft Dynamics AX .NET Business Connector is usually shipped with AX installation package. It needs to be installed on the developer machine or your integration servers.

User Name
The User Name option allows you to specify the Windows user account that you want to use when connecting to Dynamics AX server. Note that the user name should be a Windows domain account instead of the actual Dynamics AX user account. 
User Domain
The User Domain option is used to specify the active directory domain of the Windows user. 

AX Connection Manager - OData

Connection API - OData
OAuth Type

The OAuth Type option allows you to specify the OAuth type you want to use. There are three options available.

  • Password
  • Certificate
  • Client Credentials (server to server authentication)
Authorization Server (URL)

The Authorization Server (URL) option allows you to specify your authorization server endpoint which you can use to authorize the application to access your Dynamics 365 for Finance and Operations data.

Note: This option is default to https://login.windows.net/ when connecting to Dynamics 365 for Finance and Operations. Depending on your environment, you can provide your custom URL by check the Use a custom URL option.

Service URL

The Service URL option allows you to specify your organization's root service endpoint which you can use to connect to your Dynamics 365 for Finance and Operations.

User Name

The User Name option allows you to specify the user account that you want to use when connecting to your Dynamics 365 for Finance and Operations.

Note: This option is only available when Password OAuth type is selected.

Password

The Password option allows you to specify the password for the above user account in order to login to your Dynamics 365 for Finance and Operations.

Note: This option is only available when Password OAuth type is selected.

Active Directory Resources

The Active Directory Resources option allows you to specify the Microsoft Active Directory (AAD) Resource URL to complete the OAuth authorization process. The URL is usually your organization's root service endpoint (i.e. same as the Service URL).

Active Directory Tenant

The Active Directory Tenant option allows you to specify the Tenant name where the Client App Id is verified to complete the authorization process. This should typically be the email domain that you use to login to your Dynamics 365 for Finance and Operations instance - there might be exceptions however.

Client App Id

The Client App Id option allows you to specify the GUID value that identifies a client application in Microsoft Azure Active Directory (AAD). Note that you may need to register your application with AAD via the Azure portal in order to generate your Client App Id.

To create an application in Azure Active Directory (AAD):

  1. Log in Azure Portal
  2. Navigate to Azure Active Directory | App registrations | New application registration
  3. Create a new application, there are two options:
    • Native application
    • Web app / API application

In order to work with Certificate and Client Credentials (server to server authentication) OAuth Type, it is also required to have an Azure Active Directory applications created in your Dynamics 365 for Finance and Operations:

  1. Log in Dynamics 365 for Finance and Operations
  2. Navigate to Modules | System administration | Setup and click Azure Active Directory applications
  3. Click New and fill out the required fields to specify the Azure Active Directory applications. Note that the Client Id is the Client App Id that we've created in the previous step, and then specify the User ID for this application.
Certificate Thumbprint

The Certificate Thumbprint option allows you to specify the thumbprint once you have selected or created an application in Microsoft Azure Active Directory (AAD).

Before generating a thumbprint in Microsoft Azure Active Directory (AAD), you would need to create a Public/Private Key Pair:

  1. Download and install OpenSSL for Windows. Note that you may need to restart your machine after installation
  2. Launch Windows Command Prompt as an administrator using the "Run as administrator" option
  3. In the command prompt window, navigate to the bin folder of the installation location of OpenSSL, e.g. "cd C:\OpenSSL-Win32\bin"
  4. Execute the following commands. Note that the third command will prompt you to enter a password. Two files will be generated in this step:
    • publickey.cer: this is the Public Key file that is going to be uploaded to Microsoft Azure Active Directory (AAD).
    • public_privatekey.pfx: this is the Private Key file that is going to be installed on the machine where AX Connection Manager is used.

    openssl genrsa -out privatekey.pem 1024
    openssl req -new -x509 -key privatekey.pem -out publickey.cer -days 1825
    openssl pkcs12 -export -out public_privatekey.pfx -inkey privatekey.pem -in publickey.cer

To generate a thumbprint for a specific Web App / API application in Azure Active Directory:

  1. Log in Azure Portal
  2. Navigate to Azure Active Directory | App registrations and select the Web App / API application
  3. Click Settings | Keys | Upload Public Key
  4. Specify the location of Public Key file (publickey.cer) and click Save to display the Thumbprint.

Once you get thumbprint from Azure Active Directory, please be sure to install the Private Key file (public_privatekey.pfx) on the machine where AX Connection Manager is used.

Note: This option will only be available to Certificate OAuth Type.

Client Secret

The Client Secret option allows you to specify the client secret that you have requested from Microsoft Azure Active Directory (AAD), which will be used to authenticate using Azure Web application.

To create a client secret for a specific Web App / API application:

  1. Log in Azure Portal
  2. Navigate to Azure Active Directory | App registrations and select the Web App / API application
  3. Click Settings | Keys and fill out the required fields
  4. Click Save to display the Client Secret

Note: This option is only required when working with a Web App / API application.

Data Scope

The Data Scope drop-down provides two options to select. You can specify the scope of this connection as Default Company Only or All Companies.

Service Timeout (secs)

The Service Timeout (secs) option allows you to specify a timeout value in seconds for the connection. The default value is 120 seconds.

Authorize Button

By clicking the Authorize button, it will pops up a Application Access Authorization window to help you authorize the application to access your Dynamics 365 for Finance and Operations data. All you need to do is to provide the Redirect URL depending on your Azure Application's application type:

  • Native application: put the Redirect URI of the application to the Redirect URL field.
  • Web app / API application: put the Sign-on URL of the application to the Redirect URL field.

Two types of authorizations are supported:

  • Authorize in App
  • Authorize in Browser

AX Connection Manager - Application Access Authorize.png

Note: This button is only available when Password OAuth type is selected.

Test Connection

After all the connection information has been provided, you may click the "Test Connection" button to test if the user can successfully login to the AX server.

Advanced Settings page

The Advanced Settings page of AX Connection Manager allows you to specify some advanced settings of the connection. 

AX Connection Manager - Settings - Business Connector

Advanced Settings (Business Connector)
Proxy Account - User Name

Specify the .NET Business Connector proxy account's user name that is used for the AX connection. This may or may not be required depending on your system's Dynamics AX configuration.

Proxy Account - Password

Specify the .NET Business Connector proxy account's password. This is only required when you have specified a proxy account.

Proxy Account - Domain

Specify the .NET Business Connector proxy account's Windows domain name. This may or may not be required in the case that a proxy account is specified.

Object Server Name

Specify the Microsoft Dynamics AX Application Object Server (AOS) used for the connection. This may or may not be required depending on your system's Dynamics AX configuration.

Configuration Name

Specify the name of Microsoft Dynamics AX configuration to be used for the connection. This can be a file path to your AX configuration file (.axc).

Company

Specify the company to be used for the connection. This is an optional parameter.

Language

Specify the language to be used for Dynamics AX labels for the connection session. An example of such language is "en-us". This is usually an optional parameter.

Tenant

Specify the tenant when establishing the connection to your Dynamics AX server. This is usually an optional parameter.

AX Connection Manager - Settings - OData

Advanced Settings (OData)
Proxy Mode

Proxy Mode option allows to specify how you want to configure the proxy server setting. There are three options available.

  • No Proxy
  • Auto-detect (Using system configured proxy)
  • Manual
Proxy Server

Using the Proxy Server option, you can provide a proxy server to connect to the Dynamics 365 for Operations.

Port

The Port option allows you to specify port number of the proxy server for the connection.

Username

The Username option allows you to specify the proxy user account.

Password

The Password option allows you to specify the proxy user’s password.

Note: Proxy Password is not included in the AX connection manager's ConnectionString property by default. This is done by design for security reasons. However you can include it in your ConnectionString if you want to parameterize your connection manager. The format would be ProxyPassword=myProxyPassword; (make sure you have a semicolon as the last character). It can be anywhere in the ConnectionString.

Retry on Intermittent Errors

This is an option designed to help recover from possible intermittent outages or disruption of service. It prevents the integration process from stopping due to temporary issues. Enabling this option will allow service calls to be retried upon certain types of failure. A service call may be retried up to 3 times before an exception is fired. Retries occur after 0 seconds, 15 seconds, and 60 seconds.

Warning: We have designed our retry feature carefully such that the retry should only occur when it is deemed safe to do so; however, in some occasions such retry service calls could result in the creation of duplicate data.

Ignore Certificate Errors (since v10.0)

This option can be used to ignore those SSL certifcate errors when connecting to Dynamics 365 Finance & Operations .

Warning: Enabling "Ignore Certificate Errors" option is generally NOT recommended, particularly for production instance. Unless there is a strong reason to believe the connection is secure - such as the network communication is only happening in an internal infrastructure, this option should be unchecked for best security.

Note: When this option is enabled, it applies to all HTTP-based SSL connections in the same job process, it is not just limited to Dynamics 365 for Finance and Operations connections.

More Info page

More Info page shows some basic information about the toolkit. In this page, you can find the version information of the toolkit.

AX Connection Manager - More Info