Setup the OAuth authentication method

As of version 20 (2022 Wave 1) of Dynamics 365 Business Central the Basic Authentication method is deprecated and can no longer be used for setting up the connection between Authorization Box and your Dynamics environment. Existing tenants migrating to version 20 can still use Basic Authentication. New tenants created on version 20 cannot use Basic Authentication. Basic Authentication will be disabled for everyone on Business Central 21 (2022 Wave 2).

Basis Authentication will be replaced with the OAuth 2.0 authorization protocol. OAuth 2.0 is a standard authorization protocol designed to allow an application to access resources hosted by other applications on behalf of a user. OAuth 2.0 provides consented access and restricts actions of what the client app can perform on resources on behalf of the user, without ever sharing the user’s credentials. OAuth 2.0 uses Access Tokens (which essentially are data that represents the authorization to access resources on behalf of the end-user) and scopes (used to specify exactly the reason for which access to resources may be granted).

This document describes how you can set up Business Central and the Authorization Box to make use of the OAuth 2.0 protocol as authentication method.

1. Open Your Business Central environment and search Azure Active Directory Applications.
   
   
2. Open the application card called “Integration with 2CAB” or “Integration with Authorization Box.” The application card is part of the Compliance Essentials installation. If You can't find a application card for the Compliance Essantials, You are propably running an older version of the app. In this case You can add the application card manually. Click on New to add a new Azure Active Directory Application Card. 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 can't find the Compliance Essentials extension, You need to install the 2-Control Compliance Essentials from the BC Extension Management.

1. The state of the application must be set to Enabled.
2. Click on the button Grant Consent and follow the wizard to give permission to the Authorization Box OAuth app.
   
   
3. When You are finished with the wizard You must get the message that Consent was given successfully.
   
   

1. Create a new database or edit an existing one. Databases can be maintained from under Setup, General and the Fast Tab Databases. More information on how to create a database can be found in our Wiki under Installation: Wiki 2-Control - Authorization Box Installation.
2. Select the Authentication Method “OAuth Device Code.” In case of a new database You need to save the database first to make the authentication method “OAuth Device Code” available (this will be fixed in a future release).
   
   
3. Click the Edit button and fill in the fields Tenant and Scope:
   • Tenant: The Azure Active Directory Tenant ID or the corporate domain name.
   • Scope: The URL of the Azure resource that provides access to BC. You can use “https://api.businesscentral.dynamics.com/.default” if You use the cloud version of BC.
4. Click on Connect.
   
   
5. Follow the steps mentioned on the screen. Copy the code and click on Connect.
   
   
6. Paste the code and click on Next.
   
   
7. Sign in with an account that has SUPER rights in the Business Central environment. Finish the sign in and if the process is successfully completed, You should get the following message:
   
   
8. Return to the Authorization Box and click the button Check. You will see a message that a token has been retrieved.
   
   
9. Close the form and click the Database button to test the connection. You should get a message that the connection has successfully been made.
   
   
10. 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 user that is used to authorize the connection 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 steps 3-9 again.