Authenticating Users with Active Directory Federation Services

Article
02/15/2022

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.

For more information, see Active Directory Federation Services.

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:
- Business Central Server.
- Business Central Web Server.
  
  The web server instance must be configured to use SSL (https) for client connections. For more information, see Configuring SSL to Secure the Business Central Web Client Connection
- Dynamics NAV Client connected to Business Central (optional)
- Business Central Server Administration tool (optional)
- Business Central Administration Shell (optional)
Important

The deployment must be configured with security certificates to secure remote connections. For more information, see Using Security Certificates with Business Central On-Premises.

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:
```
https://<web-server-computer>:<port>/<webserver-instance>
```
  or
```
https://<domain>/<webserver-instance>
```
  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:
```
http://schemas.microsoft.com/identity/claims/objectidentifier
```
Choose OK when done to close the Edit Claim Rules dialog box.

Set up support for JSON Web tokens (JWT)

Choose the Edit Claims Issuance Policy action.
In the Edit Claim Rules dialog box, choose Add Rule.
In the Select Rule Template step, choose Send Claims Using a Custom Rule template, and then choose Next.

Set the Claim rule name to name, and the Custom rule to:

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"] => issue(Type = "unique_name", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);

Repeat steps 2 and 3 to add another custom rule, except for this rule, set the Claim rule name to objectidentifier, and the Custom rule to:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid"] => issue(Type = "oid", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType);

Close the Edit Claim Rules dialog box.

Start Window Powershell, and run the following command to define the token type for the relying party to be JWT:

Set-ADFSRelyingPartyTrust –TargetIdentifier "[Relying party trust identifier]" –EnableJWT $true

Replace [Relying party trust identifier] with the relying party trust identifier that you added in AD FS for the client, for example:

Set-ADFSRelyingPartyTrust –TargetIdentifier "https://bcwebclient" –EnableJWT $true

Set-ADFSRelyingPartyTrust –TargetIdentifier "https://dynamicsnavwinclient" –EnableJWT $true

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:
```
<add key="ClientServicesCredentialType" value="NavUserPassword"/>
```
- 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:
```
<add key="ClientServicesCredentialType" value="AccessControlService"/>
```
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:
```
https://MyADFSServer/federationmetadata/2007-06/federationmetadata.xml"/>
```
or
```
https://corp.sample.com/federationmetadata/2007-06/federationmetadata.xml
```
Note

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 example:
```
https://corp.sample.com/adfs/ls/?wa=wsignin1.0%26wtrealm=https://bcwebclient%26wreply=https://MyWebServer:443/BC130/SignIn
```
or
```
https://corp.sample.com/adfs/ls/?wa=wsignin1.0%26wtrealm=https://bcwebclient%26wreply=https://corp.sample.com/BC130/SignIn
```
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:
```
https://dynamicsnavwindowsclient
```
Restart the Business Central Server instance.

Tip

You can use the Set-NAVServerInstance cmdlet to restart the service instance.

Set up the Business Central Web Server

You configure the Business Central Web Server by modifying it's navsettings.json configuration file.

Change the ClientServicesCredentialType setting to AccessControlService as shown:

"ClientServicesCredentialType":  "AccessControlService",

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:
```
<add key="ClientServicesCredentialType" value="AccessControlService" />
```
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.

For example:
```
<add key="ACSUri" value="https://corp.sample.com/adfs/ls/?wa=wsignin1.0%26wtrealm=https://dynamicsnavwinclient%26wreply=https://corp.sample.com" />
```
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).

For more information, see Managing Users and Permissions.

Partager via