Edit

Configure Azure Active Directory Authentication with WS-Federation

  • Article
  • 23 minutes to read

APPLIES TO: Business Central 2021 release wave 2 (version 19) and earlier

The article describes the tasks involved in setting up Azure AD authentication for authenticating Business Central users. The configuration in this article sets up Azure AD authentication to use the WS-Federation protocol.

Important

Azure AD authentication with WS-Federation has been deprecated in later Business Central releases and replaced with OpenID Connect. For more information, see Moving from WS-Federation to OpenID Connect. But if you're running Business Central 2022 release wave 1 (version), you have the option to WS-Federation.

Preparation

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

    Azure AD 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.

  • Upcoming releases of some browsers, such as Google Chrome 80 and Microsoft Edge, will include changes to how cookies are handled.

    To ensure Azure AD authentication works with these browser versions, make sure that the Business Central platform has been upgraded to a recommended update. For more information, see Preparing Dynamics NAV or Dynamics 365 Business Central for Upcoming Changes to Browser Cookie Policy.

Task 1: Create an Azure AD Tenant

To get started, you need an Azure AD tenant. The Azure AD tenant is where you manage user accounts and register apps, like Business Central.

There are a couple ways to get an Azure AD 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 Azure AD. The Microsoft 365 user accounts are based on Azure AD. 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 admin@solutions.onmicrosoft.com. 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 Azure AD tenant. For more information, see the next section.

Create your own Azure AD tenants

If you have a Business Central on-premises deployment configured for multitenancy, you can choose to use the same Azure AD tenant for all Business Central tenants or you can create a separate Azure AD 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 an Azure Active Directory tenant.

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

  4. After you've created the Azure AD tenant, add users.

    For more information, see Quickstart: Add new users to Azure Active Directory. Later, you'll have to map the users in Azure AD to your users in Business Central.

Set the access token lifetime

Important

For security reasons, we recommend that you limit the lifetime of the access token to 10 minutes as described in this section.

Follow the steps outlined below.

  1. Download the latest Azure AD PowerShell Module Public Preview release.
  2. Run the following command to sign in to your Azure AD 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 Azure Active Directory.

Task 2: Register an application for Business Central in Azure AD Tenant

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

Tip

If you're configuring a multitenant deployment, where each tenant will use a different Azure Tenant, you only register an application on one of the Azure AD tenants. Then, you'll make the application available to the other Azure AD tenants by making it a Multitenant application.

Note

If you're registering an application so that you can use the email capabilities in Business Central, you must use a multitenant configuration.

  1. Sign in to Azure portal and open the Active Directory tenant.

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

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

    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 Azure AD 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/BC190/SignIn.

    The URI has the format https://<domain or computer name>/<webserver-instance>/SignIn, such as https://cronusinternationltd.onmicrosoft.com/BC190/SignIn or https://MyBcWebServer/BC190/SignIn.

    Important The portion of the reply URL after the domain name (in this case BC190/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. After you register the application, set the Application ID URI for the application:

    1. From the Overview page for your app registration, next to the Application ID URI label, select Add an Application ID URI.

    2. On the Expose API page, next to the Application ID URI, select Set.

    3. The Application ID URI box displays the default application ID URI.

      It has the format api://<guid>, such as api://70b20a51-46b7-4290-8686-b79ec90379f6. You can keep this value or change it. The application ID URI must be a valid URI starting with HTTPS, API, URN, MS-APPX. It must not end in a slash. To use an HTTPS URI, for example https://cronusinternationltd.onmicrosoft.com/businesscentral, it must be a verified domain.

    4. Select Save when done.

  4. (SharePoint app only) Make Business Central available to Azure AD Tenants

    In the overview page for the application, the URL for Granting Access field contains a URL that you can send to users in other Azure AD tenants. Then, when they choose the link, a page displays where they must agree to trust the application. If they accept, the app is added to their SharePoint site.

  5. The Business Central solution is now registered in your Azure AD tenant. To complete the steps that follow, you'll need the tenant's domain (Directory (tenant) ID), Redirect URI, and Application ID URI.

    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.

Note

The guidelines for the Azure Portal in this article might not reflect the current user interface of the Azure Portal. Please refer to the Azure Portal documentation for the latest instructions.

Task 3: Associate Azure AD Users with Business Central Users

Each user in your Azure AD 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 Azure AD 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 Azure AD.

To associate a Business Central user account with Azure AD, you'll set the user principal name of the user in Azure AD, like chris@contoso.com, as the user's authentication email in Business Central. When you combine this setting with the relevant configuration of the Business Central Server instance, users achieve single sign-on when they access Business Central Web client.

This task can be done from the Business Central Web client or using the Business Central Administration Shell.

  1. Start the Business Central, and open the Users page.
  2. Open the user that you want to modify.
  3. Under Microsoft 365 (Authentication), set the Authentication Email to the user principle name in Azure AD.

For more information about setting up users in Business Central, see Create Users According to Licenses.

Important

Single sign-on means that users are still signed in to Azure AD 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 are still signed in when they close the browser window. To fully sign out from Azure AD, the user must sign out from each application that uses Azure AD, including Business Central and SharePoint.

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

Task 4: Configure Business Central Server

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

You can configure the Business Central Server by using the Business Central Server Administration tool or Business Central Administration Shell.

Important

Starting in Business Central 2022 release wave 2 (v21), the Business Central Server Administration tool is no longer available. Use the Business Central Administration Shell instead.

  1. Open the Business Central Server Administration tool.

  2. In the General tab, set the Credential Type to AccessControlService.

  3. Configure the Azure Active Directory settings.

    This step is different for a single-tenant and multitenant Business Central Server deployments. The settings you set in this step are under the Azure Active Directory tab.

    1. Set the WS-Federation Login Endpoint 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 Azure AD tenant ID or its domain, like 11111111-aaaa-2222-bbbb-333333333333 or CRONUSInternationLtd.onmicrosoft.com.
      <Application ID URI> The ID that was assigned to the Business Central application when it was registered in Azure AD, for example api://44444444-cccc-5555-dddd-666666666666 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 Azure AD 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 Azure AD.

      Important

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

      Example

      https://login.microsoftonline.com/cronusinternationltd.onmicrosoft.com/wsfed?wa=wsignin1.0%26wtrealm=https://cronusinternationltd.onmicrosoft.com/businesscentral%26wreply=https://cronusinternationltd.onmicrosoft.com/BC190/SignIn

    2. Set the WS-Federation Metadata Location parameter.

      The WS-federation metadata location establishes a trust relationship between Business Central and Azure AD. The parameter value has the following format:

      https://login.microsoftonline.com/<AAD TENANT ID>/FederationMetadata/2007-06/FederationMetadata.xml
      Parameter Description
      <AAD TENANT ID> The ID of the Azure AD tenant ID or its domain, for example, 11111111-aaaa-2222-bbbb-333333333333 or CRONUSInternationLtd.onmicrosoft.com. The value is the same as what you used in the WS-federation login endpoint in the previous step.

      Example

      https://login.microsoftonline.com/cronusinternationltd.onmicrosoft.com/FederationMetadata/2007-06/FederationMetadata.xml

    Important

    The Application Client Certificate Thumbprint, Application Client ID, and Application Client Secret parameters aren't used. The Application Client ID 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.

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

    On the Azure Active Directory tab, set the Azure AD App URI. The App ID URI is typically the same as the wtrealm parameter value of the WS-Federation Endpoint setting.

  5. Increase the ExtendedSecurityTokenLifetime parameter value.

    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.

  6. Disable token-signing certificate validation by selecting the Disable Token-Signing Certificate Validation check box.

  7. Restart the server instance.

Task 5: Configure Business Central Web Server components

Configure the Business Central Web Server components to use AccessControlService as the credential type.

  1. Open the navsettings.json for the Business Central Web Server in any text or code editor, such as Notepad or Visual Studio Code.

  2. Set the ClientServicesCredentialType key value to AccessControlService.

    "ClientServicesCredentialType":  "AccessControlService",

  3. If you're setting up Business Central version 20, add the following line:

    "UseLegacyAcsAuthentication":  "true"

    This line is required so that WS-Federation is used instead of OpenID Connect.

  4. Save the navsettings.json file

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

Task 6: Configure Dynamics NAV Client connected to Business Central

DISCONTINUED AFTER: Business Central Spring 2019

Configure the Dynamics NAV Client connected to Business Central to use AccessControlService as the credential type to support Azure AD. Also, configure the ACSUri setting for Azure AD authentication must be set. The value must be that same as the WS-Federation Login Endpoint setting of the Business Central Server instances, except for the <App REPLY URL> parameter. The ACSUri setting has the following format:

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

The <Redirect URL> parameter in the URL must be equal to the sign-in page for the Dynamics NAV Client connected to Business Central, such as https://dynamicsnavwinclient.

For example:

<add key="ACSUri" value="https://login.microsoftonline.com/cronusinternationltd.onmicrosoft.com/wsfed?wa=wsignin1.0%26wtrealm=https://cronusinternationltd.onmicrosoft.com/businesscentral%26wreply=https://dynamicsnavwinclient" />

You configure the Dynamics NAV Client connected to Business Central by modifying the ClientUserSettings.config file.

Task 7: Mount tenants (multitenant only)

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

Use either the Business Central Server Administration tool or Business Central Administration Shell. For more information about mounting tenants, see Mount or Dismount a Tenant on a Business Central Server Instance.

In the navigation pane, use the Tenants node to mount the tenants.

  • If you'll be using the same Azure AD tenant for all Business Central tenants, you can leave Azure AD Tenant ID blank.
  • If you'll be using different Azure AD tenants, set the Azure AD Tenant ID to the ID or domain name of the Azure AD tenant that you want to use for the tenant. For example, 11111111-aaaa-2222-bbbb-333333333333 or CRONUSInternationLtd.onmicrosoft.com.
  • Also, if you've set up different host names that you want to use accessing the tenant, set the Alternate ID. See Using alternate tenant IDs.

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 Azure AD authentication email accounts.

Web service accounts

With Azure AD 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 using their Azure AD 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 Azure AD credentials, providing a more direct and single sign-on experience. For more information, see Using OAuth to Authorize Business Central Web Services (OData and SOAP).

Additional tips

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/BC190.

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}/BC190/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 a 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 are 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 do not do this, you will get the error securitytokeninvalidaudienceexception in the application log when trying to download symbols.

See Also

Authentication and Credential Types
Troubleshooting: SAML2 token errors with Azure Active Directory/Office 365 Authentication
Migrating to Multitenancy