Configure Microsoft Entra authentication with OpenID Connect

APPLIES TO: Business Central 2022 release wave 1 and later

This article explains how to configure Business Central to use Microsoft Entra ID to authenticate users. This setup configures Microsoft Entra authentication to use OpenID connect.

Preparation

• Obtain and set up security certificates on the Business Central deployment

  Microsoft Entra authentication requires the use of service certificates to help secure client connections over a wide area network (WAN). In a production environment, you should obtain a certificate from a certification authority or trusted provider. In a test environment, if you don't have a certificate, then you can create your own self-signed certificate. The implementation of certificates involves installation and configuration of the certificates on the Business Central Server server and client computers.

  Follow the instructions for obtaining and installing the certificates Using Certificates to Secure Connections. However, for now, don't change the credential type used by Business Central Server and Business Central Web Server yet. You'll change it later in this article.

Task 1: Create a Microsoft Entra tenant

To get started, you need a Microsoft Entra tenant. The Microsoft Entra tenant is where you manage user accounts and register apps, like Business Central.

There are a couple ways to get a Microsoft Entra tenant:

• Sign up a Microsoft 365 plan

  If you have a Microsoft 365 subscription that is based on a domain such as solutions.onmicrosoft.com, then you're already using Microsoft Entra ID. The Microsoft 365 user accounts are based on Microsoft Entra ID. So, there's nothing more to do in this task.

  If you want to sign up for a Microsoft 365 plan, you can use a plan such as Microsoft 365 Enterprise E1 as your test site, or sign up for a trial developer plan. A trial plan includes an administrative account that you'll use to access the Azure management portal. If your Microsoft 365 site is solutions.onmicrosoft.com, for example, your administrative account can be [email protected]. For more information, see Select a Microsoft 365 plan for business.

• Sign up for an Azure subscription that isn't associated with a Microsoft 365 subscription and create your own Microsoft Entra tenant. For more information, see the next section.

Create your own Microsoft Entra tenants

If you have a Business Central on-premises deployment configured for multitenancy, you can choose to use the same Microsoft Entra tenant for all Business Central tenants. Or you can create a separate Microsoft Entra tenant for each Business Central tenant.

1. Sign up for an Azure subscription at https://azure.microsoft.com.

2. Sign in to Azure portal.

3. Create a directory by following the instructions at How to get a Microsoft Entra tenant.

   This step will create a Microsoft Entra tenant. When you create a Microsoft Entra ID in the Azure portal, you specify an initial domain name that identifies your Microsoft Entra tenant, such as solutions.onmicrosoft.com or cronusinternationltd.onmicrosoft.com. You'll use the domain name when you add users to your Microsoft Entra ID and when you configure the Business Central Server instance. In the tasks that follow, this value is referred to as the Microsoft Entra tenant ID.

4. After you've created the Microsoft Entra tenant, add users.

   For more information, see Quickstart: Add new users to Microsoft Entra ID. Later, you'll have to map the users in Microsoft Entra ID to your users in Business Central.

Task 2: Register an application in the Microsoft Entra tenant

In this task, you register your Business Central solution as an application in the Microsoft Entra tenant.

1. Sign in to Azure portal and open the Microsoft Entra tenant.

2. To register the application, follow the guidelines at Registering Business Central On-Premises in Microsoft Entra ID for Integrating with Other Services.

   When you add an application to a Microsoft Entra tenant, you specify the following information. The configuration is slightly different in for Business Central single-tenant and multitenant deployment.

   • Single-tenant
   • Multitenant-tenant

   Setting	Description
   Name	Specifies the name of your application as it will display to your users, such as Business Central App by My Solutions.
   Supported account types	Select Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant)
   Redirect URI	Specifies the type of application that you're registering and the redirect URI (or reply URL) for your application. Set the type to Web, and in the redirect URL box, enter URL for signing in to the Business Central Web client, for example https://localhost:443/240/SignIn. The URI has the format https://<domain or computer name>/<webserver-instance>/SignIn, such as https://cronusinternationltd.onmicrosoft.com/240/SignIn or https://MyBcWebServer/240/SignIn. Important The portion of the reply URL after the domain name (in this case 240/SignIn) is case-sensitive, so make sure that the web server instance name matches the case of the web server instance name as it is defined on IIS for your Business Central Web Server installation.

3. Set up ID tokens for implicit grant and hybrid flows:

   1. Select Authentication.
   2. Under Implicit grant and hybrid flows, select ID tokens (used for implicit and hybrid flows).
   3. Select Save.

4. The Business Central solution is now registered in your Microsoft Entra tenant. To complete the steps that follow, you'll need the following information:

   • Tenant's domain (Directory (tenant) ID)
   • Redirect URI
   • Application (client) ID

   You can view the settings in the Azure portal by selecting Overview for the registered application. So, make a note of or copy the values for these settings for later use.

Task 3: Associate Microsoft Entra ID Users with Business Central Users

Each user in your Microsoft Entra tenant that will access Business Central must be set up with an account in Business Central.

You can postpone this task for most users and do it after you complete Microsoft Entra ID setup. But you must do this task now for your Business Central user account. If you don't, you won't be able to sign in to Business Central after you switch to Microsoft Entra ID.

To associate a Business Central user with Microsoft Entra ID, set the user's authentication email in Business Central to the user's principal name in Microsoft Entra ID, like [email protected].

1. In the Azure portal, get the Microsoft Entra ID user's principal name.

   For more information, see Users in Microsoft Entra ID in the Azure help.

2. Assign the Azure user principal name to the Business Central user. You can use the web client or Business Central Administration Shell.

For more information, see Create Users According to Licenses.

Task 4: Configure Business Central Server

Once you have the Microsoft Entra tenant and a registered application for Business Central, you configure the Business Central Server instance for Microsoft Entra authentication.

1. Run Business Central Administration Shell as an administrator.

   To configure the server instance in the next steps, you'll use the Set-NAVServerConfiguration cmdlet.

2. Set the ClientServicesCredentialType to AccessControlService.

   Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName  -KeyName ClientServicesCredentialType -KeyValue AccessControlService
   

3. Configure the Microsoft Entra ID settings.

   This step is different for a single-tenant and multitenant Business Central Server deployments.

   1. Set the ValidAudiences parameter to the Application (client) ID of the registered application in Microsoft Entra ID. If you'll be using service-to-service (S2S) authentication for Business Central APIs, include https://api.businesscentral.dynamics.com in the value.

      The value has the following format:

      Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName  -KeyName ValidAudiences -KeyValue "<application ID>;https://api.businesscentral.dynamics.com"
      

      Example

      Set-NAVServerConfiguration -ServerInstance 240 -KeyName ValidAudiences -KeyValue "44445555-eeee-6666-ffff-7777aaaa8888;https://api.businesscentral.dynamics.com"
      

   2. Set the ADOpenIdMetadataLocation parameter for version 22 and later or ClientServicesFederationMetadataLocation parameter for version 21 and earlier.

      The value has the following format:

      Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName  -KeyName ADOpenIdMetadataLocation -KeyValue "https://login.microsoftonline.com/{AADTENANTID}/.well-known/openid-configuration"
      

      or

      Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName  -KeyName ClientServicesFederationMetadataLocation -KeyValue "https://login.microsoftonline.com/<AAD TENANT ID>/FederationMetadata/2007-06/FederationMetadata.xml"
      

      • Single-tenant
      • Multitenant-tenant

      Replace <AAD TENANT ID> with the ID of the Microsoft Entra tenant ID or its domain, for example, aaaabbbb-0000-cccc-1111-dddd2222eeee or CRONUSInternationLtd.onmicrosoft.com.

      For example:

      Set-NAVServerConfiguration -ServerInstance 240 -KeyName ADOpenIdMetadataLocation -KeyValue "https://login.microsoftonline.com/cronusinternationltd.onmicrosoft.com/.well-known/openid-configuration"
      

      or

      Set-NAVServerConfiguration -ServerInstance BC240 -KeyName ClientServicesFederationMetadataLocation -KeyValue "https://login.microsoftonline.com/cronusinternationltd.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml"
      

      Important

      The AzureActiveDirectoryClientSecret, AzureActiveDirectoryClientId, and AzureActiveDirectoryClientSecret parameters aren't used. The AzureActiveDirectoryClientId must be empty or set to 00000000-0000-0000-0000-000000000000. If not, you'll get the following error when you try to sign in to Business Central: The value for the WSFederationLoginEndpoint configuration settings cannot be empty.

   3. If you'll be setting up the Business Central add-in for Excel, set the WSFederationLoginEndpoint parameter.

      The WS-federation login endpoint is the URL of the sign-on page that Business Central redirects to when users sign in from a client. Specify a URL in the following format:

      https://login.microsoftonline.com/<AAD TENANT ID>/wsfed?wa=wsignin1.0%26wtrealm=<Application ID URI>%26wreply=<Redirect URL>
      

      Parameter	Description
      <AAD TENANT ID>	The ID of the Microsoft Entra tenant ID or its domain, like aaaabbbb-0000-cccc-1111-dddd2222eeee or CRONUSInternationLtd.onmicrosoft.com.
      <Application ID URI>	The ID that was assigned to the Business Central application when it was registered in Microsoft Entra ID, for example api://44445555-eeee-6666-ffff-7777aaaa8888 or https://cronusinternationltd.onmicrosoft.com/businesscentral.
      <Redirect URL>	The redirect URL that was assigned to the Business Central application when it was registered in the Microsoft Entra tenant. This parameter must point to the SignIn page of the Business Central Web client. Make sure it exactly matches the Redirect URL that was configured on the application in Microsoft Entra ID.

      Important

      The string parameter must be URI-encoded. This means, for example, use "%26" instead of "&".

      Example

      Set-NAVServerConfiguration -ServerInstance BC240 -KeyName WSFederationLoginEndpoint -KeyValue "https://login.microsoftonline.com/cronusinternationltd.onmicrosoft.com/wsfed?wa=wsignin1.0%26wtrealm=https://cronusinternationltd.onmicrosoft.com/businesscentral%26wreply=https://cronusinternationltd.onmicrosoft.com/BC240/SignIn"
      

4. To configure SOAP and OData web services for Microsoft Entra authentication, specify the App ID URI that is registered for Business Central in the Microsoft Entra ID.

   Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName  -KeyName AppIdUri -KeyValue "<Application ID URI>"
   

   The value is typically the same as the wtrealm parameter value of the WSFederationLoginEndpoint parameter.

   Example

   Set-NAVServerConfiguration -ServerInstance BC240  -KeyName AppIdUri -KeyValue "https://cronusinternationltd.onmicrosoft.com"
   

5. Restart the server instance. For example:

   Restart-NAVServerInstance -ServerInstance BC240
   

Task 5: Configure Business Central Web Server components

1. Set the ClientServicesCredentialType key to AccessControlService.

   Set-NAVWebServerInstanceConfiguration -WebServerInstance $BCServerInstanceName -KeyName ClientServicesCredentialType -KeyValue AccessControlService
   

   For example:

   Set-NAVWebServerInstanceConfiguration -WebServerInstance BC240 -KeyName ClientServicesCredentialType -KeyValue "AccessControlService"
   

2. Set the AadApplicationId key to the application (client) ID of the registered application for Business Central in Microsoft Entra ID.

   Set-NAVWebServerInstanceConfiguration -WebServerInstance $BCServerInstanceName -KeyName AadApplicationId -KeyValue $AADApplicationId
   

   For example:

   Set-NAVWebServerInstanceConfiguration -WebServerInstance $BCServerInstanceName -KeyName AadApplicationId "44445555-eeee-6666-ffff-7777aaaa8888"
   

3. Set the AadAuthorityUri key.

   Set-NAVWebServerInstanceConfiguration -WebServerInstance $BCServerInstanceName -KeyName AadAuthorityUri -KeyValue "https://login.microsoftonline.com/<AzureADTenantID>"
   

   • Single-tenant
   • Multitenant-tenant

   Replace <AAD TENANT ID> with the ID of the Microsoft Entra tenant ID or its domain, for example, aaaabbbb-0000-cccc-1111-dddd2222eeee or CRONUSInternationLtd.onmicrosoft.com.

   For example:

   Set-NAVWebServerInstanceConfiguration -WebServerInstance $BCServerInstanceName -KeyName AadAuthorityUri -KeyValue "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee"
   

For more information, see Configure Configuring Business Central Web Server Instances and Configure Authentication.

Task 7: Mount tenants (multitenant only)

If you have a multitenant Business Central environment, mount the tenant databases on the Business Central Server.

Mount your tenants by using the Mount-NAVTenant cmdlet.

• If you'll be using the same Microsoft Entra tenant for all Business Central tenants, you can omit the -AadTenantId parameter.
• If you'll be using different Microsoft Entra tenants, set the -AadTenantId parameter to the ID or domain name of the Microsoft Entra tenant that you want to use for the tenant.
• Also, if you've set up different host names that you want to use accessing the tenant, use the -AlternateId parameter. See Using alternate tenant IDs.

For example:

Mount-NAVTenant -ServerInstance BC240  -Tenant Tenant1 –DatabaseServer ..\BCDEMO -DatabaseName "BC Demo Database" -AadTenantId 1111-aaaa-2222-bbbb-333333333333

Task 8: Set up other users and web service accounts

User accounts

Set up remaining Business Central user accounts, which you didn't cover in Task 3, with Microsoft Entra authentication email accounts.

Web service accounts

With Microsoft Entra authentication, Business Central supports two different methods for authenticating users trying to access data through OData and SOAP web services: web service access keys (or Basic authentication) and OAuth.

With Basic authentication, the Business Central user account must have web service access key. To sign in, instead of using their Microsoft Entra ID password, users provide the Business Central the web service access key. For information about setting up web service access keys, see How to use an Access Key for SOAP and OData Web Service Authentication.

With OAuth, users are authenticated based on their Microsoft Entra ID credentials, providing a more direct and single sign-on experience. See Using OAuth to Authorize Business Central Web Services (OData and SOAP).

More Security and configuration tips

Set the access token lifetime

Follow the steps outlined below.

1. Download the latest Microsoft Entra ID PowerShell Module Public Preview release.
2. Run the following command to sign in to your Microsoft Entra admin account: Connect-AzureAD -Confirm
3. Sign in as the tenant admin.
4. Run the Get-AzureADPolicy command.
5. For each Id that is the result of above command, run Remove-AzureADPolicy -Id {Guid}.
6. Set the token lifetime to 10 minutes by running the following command: New-AzureADPolicy -Definition @('{"TokenLifetimePolicy":{"Version":1, "AccessTokenLifetime":"0.00:10:00"}}') -DisplayName "OrganizationDefaultPolicyScenario" -IsOrganizationDefault $true -Type "TokenLifetimePolicy".

For reference, see the prerequisites section in the following article: Configurable token lifetimes in Microsoft Entra ID.

Increase the ExtendedSecurityTokenLifetime parameter value on Business Central Server

This parameter defines the interval of time that a client session can remain inactive before the session is dropped. If the value is too low, users may experience the error: Connection is not longer available or was lost. The event log will include the error: The SAML2 token is not valid because its validity period has ended. for the server instance. Increasing this value will resolve this issue. We recommend that you set it to a value greater than 8 hours.

Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName  -KeyName ExtendedSecurityTokenLifetime -KeyValue "<hours>"

Example

Set-NAVServerConfiguration -ServerInstance BC240  -KeyName ExtendedSecurityTokenLifetime -KeyValue "20"

Using host names for tenants

You can configure host name tenant resolution, where each tenant is assigned a unique domain, like customer1.cronusinternational.com. Customers would then access their tenant by using https://customer1.cronusinternational.com/240.

This setup implies that the public URL is different for each tenant. To support this scenario, you set Business Central Server to calculate the host dynamically. In the WSFederationLoginEndpoint parameter, use the {HOSTNAME} placeholder in the wreply, for example:

https://login.microsoftonline.com/<AAD TENANT ID>/wsfed?wa=wsignin1.0%26wtrealm=<APP ID URI>%26wreply=https://{HOSTNAME}/240/SignIn

Using alternate tenant IDs

When you mount a tenant, you can give the tenant an additional ID by setting the -AlternateId parameter. Users can then access the tenant using this ID as well as the original. The alternate ID is useful if you have different host names for tenants. In this case, you have to set up URL rewriting in the web.config file for the Business Central Web Server. For more information, see Configuring Business Central Web Server to Accept Host Names for Tenants.

Using Visual Studio Code

If you're connecting to your solution from Visual Studio Code, then you must also specify the Business Central server config parameter ValidAudiences and set it to https://api.businesscentral.dynamics.com. If you don't do this step, you'll get the error securitytokeninvalidaudienceexception in the application log when trying to download symbols.

Give users guidance about single sign-on

Single sign-on means that users are still signed in to Microsoft Entra ID when they sign out from Business Central, unless they close all browser windows. However, if a user selected the Keep me signed in field when they signed in, they're still signed in when they close the browser window. To fully sign out from Microsoft Entra ID, the user must sign out from each application that uses Microsoft Entra ID, including Business Central and SharePoint.

We recommend that you provide guidance to your users for signing out of their account when they're done. Doing so will help you keep your Business Central deployment more secure.

Related information

Authentication and Credential Types
Troubleshooting: SAML2 token errors with Microsoft Entra ID/Office 365 Authentication
Migrating to Multitenancy