Introduction

    This document describes how to call Business Central APIs by using the OAuth Resource Owner Password Credentials (ROPC) flow. This flow uses the username and password of an Azure Active Directory (AAD) user to access Business Central APIs. The user needs to have access to Business Central. The app that calls the Business Central API needs to be registered in AAD.

    MFA is not supported in this flow!

    User

    The user needs to be set up in AAD and Business Central in the usual way. Make sure to only assign required permissions (not SUPER). If Multifactor Authentication (MFA) is configured in AAD, then make sure to disable it for this user. The ROPC flow does not support MFA.

    The user should have a very strong password, similar to the secret of an Azure AD app. Password should not too soon, preferably it should be valid for at least 1 year to avoid frequent changing the setup.

    App registration

    The application that calls Business Central needs to get its own identity. This is done by registering the app in AAD. The app needs to be registered one time, in the AAD of the owner of the application.

    Follow these steps to register and configure the application in AAD.

    1. Open the Azure Portal http://portal.azure.com
    2. Navigate to Azure Active Directory --> App registrations https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps
    3. Click on New registration
    4. Provide a name for the application, e.g. BC Integration
    5. Under Supported account types select Accounts in any organizational directory
    6. Under Redirect URI choose Web and provide the URL https://businesscentral.dynamics.com/OAuthLanding.htm
    7. Click on the Register button

    image.png

    1. In the Overview page, make a copy of the Application (client) ID

    image.png

    1. Click on Certificates & secrets
    2. Under Client secrets click on New client secret
    3. Choose an expiration period and optionally provide a description.
    4. Make a copy of the secret value. This is the only time you can do this!

    image.png

    1. Click on API permissions
    2. Click on Add a permission, then on Dynamics 365 Business Central
    3. Select Delegated permissions and then select user_impersonation
    4. Click on Add permissions to save this permission

    image.png

    1. Click on Branding
    2. Under Publisher verification, click on Add MPN ID to verify publisher
    3. Provide the MPN ID, select the checkbox to agree to the Microsoft Platform Policies and then click on Verify and save

    The application registration in AAD is now completed.

    Grant consent to the external application

    The external application needs to be given consent to access Business Central on behalf of a user. For this, interaction with a user is required. The user needs to be logged in and the external application needs to ask the user to give consent. If the external application is a background service and has no user interface, then this flow can be completed by constructing the correct URL. It is also possible to use Business Central user interface to grant consent. Both methods will be explained here.

    The procedure of granting consent must be done as a (delegated) admin. It will give consent to the app for any user. The advantage is that the user account itself does not have to be logged and the external application can switch to another user account without the need to grant consent again.

    This process is a very simple process because the URL is known upfront and can be provided in setup documentation. The base URL is https://login.microsoftonline.com/common/adminconsent?client_id={client_id}. Replace {client_id} with the id that was copied in step 8 when registering the app in AAD.

    https://login.microsoftonline.com/common/consent?client_id=e2d2001b-de03-41b7-8cb2-9a08dd1b9136

    After logging in as an admin user, this page will be visible:

    image.png

    Click on Accept to grant consent to the external application. The browser will now redirect the user the URL that has been provided as the redirect URI in step 6. If there is no redirect URI, then an error message will occur, but that has no effect on the consent given. The page can now be closed.

    This method basically does the same as the previous method, but it uses the user interface of Business Central. The steps below describe how to manually create the record, but this can also be done by an install codeunit. The end-user only has to click on Grant Consent. This process will become a standard process in the future, when the service-to-service calls become possible with the client credentials flow.

    Follow these steps to grant consent to the external application with Business Central.

    1. Search for AAD Applications
    2. In the list of AAD Applications, click on New
    3. Enter the client id from step 8 in the format {}
    4. Provide a description
    5. Click on Grant Consent

    image.png

    1. Follow the instructions to log in and give consent. It will be possible to log in with a different user. The consent screen is the same as above.
    2. A confirmation will be displayed when successfully finished.

    image.png

    Get the OAuth access token

    The OAuth access token can be retrieved with just one call, which does not require any user interaction.

    The call is constructed as follows:

    POST https://login.microsoftonline.com/kauffmann.nl/oauth2/v2.0/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=
&client_secret=
&scope=https%3A%2F%2Fapi.businesscentral.dynamics.com%2Fuser_impersonation
&username=
&password=

    client_id = the AAD application id as copied in step 8 and used for the admin consent client_secret = the secret as copied in step 12 username = the full user name created in AAD that has proper permissions in BC password = the password of the user

    This call returns a json body with an access token. The access token expires in 60 minutes, after which a new access token can be retrieved.

    The access token must be used in the Authorization header as a bearer token:

    GET https://api.businesscentral.dynamics.com/v2.0/demo/api/v2.0/companies()/customers
Authorization: Bearer

    It is not required to include the AAD tenant id in the URL, because it is automatically taken from the access token.

    In Postman the access token can be retrieved as follows:

    image.png