OAuth Applications

  • How do I create an OAuth application?
  • How do I register an app for a Business Central web service connection?
  • How do I set application permissions in Business Central?
  • How do I create an OAuth Application to connect to Business Central?
  • What are the different types of credentials used in an OAuth Application?
  • What is a redirect URL?
Tip

Summary: OAuth Applications stores credentials and tokens to authenticate against a web service. This chapter provides instructions on how to create an OAuth application and register an app for a Business Central web service connection, as well as how to set application permissions in Business Central. It also explains the four types of OAuth authentication, including Client Credentials, Password Credentials, Authorization Code, and Implicit, and describes the Redirect URL.

An OAuth Application stores credentials and tokens to authenticate against a web service. OAuth 2.0 is an industry-standard protocol for authorization. Find more details on https://oauth.net/2/.

To create an OAuth application

  • What is the process for creating an OAuth application?
  • How do I register an app for a Business Central web service connection?
  • How do I set application permissions in Business Central?
  • How do I create an OAuth Application to connect to Business Central?
  • What are the different types of authentication available?
Tip

Summary: This chapter provides instructions on how to create an OAuth Application for use with the COSMO Data Integration Framework, including setting up Client Credentials, Password Credentials, Authorization Code, and Implicit permissions, as well as the Redirect URL.

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter OAuth Applications - Data Integration Framework, and then choose the related link.
  2. Choose the New action.
  3. On the OAuth Application Card page, fill in the fields as necessary. Hover over a field to read a short description.

To register an app for a Business Central web service connection

  • How do I register an app for a Business Central web service connection?
  • How do I set application permissions in Business Central?
  • How do I create an OAuth Application to connect to Business Central?
  • What are the different types of OAuth credentials?
Tip

Summary: This chapter provides instructions on how to register an app for a Business Central web service connection using OAuth 2.0. It covers how to create an OAuth application, set application permissions in Business Central, create an OAuth Application to connect to Business Central, and how to set redirect URL. It also explains the different authentication types, such as Client Credentials, Password Credentials, Authorization Code and Implicit. Finally, it provides instructions on how to grant consent to the registered app.

Using OAuth 2.0 to send messages from one company to another requires the creation of an application in Microsoft Azure portal of the target company.

Follow these steps to create an app to establish a connection from an OAuth Application in COSMO Data Integration Framework.

  1. Register an app in Azure portal. For connecting to Business Central, add the endpoint OAuthLanding.htm (for example, https://businesscentral.dynamics.com/[<environment id>/]OAuthLanding.htm). You might set the account type to Multitenant, if the app is shared across different Azure tenants.

  2. For Service to Service (S2S) authentication, create application permissions for Dynamics 365 Business Central and check API.ReadWrite.All. You may also use delegated permissions and check user_impersonation and Financial.ReadWrite.All, if a specific user is used for authentication.

  3. Create a client secret and copy the value for the next steps.

  4. Find the client ID and Azure endpoints. Copy the values for the next steps. The endpoint version defines the used OAuth parameters, such as scope and resource. For Service to Service (S2S) authentication based on client credentials grant type, you will only need the OAuth 2.0 token endpoint (v2). For other grant types, you might also need the OAuth 2.0 authorization endpoint (v2).

  5. Using administrator rights, grant consent to the registered app (API permissions > Grant admin consent for ). You can also grant permissions from inside Business Central, but it's not recommended due to possible authentication errors.

To set application permissions in Business Central

Tip

Summary: This chapter explains how to create an OAuth application, register an app for a Business Central web service connection, and set application permissions in Business Central. The steps to create an OAuth application include setting up Client Credentials, Password Credentials, Authorization Code and Implicit, as well as setting up a Redirect URL. To set application permissions in Business Central, the previously created application needs permissions defined in Business Central, which can be done by entering the client ID, description, and setting the desired permissions.

For Service to Service (S2S) authentication, the previously created application needs permissions defined in Business Central.

  1. Choose the Lightbulb that opens the Tell Me feature icon, enter Azure Active Directory Applications, and then choose the related link.

  2. Enter the client ID from the steps before and a description. The description will be used as User Name. Select State = Enabled and confirm the dialog. Then choose Grant Consent and accept the next dialog. If the Azure app has not already been granted consent in the Azure portal, an additional dialog might appear. The Azure application is now represented by a new user inside Business Central.

  3. Scroll down the Azure Active Directory Applications page and set the desired permissions for the Azure application. The permission set SUPER must not be used. In this example, we use the D365 FULL ACCESS user group with sufficient permissions to transmit data into the Data Integration Framework app.

To create an OAuth Application to connect to Business Central

  • What are the different types of authentication available with an OAuth Application?
  • What is the Scope field used for?
  • What is the Grant Type field used for?
  • What is the Request Access Token action used for?
  • What is the Clear Tokens action used for?
  • What is the Initialize for Business Central (SaaS) action used for?
  • What is the Resource field used for?
  • What is the Client ID field used for?
  • What is the Client Secret field used for?
  • What is the Access Token URL field used for?
  • What is the Username field used for?
  • What is the Password field used for?
  • What is the Redirect URL field used for?
  • What is the Show Current Token action used for?
Tip

Summary: This chapter provides instructions for creating an OAuth Application to connect to Business Central. It covers how to initialize the application for Business Central SaaS, set the application permissions in Business Central, and create an OAuth Application using different authentication types including Client Credentials, Password Credentials, Authorization Code, and Implicit. It also explains the importance of the Redirect URL field.

Create an OAuth Application in the sender company to authenticate on the target company. The values are based on a SaaS target environment.

  1. Go to Business Central and create a new OAuth Application. Enter a Code, a Description, and choose Type = OAuth 2.0.
  2. Choose the Initialize for Business Central (SaaS) action to initialize some of the values based on the current environment.
  3. Enter the values from the previous steps in the Client ID, Client Secret and Access Token URL fields. For authentication types other than Service to Service, additional values are required.
  4. The Scope field must be https://api.businesscentral.dynamics.com/.default to address Business Central.
  5. The Grant Type field must be Client Credentials for Service to Service authentication.
  6. Choose the Request Access Token action to test the authentication. Depending on the Grant Type field, a consent dialog might pop up to log in with user credentials. The Status should be Connected.
  7. Optional: Choose the Clear Tokens action to remove the cached tokens. If you don't clear the token, the next authentication attempt will use the refresh token to create a new access token, similar to the Refresh Access Token action.

Tip

Select the Initialize for Business Central (SaaS) action to initialize some of the values based on the current environment. Be aware that these are the values for the sender company only. Choose the action on the target company and copy the values or change them respectively.

Tip

For v1 endpoints, the Resource field must be https://api.businesscentral.dynamics.com.

Tip

If you choose other grant types than Client Credentials, the Username, Password or Redirect URL fields must be set respectively to the type.

Tip

In sandbox environments, the Show Current Token action can be used to verify the audience and scope of the received token. For example, use https://jwt.io/ to decode the token and find detailed information.

Client Credentials

Choosing the Grant Type = Client Credentials will only use the Client ID, Client Secret, Scope and Resource for authentication. This type is best practice for an easy Service to Service connection with Business Central in SaaS.

Password Credentials

Choosing the Grant Type = Password Credentials requires to set the Username and Password fields of the user to be used for authentication in the target company. This is typically a service user. The password credential flow does not pop up a consent dialog every time, but is linked to a user. It can be used for user-based authentication.

Authorization Code

The Grant Type = Authorization Code requires you to set the Redirect URL field.

The authorization code flow may pop up a consent dialog for the user to log in with their credentials. UI dialogs are not allowed for background or automated tasks. This option should be used if Partner Mapping execution requires a user delegated authorization in the target company.

Implicit

The Grand Type = Implicit requires the Client ID but no Client Secret. Further, the Access Token URL field can be skipped, as the token will be retrieved from directly from the Authorization URL through a consent dialog. UI dialogs are not allowed for background or automated tasks. The Redirect URL field must be configured.

This option should be used if Partner Mapping execution requires a new login for each execution. The implicit flow does not have a refresh token and requires login for each request.

Redirect URL

  • What is the endpoint for handling OAuth callbacks?
  • How do I register an application for a Business Central web service connection?
  • How do I set application permissions in Business Central?
  • How do I create an OAuth Application to connect to Business Central?
  • What are the different types of OAuth credentials?
  • What is the redirect URL?
Tip

Summary: This chapter provides instructions on how to create and register an OAuth application in Business Central, as well as how to set permissions and create an OAuth application to connect to Business Central. It also provides an overview of the Redirect URL endpoint that must be entered in the OAuth application and registered app in Azure portal.

Business Central offers a fixed endpoint to handle OAuth callbacks. This endpoint must be entered correctly in both the redirect URL of the OAuth Application and the registered app in Azure portal. The URL is defined as https://<server name>[:<port>]/[<aad tenant id>/][<environment name>/]OAuthLanding.htm. An example for a SaaS environment is https://businesscentral.dynamics.com/e1894b46-5483-4e16-a0c6-0d039b12b488/Production/OAuthLanding.htm.

Note

Using the http protocol for local environments can be difficult because Azure portal only allows http://localhost for unsecure connections. To connect from a local docker container, use an IIS and redirect the http://localhost:<your-port> calls by <httpRedirect enabled="true" destination="http://<your docker container>/bc/OAuthLanding.htm$Q" /> setting in your web.config to your docker container.

Feedback

Submit feedback for this page .