Skip to content

Configuring an App Registration in Azure

The following steps need to be completed to create an App Registration in DMS by Simova. An App Registration is required by DMS, to be able to use all of the features that are available in DMS.

Info

To perform this setup, it is necessary for the administrator account to be present in both Business Central and Azure Portal as only administrators have the necessary privileges.

Business Central (SaaS)

An App Registration Wizard is available in DMS by Simova to configure an App Registration in DMS. The App Registration Wizard will guide you to create a new App Registration for DMS or using an existing App Registration. The following steps to configure the App Registration in DMS for Business Central in SaaS environment.

  1. Navigate to DMS - Module Setup.
  2. Click on the Configure App Registration action in the DMS - Module Setup to proceed.
  3. Click on Begin to start the configuration of the App Registration.
  4. Choose either to Create a new App Registration or to Use an existing App Registration.

Create New App Registration

The following steps will guide you on how to create a new App Registration for DMS through the App Registration Wizard.

  1. If a pop-up to sign in appears, make sure to sign in with an administrator account in both DMS and Azure to continue with the creation of the App Registration.
  2. Enter a name for the App Registration in the App Registration Name field.
  3. Clicking on Next will start the creation process of the App Registration in Azure. This process will create all the necessary permissions and credentials to be used by DMS.
  4. A pop-up will appear to create a new user in the Azure Active Directory Application. CLick on Yes to continue with the creation of the App Registration.
  5. You will be navigated to the Azure Active Directory Application page where you can click on the Grant Consent action button to provide administrator consent and permissions in Azure. If a pop-up appears. Make sure to sign in with an administrator account in both DMS and Azure.
  6. Close the Azure Active Directory Application page, and the App Registration Wizard will be automatically navigated to the next step.
  7. The Client Secret of the App Registration will be shown only once. Please take a note of the Client Secret. You will not be able to go back to this step once you click on Next.
  8. Click on Next to continue.
  9. The configuration of the App Registration is now complete. Click on Finish to close the App Registration Wizard.

Use Existing App Registration

The following steps will guide you on how to use an existing App Registration for DMS through the App Registration Wizard.

  1. If a pop-up to sign in appears, make sure to sign in with an administrator account in both DMS and Azure to continue with the creation of the App Registration.
  2. Enter the App Registration Name of the App Registration you want to use in the App Registration Name field or use the lookup function to look for all existing App Registrations in your Azure tenant.

Using the lookup to enter the App Registration data automatically

  1. Choose an App Registration via the lookup, the wizard will automatically fill all of the necessary fields in the App Registration Wizard, except for the Client Secret.
  2. Enter the Client Secret of the selected App Registration in the Client Secret field. If the Client Secret is correct, the Next button will be enabled to proceed with the configuration of the App Registration.

Entering the App Registration data manually

  1. Enter the App Registration Name of the App Registration you want to use in the App Registration Name field.
  2. Enter the Application (client) ID of the App Registration you want to use in the Client ID field.
  3. Enter the Client Secret of the App Registration you want to use in the Client Secret field.
  4. Enter the Directory (tenant) ID of the App Registration you want to use in the Tenant ID field.
  5. Enter the Redirect URL of the App Registration you want to use in the Redirect URL field. In SaaS environment, the Redirect URL should be https://businesscentral.dynamics.com/OAuthLanding.htm.
  6. Enter the Service Principal ID of the App Registration you want to use in the Service Principal ID field.
  7. Click on Next to proceed with the configuration. If the Next button is disabled, make sure that all of the fields are filled in correctly.

Info

To get the Service Principal ID the following steps can be followed :

  1. In the Azure Portal, navigate to Enterprise applications.
  2. Change the filter to Application type == All Applications.
  3. Search for the App Registration you want to use.
  4. Click on the App Registration to open the App Registration page.
  5. Copy the Object ID from the Overview page. The Object ID is the Service Principal ID.

Certificate

DMS by Simova has the possibility to authenticate to SharePoint, by allowing the App Registration to use a certificate to authenticate to Sharepoint. If the selected App Registration does not have a certificate configured in Azure, a page will be shown to ask if you want to create a certificate for the selected App Registration. This is an optional step, and can be skipped by clicking on Next, however DMS cannot authenticate to SharePoint with an App Context without a certificate.

By using a certificate, DMS can work with the SharePoint without the need to impersonate the user. This also avoids the problem of the token expiring, which can happen when working with a user context.

To create a certificate for the selected App Registration, the following steps can be done :

  1. Turn on the Create a new certificate to create a certificate for the selected App Registration. By turning this option on, a certificate for DMS will be created in this App Registration at the end of the configuration.
  2. Click on Next to proceed with the configuration.

Warning

Existing App Registration will be overwritten upon finishing the App Registration Wizard.

Renewing an App Registration credentials

The Client Secret and Certificate credentials have an expiration date. The credentials can be renewed automatically without the need for the administrator to go to the Azure Portal by using the action Renew Secret/Certificate. The following steps will guide you on how to renew the credentials of an App Registration.

  1. Navigate to the DMS - Module Setup.
  2. Click on the Renew Secret/Certificate to start the renewal process.
  3. Once the renewal process is finished, a message will be shown to inform the user that the renewal process is successful, and the new Client Secret will be shown once. An administrator can take a note of the new Client Secret for future use.
  4. Click on OK to close the message, and the new Client Secret and Certificate will be saved and used by DMS automatically.

Info

The new Client Secret and Certificate will be automatically applied to the other companies in Business Central, when the company shares the same App Registration data.

Business Central (On-Premise)

Creating the App Registration automatically from Business Central On-Premise is not feasible. Therefore, the creation of the App Registration needs to be done manually through the Azure Portal.

Creating the Azure App Registration in Azure Portal

The following steps will guide you on how to create a new App Registration for DMS in Azure Portal.

  1. Log in to the Azure Portal at Azure Portal.
  2. Click on the Azure Active Directory icon in the left-hand navigation menu.
  3. In the Azure Active Directory menu, click on App Registrations.
  4. Click the New registration button.
  5. Enter the name DMS by Simova in the Name field.
  6. Choose the appropriate Supported account types option for the app registration.
  7. Enter the appropriate Redirect URI for your app registration. This is the URI that Azure AD will redirect the user to after authentication. The URI should be set to Web for the platform and written in the following format https://**external Business Central address/BC/OAuthLanding.htm**.
  8. Click the Register button to create the app registration.
  9. On the app registration page, note the Application (client) ID and Directory (tenant) ID. This is the unique identifier for your app registration that you will need to use when configuring your DMS by Simova in Business Central.
  10. Under the Certificates & secrets tab, click New client secret to create a new secret that will be used to authenticate your app with Azure AD.
  11. Enter a description for the secret, select an expiration date, and click Add.
  12. Note the generated secret value, as it will only be displayed once and cannot be retrieved later. Please take a note of the secret value as it is needed to configure DMS by Simova in Business Central.

  13. Under the API permissions tab, click Add a permission and add the following permissions.

    Permission group API / Permission name Type Description
    Azure Service Management user_impersonation Delegated Access Azure Service Management as organization users
    Microsoft Graph offline_access Delegated Maintain access to data you have given it access to
    Microsoft Graph User.Read Delegated Sign in and read user profile
    Microsoft Graph User.Read.All Application Read all users' profiles
    Microsoft Graph Sites.ReadWrite.All Application Read and write items in all site collections
    Microsoft Graph GroupMember.ReadWrite.All Application Read and write all group memberships
    SharePoint AllSites.FullControl Delegated Have full control of all site collections
    SharePoint AllSites.Read Delegated Read items in all site collections
    SharePoint Sites.FullControl.All Delegated Have full control of all site collections
    SharePoint Sites.ReadWrite.All Delegated Read and write items in all site collections

  14. Click the Grant admin consent button to grant the permission an admin consent.

Creating Certificate

Creating a Client Certificate allows DMS to authenticate to SharePoint without the need to impersonate the user. This also avoids the problem of the token expiring, which can happen when working with a user context. The use of a Client Certificate is optional. However, if you want to use a Client Certificate to authenticate to SharePoint, the following steps will guide you on how to create a Client Certificate for DMS.

  1. Navigate to Ceritificates and follow the steps to create a Client Certificate. The .pfx file and the .cer files are needed. Please take a note of the password of the .pfx file as it is needed to configure DMS by Simova in Business Central.
  2. Navigate to the created Azure App Registration for DMS.
  3. Under the Certificates & secrets tab, click Certificates tab.
  4. Click on Upload certificate then upload the .cer file and write a description.
  5. Click on Add to save the certificate.
  6. The pfx file will be uploaded in the DMS by Simova configuration.

Adding role to a Subscription

Assigning DMS by Simova app a role in a subcription is necessary to enable them to create and configure a storage account for Azure Blob Storage. However, if Azure Blob Storage is not utilized in DMS by Simova in the subcription, this step can be skipped.

Info

The role assignment could only be done by an administrator account.

  1. Log in to the Azure Portal at Azure Portal.
  2. Search for Subscriptions using the search bar.
  3. If you have multiple subscriptions, select the one intended for Azure Blob Storage since a storage account must have a subscription.
  4. Go to the Access control (IAM) tab and click on the Role assignment tab.
  5. Click Add button and select Add role assignment.
  6. Under the Role tab, choose the Contributor role and click Next.
  7. Click the Select members button under the Members tab, then add DMS by Simova.
  8. Click on Review + assign to complete the role assignment process.

Entering the Azure App Registration information in Business Central

The following steps will guide you on how to configure the App Registration for DMS through the App Registration Wizard.

  1. Navigate to DMS - Module Setup.
  2. Click on the Configure App Registration action in the DMS - Module Setup to proceed.
  3. An App Registration Wizard will appear. Click on Begin to start the configuration.
  4. To continue this step, it is necessary to already have an App Registration prepared for DMS. If you have not created an App Registration for DMS, please refer to the Creating the Azure App Registration in Azure Portal section.
  5. Fill the App Registration Name, Client ID, Client Secret, Tenant ID, and Redirect URL fields.
  6. Once all fields are filled correctly, click on Next to proceed with the configuration.
  7. The Client Certificate configuration page will be shown, this step is optional, and can be skipped by clicking on Next and skip to step 10. However, if you want to use a Client Certificate to authenticate to SharePoint, a Certificate needs to be prepared.
  8. Click on the Certificate Key field to open a pop-up which allows you to select the .pfx file that was created in the Creating Certificate step.
  9. Enter the password of the .pfx file in the Certificate Key Password field, and click on Next to proceed with the configuration.
  10. Upon clicking Finish the changes will be applied to the App Registration settings in DMS.

Warning

  • If the App Registration is not configured correctly, the DMS by Simova will not be able to function properly in some area.
  • Existing App Registration will be overwritten upon finishing the App Registration Wizard.