Authenticating Users with Active Directory Federation Services
Article
Business Central supports Active Directory Federation Services (AD FS) authentication for authenticating users, without having to use the Access Control Service (ACS). This article walks you through the steps about how to set up AD FS authentication in AD FS Management console, and then how to configure it in Business Central.
Prerequisites
Your deployment must meet the following prerequisites:
Active Directory Federation Services (AD FS) is installed on the computer that you want to prepare as the federation server.
To complete the steps in this article, you will need to know the public URL for AD FS server. This URL needs to be accessible from a web browser on the computer that is running the Business Central Server instance.
Note
The steps in this article are based on using the AD FS version on Windows Server 2016, but should also work with earlier versions of AD FS. Be aware that some dialog box references in the steps might be slightly different in earlier versions of AD FS.
A working Business Central deployment that includes the following components:
Configure AD FS to allow Business Central authentication
These steps are done by using the AD FS Management console on the server where AD FS is running.
Set up a Relying Party Trust for the Business Central clients
You must complete these steps separately for Business Central Web Server for the Web client and Dynamics NAV Client connected to Business Central.
Open Server Manager on the computer that is running AD FS, choose AD FS > Tools > AD FS Management.
Right-click Relying Party Trusts, and then choose Add Relying Party Trust.
The Add Relying Party Trust Wizard appears.
In the Welcome step, choose Claims aware, and then choose Start.
In the Select Data Source step, choose Enter data about the relying party manually, and then choose Next.
In the Specify Display Name step, give the relying party a name, such as Business Central Web Client or Dynamics NAV Windows Client, and then choose Next.
In the Configure Certificate step, choose Next to skip specifying the token encryption certificate.
This assumes that the Business Central Web Server is running https.
In the Configure URL step, select the Enable support for the WS-federation Passive protocol check box.
Then, in Relying party WS-Federation Passive Control URL field, enter the URL for the Business Central client according to the following:
If you are setting up AD FS for the Business Central Web client, set this to the full URL for the Web client. The URL typically has the format:
Replace <webserver-instance> with the instance name of the Business Central Web Server as defined in IIS for your installation. Make sure that the case matches exactly. For example:
https://MyWebServer:443/BC130
or
https://corp.sample.com/BC130
If you are setting up AD FS for the Dynamics NAV Client connected to Business Central, you can use any URL as long as it is in the form of a trusted URL https://<name>, such as https://mynavwinclient or https://www.cronus.com. The URL does not have to point to a valid target, it is only used by AD FS to validate the client. For example, you could just use the domain name of your site:
https://corp.sample.com
Choose Next to continue.
Note
This is the URL to which AD FS will be allowed to issue authentication tokens. The URLs that you specify will be used later on when you configure the Business Central Server and Dynamics NAV Client connected to Business Central.
In the Configure Identifiers step, in the Relying party trust identifier field, remove the Business Central Web client URL , and then add a URL that identifies the client instead. You can use any value as long as it has the for format https:<name>:
For example, if you are setting up AD FS for the Business Central Web client, you could use the following URL:
https://bcwebclient
If you are setting up AD FS for the Dynamics NAV Client connected to Business Central, you could use add the URL:
https://dynamicsnavwinclient
Choose Next to continue.
Important
This is the URL which is used to identify the relying party, and it has to be unique for the AD FS setup. This URL will be used as the wtrealm parameter in the WSFederationLoginEndpoint setting of the Business Central Server instance configuration (CustomSettings.config file).
In the Choose Access Control Policy step, setup multi-factor authentication if required, and then choose Next.
Review the configuration, and then choose Next.
On the Finish step, select the Configure claims issuance policy for the application check box, and then choose Close.
Based on whether you will be using SAML tokens or JSON Web Tokens (JWT), which are supported from AD FS 3.0 and later, you need to add different claims. Complete one of the following procedures for your token type.
Set up support for SAML 1.0 tokens
Choose the Edit Claims Issuance Policy action.
In the Edit Claim Rules dialog box, choose Add Rule.
In the Select Rule Template step, choose Transform an Incoming Claim template, and then choose Next.
In the Configure Rule step, set the Claim rule name to name, the Incoming claim type to UPN, and the Outgoing claim type to Name. Choose Finish when done.
Repeat steps 2 to 4 to add another rule, except this time, set the Claim rule name to objectidentifier, the Incoming claim type to Primary SID, and the Outgoing claim type to:
Configure Business Central to use AD FS authentication
To setup Business Central for ADFS authentication, you must modify the configuration of the Business Central Server, Business Central Web Server, and Dynamics NAV Client connected to Business Centrals.
Business Central Server instance setup
The Business Central Server instance must be configured to allow claims based authentication. You can do this by using the Business Central Server Administration tool, the Set-NAVServerConfiguration cmdlet in the Business Central Administration Shell, or by modifying the server instance's CustomSettings.config file directly.
Set the Credential Type (ClientServicesCredentialType) to NavUserPassword or AccessControlService.
If you set this to NavUserPassword, client users can use either NavUserPassword or claims based authentication to access Business Central. The CustomSettings.config file should include the following line:
If you set this to AccessControlService, only clients that use claims based authentication will be allowed to access Business Central. The CustomSettings.config file should include the following line:
Set the WS-Federation Metadata Location (ClientServicesFederationMetadataLocation) to the URL that defines the federation metadata XML document for your AD FS. The URL has the following format:
https://<Public URL for AD FS server>/federationmetadata/2007-06/federationmetadata.xml
Replace <Public URL for AD FS server> with the URL for your installation. For example:
This URL must to be accessible from a browser on the computer running the Business Central Server.
For the Business Central Web client, set the WSFederationLoginEndpoint (WSFederationLoginEndpoint) to point to the AD FS login page for authenticating users.
https://<Public URL for ADFS server>/adfs/ls/?wa=wsignin1.0%26wtrealm=<Relying party trust identifier>%26wreply=<Business Central Web Client URL>/SignIn" />
Replace <Public URL for AD FS server> with the URL for your installation.
Replace <Relying party trust identifier> with the exact value that was specified as the Relying party trust identifier in the earlier task (Set up a Relying Party Trust for the Business Central clients).
Replace <Business Central Web Client URL> with the exact value that was specified for Relying party WS-Federation Passive Control URL field in the Relying Party Trust set up for the client in AD FS. Make sure that the case matches exactly.
For the Dynamics NAV Client connected to Business Central, set the Valid Audiences (ValidAudiences) to the exact value that was specified as the Relying party trust identifier in the earlier task (Set up a Relying Party Trust for the Business Central clients). For example:
The configuration changes are automatically picked up by the Internet Information Service (IIS).
Tip
Instead of re-configuring the existing web client, consider using the New-NAVWebServerInstance cmdlet in the Business Central Administration Shell to add an additional web server instance, and leave the existing instance running NavUserPassword authentication.
Set up the Dynamic NAV Windows client (optional)
Note
Dynamics NAV Client connected to Business Central is DISCONTINUED AFTER: Business Central Spring 2019.
You configure the Dynamics NAV Client connected to Business Central by modifying the ClientUserSettings.config file for each client installation.
Set the ClientServicesCredentialType to AccessControlService as shown:
This means that authentication is delegated to the URL that is specified by ACSUri setting.
Set the ACSUri setting to the AD FS login page as shown:
<add key="ACSUri" value="https://<Public URL for ADFS server>/adfs/ls/?wa=wsignin1.0%26wtrealm=<https://dynamicsnavwinclient%26wreply=<Relying Party Trust Endpoint>" />
Replace <Public URL for AD FS server> with the URL for your installation.
Replace <Relying party trust identifier> with the exact value that was specified as the Relying party trust identifier in the earlier task (Set up a Relying Party Trust for the Business Central clients).
Replace <Relying Party Trust Endpoint> with the same value that was specified for Relying party WS-Federation Passive Control URL field in the Relying Party Trust set up for the Dynamics NAV Client connected to Business Central in AD FS.
Restart the Dynamics NAV Client connected to Business Central.
Business Central User setup
You must map the user accounts in Business Central to corresponding user accounts in AD FS. The mapping is based on the User Principal Name (UPN) that is assigned to the user in Active Directory. The UPN is the user's name in email address format, such as username@corp.sample.com.
You can do this by using the Business Central client. Open the User Card page for a user, and then in the Office 365 Authentication section, set the Authentication Email field to the UPN of the AD FS user.
When you initially set the Authentication Email, the Authentication Status will be Inactive. After the first time the user signs in to Business Central by using AD FS, the status will be change to Active. This means that the Primary SID from AD FS has been registered on the user in Business Central, and all subsequent authentication mappings will be done on the Primary SID and not on the Authentication Email (UPN).
As a functional consultant, you implement core application setup processes for small and medium businesses. You configure the application in collaboration with the implementation team to provide the business with manageability and ease of use.