¶ General
This is the installation guide for the Authorization Box. Authorization Box communicates with your Dynamics environment via a web service and a secure relay mechanism.
For more details about architecture and security, see Security and Compliance.
To use the Authorization Box, you first need to install two technical components. After that, you can start setting up your connection.
If you are looking for the installation guide for the Compliance Apps (Field Security or Field Validation), see Getting Started.
¶ Technical Installation
To communicate with the Authorization Box, a Dynamics web service and an Authorization Box Multi Connector need to be installed.
¶ Dynamics Web Service
¶ System Requirements
For the Cloud version of Microsoft Dynamics 365 Business Central, there are no additional requirements. For On-Premises installations of Microsoft Dynamics 365 Business Central, the following is required:
- Your license needs to be updated with granule Compliance Essentials (70077720). If you are still on a Dynamics NAV version, you need the granule Business Essentials (11018410). If you already have software from 2-Controlware, the granule will already be in your license.
- SOAP Services need to be enabled on the service tier configuration
- Supported versions: Microsoft Dynamics 365 Business Central (for Dynamics NAV versions: Dynamics NAV 2013 R2 and up)
¶ Installation
To install the required web services, you need to install the extension Compliance Essentials.
For the Cloud version, you can install either one of the available Compliance extensions (Field Security, Field Validation or Inventory Reconciliation). Compliance Essentials will be automatically installed with those extensions.
For On-Premises installations, you can download the extension from our web portal and install it manually.
For detailed extension installation instructions, see Getting Started.
After the extension is installed, the following web services should be available in your environment.
If you are still on a Dynamics NAV version, you can download the 2-Controlware software (.FOB) from our web portal, and install the .FOB file.
Afterwards, manually create the following web service: Codeunit 11112022 ABWebservice.
Make sure the Service Name is “AB”.
¶ Authorization Box Multi Connector
¶ System Requirements
On the server where you want to install the connector, the firewall needs to enable communication between:
- Inbound (internal network) : The Authorization Box Multi Connector and any Business Central service tier to be connected (especially the configured web service ports of the service tier)
- Outbound : The Authorization Box Multi Connector and our Azure Service Bus.
- Azure Relay port settings : You need to open the firewall's outbound ports as described in the following article https://docs.microsoft.com/en-us/azure/azure-relay/relay-port-settings#wcf-relays.
This article includes a table that describes the required configuration for port values for Azure Relay. - IP/Host whitelisting : Authorization Box is hosted on Azure. As a result, the Authorization Box does not have a fixed IP address, but changes daily or more often.
Therefore, a range of IP addresses must be added in the firewall (if applicable). See: https://blogs.msdn.microsoft.com/servicebus/2017/01/13/azure-wcf-relay-dns-support/.
You should test whether you can whitelist the host name: box-sb-prod.servicebus.windows.net.
If this does not work, the following PowerShell script can be used to find IP addresses to whitelist: https://github.com/Azure/azure-relay-dotnet/blob/master/tools/GetNamespaceInfo.ps1 . This returns a list of all IP addresses associated with our service bus. It is possible that this is a large number of addresses.
- Azure Relay port settings : You need to open the firewall's outbound ports as described in the following article https://docs.microsoft.com/en-us/azure/azure-relay/relay-port-settings#wcf-relays.
If you run Business Central in the Cloud, we can host the connector for you. If that is the case, you can skip this step.
If you want more information about hosting the connector, please contact sales@2-controlware.com .
¶ Installation
On the server where you want to install the connector, run the installer setup.exe from the zip file authorizationbox-setup.zip.
You can download the installer when you log in to the Authorization Box and go to Setup=>General.
In the fasttab Databases, use the button ‘Download Connector’.
If you are a partner, the file can also be downloaded from our portal.
Choose a different location for installation if required
Insert the security key you received in the welcome mail from our backoffice. If you did not receive a security key yet, please contact support@2-controlware.com.
Confirm installation by clicking on Next
After the installation is finished, the following Windows Services are installed:
.png)
Make sure that also the service Authorization Box Multi Connector Update runs.
This service will automatically update the Authorization Box Multi Connector if needed.
Please test if you can reach the Dynamics web service on the server where the connector is installed.
You can test this by copying the SOAP URL from the page Web Services in Dynamics from the webservice “AB” (Codeunit 70077770) and paste this in a browser. After authentication you should see a WSDL page.
¶ Configure Business Central
To access the Business Central web service, the following is required:
- A SUPER user
- If you use OAuth to authenticate, a valid (consented) Entra Application is required.
OAuth is mandatory for the latest (Cloud) Business Central versions. If you are on an older version, you can skip this step.
Open your Business Central environment and search for Microsoft Entra Applications (in older versions Azure Active Directory Applications).
Open the application card called “Integration with Authorization Box.”
This application is automatically installed when you install the extension Compliance Essentials.
If for some reason you cannot find an application card for Authorization Box or it got accidentally removed, you can add the application card manually.
¶ How to create the application card manually
Click on 'New' to add a new Microsoft Entra Application Card and create the card with the following data:
- Client ID = “{54458fab-b778-4677-b5f5-04b3d0fe39a5}”
- Description = Integration with Authorization Box
- State = Enabled
- Contact Information = 2-Control B.V.
- App ID = Select the Compliance Essentials extension.
In case you cannot find the Compliance Essentials extension, you first need to complete the Technical Installation above.
The state of the application must be set to “Enabled”.
Click on the button Grant Consent and follow the wizard to give permission to the Authorization Box OAuth app [ important ! ].
When you have finished the wizard, the message should appear : “Consent was given successfully”.
¶ Configure Authorization Box
When you have finished the technical installation and the configuration of Business Central, you can start configuring Authorization Box by creating your first database connection.
¶ Create your first database connection
Log in at https://login.2-controlware.com using the credentials provided in the registration email. The user name is the email address used to register with Authorization Box. If you do not have an account yet, please contact support@2-controlware.com .
When logging in for the first time, you are required to change your password. Next, click in the menu on Setup -> General and click on the fasttab "Databases"
- Click on the 'New' button
- Enter the Database name and click on ‘Next’
- Paste the SOAP-URL from the web service in the Connection URL-field (http(s)://<domain>:<port>/<Dynamics service name>/WS/<company>/Codeunit/AB).
You can find this URL in your Dynamics environment in the page Web Services. Search for the web service called “AB” (codeunit 70077770) - Select the Authentication method that is used for your Business Central
- E-mail for warnings : you need to fill in a valid email address where warnings can be sent to
- Enter the required authentication details for the SUPER user account that will be used for the connection. For details about authenticating with OAuth, see Authentication with OAuth
- In case your authentication protocol uses NTLM, you have to enable the field “Use NTLM”. If you do not know this, the connection check will validate if NTLM is required
- Click on the button ‘Database’ and select "Test connection"
- After a successful test, click on the buttons ‘Save’ and ‘Close’ to leave the database setup
The Authorization Box user that creates the connection will automatically have permissions for the newly created database connection.
For other Authorization Box users, you have to grant permissions for the new connection via their user card.
You can access a user card using Setup -> General and click on the fasttab “Users”.
Next, click on a user name to access their user card.
¶ Authentication with OAuth
To authenticate with OAuth, there is some configuration required. See Configure Business Central above.
When you are using OAuth On-Prem authentication, it is necessary to set the ADOpenIdMetadataLocation parameter in the server instance.
(see https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/authenticating-users-with-azure-ad-openid-connect?tabs=singletenant%2Cadmintool#task-4-configure-)
Afterwards, to setup OAuth authentication in your Database Connection, follow these steps whilst setting up your database connection:
.png)
- Select the Authentication Method: OAuth Device Code
- Click on the button ‘Edit’
.png)
- Fill in the required fields: Tenant (Domain or Tenant-id) and Scope (by default https://api.businesscentral.dynamics.com/.default)
- Click on 'Connect'
- Follow the wizard. Copy the code and click on 'Connect'.
- Paste the code you copied in the previous step and click 'Next'
- Sign in with an account that has SUPER rights in the Business Central environment.
- Finish the sign in.
- Return to the form and click on 'Check' (Step 3). You will see a message that a token has been retrieved successfully.
- Close the form, click on the ‘Database’ button and choose “Test the connection”. You should receive a message that the connection has successfully been made.
To maintain the connection, the token must be refreshed periodically. This is automatically handled by Authorization Box.
If a situation occurs that the token is no longer valid, this is usually because the password of the connection-user has changed or that changes have been made to the tenant settings. In this case you will be informed by an e-mail.
The problem can be solved by following the above steps again.
¶ Settings Menu
¶ Changing the User (actor) settings of the currently active database
You can change the time zone and language of the currently active database under the User Settings.
- Open the User settings by clicking on the email address of the user account on top of the page and choose “Settings”.
.png)
- Modify the settings as you wish and confirm with 'Save & Close'
¶ Change Password
It is possible to change your password to access the Authorization Box any time you want.
- Click in the upper right corner on your account for the Set up menu and choose “Change Password”.
- Fill in the required fields and click on ‘Change Password’
¶ About the Authorization Box
In the Setup menu you can also choose for the "About the Authorization Box".
Here you can find the Version number, Database name you are in, the Server name and the Internal IP address of the Server.
In Setup / Administration you can find :
- General setup of Customer settings, Contracts, Databases and Users
- How to add users to the Authorization Box and how to set up Multifactor Authentication
- Set up Approval settings
- Set up Notifications
- Architecture of the Authorization Box on Azure
- Use with API
- Overwrite current permissions in Business Central with those of the Authorization Box