Set up and deploy on-premises environments (Platform update 41 and later)

This topic explains how to plan, set up, and deploy Microsoft Dynamics 365 Finance + Operations (on-premises) with Platform update 41 and later. Platform update 41 is available with version 10.0.17.

The Local Business Data Yammer group is available. There, you can post any questions or feedback that you have about the on-premises deployment.

Finance + Operations components

The Finance + Operations application consists of three main components:

  • Application Object Server (AOS)
  • Business Intelligence (BI)
  • Financial Reporting/Management Reporter

These components depend on the following system software:

  • Microsoft Windows Server (Only English-language operating system installations are supported.)

  • Microsoft SQL Server

    Important

    Full-Text Search must be enabled.

  • SQL Server Reporting Services (SSRS)

    SSRS is deployed on BI virtual machines (VMs). The SSRS nodes should also have a Database Engine instance that is running locally.

  • SQL Server Integration Services (SSIS)

    SSIS is deployed on AOS VMs.

  • SQL Server Management Studio

  • Standalone Microsoft Azure Service Fabric

  • Microsoft Windows PowerShell 5.0 or later

  • Active Directory Federation Services (AD FS) on Windows Server

  • Domain controller

    Important

    The domain controller must be Microsoft Windows Server 2012 R2 or later, and it must have a domain functional level of 2012 R2 or more. For more information about domain functional levels, see the following topics:

  • Optional but highly recommended: Active Directory Certificate Services (AD CS) on Windows Server

LCS

Finance + Operations bits are distributed through Microsoft Dynamics Lifecycle Services (LCS). Before you can deploy, you must purchase license keys through the Enterprise Agreements channel and set up an on-premises project in LCS. Deployments can be initiated only through LCS. For more information about how to set up on-premises projects in LCS, see Set up on-premises projects in Lifecycle Services (LCS).

Authentication

The on-premises application works with AD FS. To interact with LCS, you must also configure Azure Active Directory (Azure AD). To complete the deployment and configure the LCS local agent, you must have Azure AD. If you don't already have an Azure AD tenant, you can get one for free by using one of the options that Azure AD provides. For more information, see Quickstart: Set up a tenant.

Standalone Service Fabric

Finance + Operations uses standalone Service Fabric. For more information, see the Service Fabric documentation.

Setup of Finance + Operations will deploy a set of applications inside Service Fabric. During deployment, each node in the cluster will be defined through configuration so that it has one of the following node types:

  • AOSNodeType – Nodes of this type host AOS (business logic).
  • OrchestratorType – Nodes of this node type work as Service Fabric Primary nodes, and host deployment and servicing logic.
  • ReportServerType – Nodes of this type host SSRS and reporting logic.
  • MRType – Nodes of this type host Management Reporter logic.

Infrastructure

Finance + Operations falls under the standard Microsoft support policy about operation on non-Microsoft virtualization platforms, specifically VMware. For more information, see Support policy for Microsoft software that runs on non-Microsoft hardware virtualization software. In short, Microsoft supports its products in this environment. However, if Microsoft is asked to investigate an issue, we might first ask the customer to reproduce the issue without the virtualization platform or on the Microsoft virtualization platform.

If you're using VMware, you must implement the fixes that are documented on the following webpages:

Warning

Dynamics 365 Finance + Operations (on-premises) is not supported on any public cloud infrastructure, including Microsoft Azure Cloud services. However, it is supported to run on Microsoft Azure Stack Hub.

The hardware configuration includes the following components:

  • A standalone Service Fabric cluster that is based on Windows Server VMs
  • SQL Server (Both Clustered SQL and Always-On are supported.)
  • AD FS for authentication
  • Server Message Block (SMB) version 3 file share for storage
  • Optional: Microsoft Office Server

For more information, see System requirements for on-premises deployments.

Hardware layout

Plan your infrastructure and Service Fabric cluster, based on the recommended sizing in Hardware sizing requirements for on-premises environments. For more information about how to plan the Service Fabric cluster, see Plan and prepare your Service Fabric standalone cluster deployment.

The following table shows an example of a hardware layout. This example is used throughout this topic to demonstrate the setup. When you complete the setup, you will have to replace the machine names and IP addresses that are provided in the following instructions with the names and IP addresses for the machines in your environment.

Note

The Primary node of the Service Fabric cluster must have at least three nodes. In this example, OrchestratorType is designated as the Primary node type. If you have a node type that has more than three VMs, consider making that node type your Primary (Seed) node type to help increase the reliability of the cluster.

Machine purpose Service Fabric node type Machine name IP address
Domain controller DAX7SQLAODC1 10.179.108.2
AD FS DAX7SQLAOADFS1 10.179.108.3
File server DAX7SQLAOFILE1 10.179.108.4
SQL Always-On cluster DAX7SQLAOSQLA01 10.179.108.5
DAX7SQLAOSQLA02 10.179.108.6
DAX7SQLAOSQLA 10.179.108.9
Client SQLAOCLIENT1 10.179.108.11
AOS 1 AOSNodeType SQLAOSF1AOS1 10.179.108.12
AOS 2 AOSNodeType SQLAOSF1AOS2 10.179.108.13
AOS 3 AOSNodeType SQLAOSF1AOS3 10.179.108.14
Orchestrator 1 OrchestratorType SQLAOSF1ORCH1 10.179.108.21
Orchestrator 2 OrchestratorType SQLAOSF1ORCH2 10.179.108.22
Orchestrator 3 OrchestratorType SQLAOSF1ORCH3 10.179.108.23
Management Reporter node MRType SQLAOSMR1 10.179.108.31
SSRS node 1 ReportServerType SQLAOSFBI1 10.179.108.41

The following table shows an example of a hardware layout where batch execution and interactive sessions are run in dedicated nodes. For more information, see Configure batch-only and interactive-only AOS nodes in on-premises deployments.

Machine purpose Service Fabric node type Machine name IP address
Domain controller DAX7SQLAODC1 10.179.108.2
AD FS DAX7SQLAOADFS1 10.179.108.3
File server DAX7SQLAOFILE1 10.179.108.4
SQL Always-On cluster DAX7SQLAOSQLA01 10.179.108.5
DAX7SQLAOSQLA02 10.179.108.6
DAX7SQLAOSQLA 10.179.108.9
Client SQLAOCLIENT1 10.179.108.11
AOS 1 BatchOnlyAOSNodeType SQLAOSF1AOS1 10.179.108.12
AOS 2 BatchOnlyAOSNodeType SQLAOSF1AOS2 10.179.108.13
AOS 3 BatchOnlyAOSNodeType SQLAOSF1AOS3 10.179.108.14
AOS 4 InteractiveOnlyAOSNodeType SQLAOSF1AOS4 10.179.108.15
AOS 5 InteractiveOnlyAOSNodeType SQLAOSF1AOS5 10.179.108.16
AOS 6 InteractiveOnlyAOSNodeType SQLAOSF1AOS6 10.179.108.17
Orchestrator 1 OrchestratorType SQLAOSF1ORCH1 10.179.108.21
Orchestrator 2 OrchestratorType SQLAOSF1ORCH2 10.179.108.22
Orchestrator 3 OrchestratorType SQLAOSF1ORCH3 10.179.108.23
Management Reporter node MRType SQLAOSMR1 10.179.108.31
SSRS node 1 ReportServerType SQLAOSFBI1 10.179.108.41

Overview of the setup process

You must complete the following steps to set up the infrastructure for Finance + Operations. By reading all the steps before you begin, you can more easily plan your setup.

  1. Plan your domain name and DNS zones
  2. Plan and acquire your certificates
  3. Plan your users and service accounts
  4. Create DNS zones, and add A records
  5. Join VMs to the domain
  6. Download setup scripts from LCS
  7. Describe your configuration
  8. Configure certificates
  9. Set up VMs
  10. Set up a standalone Service Fabric cluster
  11. Configure LCS connectivity for the tenant
  12. Set up file storage
  13. Set up SQL Server
  14. Configure the databases
  15. Encrypt credentials
  16. Set up SSIS
  17. Set up SSRS
  18. Configure AD FS
  19. Configure a connector, and install an on-premises local agent
  20. Tear down CredSSP, if remoting was used
  21. Deploy your Finance + Operations environment from LCS
  22. Connect to your Finance + Operations environment

Setup

Prerequisites

Before you start the setup, the following prerequisites must be in place. The setup of these prerequisites is out of the scope of this document.

  • Active Directory Domain Services (AD DS) must be installed and configured in your network.
  • AD FS must be deployed.
  • SQL Server must be installed on the SSRS machines.
  • SSRS must be installed (but not configured) in Native mode on the SSRS machines.
  • Optional: AD CS is installed and configured in your network.

The following table shows the prerequisite software that is installed on the VMs by the infrastructure setup scripts that are downloaded from LCS.

Node type Component Details
AOS SNAC – ODBC driver 13 ODBC driver 13.1
AOS SNAC – ODBC driver 17.5.x ODBC driver 17.5.2
AOS The Microsoft .NET Framework version 2.0–3.5 (CLR 2.0) Windows features: NET-Framework-Features, NET-Framework-Core, NET-HTTP-Activation, NET-Non-HTTP-Activ
AOS The Microsoft .NET Framework version 4.0–4.6 (CLR 4.0) Windows features: NET-Framework-45-Features, NET-Framework-45-Core, NET-Framework-45-ASPNET, NET-WCF-Services45, NET-WCF-TCP-PortSharing45
AOS The Microsoft .NET Framework version 4.7.2 (CLR 4.0) https://dotnet.microsoft.com/download/thank-you/net472-offline
AOS Microsoft Internet Information Services (IIS) Windows features: WAS, WAS-Process-Model, WAS-NET-Environment, WAS-Config-APIs, Web-Server, Web-WebServer, Web-Security, Web-Filtering, Web-App-Dev, Web-Net-Ext, Web-Mgmt-Tools, Web-Mgmt-Console
AOS SQL Server Management Studio 17.9.1 SSMS 17.9.1
AOS Microsoft Visual C++ Redistributable Packages for Microsoft Visual Studio 2013 https://support.microsoft.com/help/3179560
AOS Microsoft Visual C++ Redistributable Packages for Microsoft Visual Studio 2017 Go to https://lcs.dynamics.com/V2/SharedAssetLibrary, select Model as the asset type, and then select VC++ 17 Redistributables.
AOS Microsoft Access Database Engine 2010 Redistributable https://www.microsoft.com/download/details.aspx?id=13255
BI The .NET Framework version 2.0–3.5 (CLR 2.0) Windows features: NET-Framework-Features, NET-Framework-Core, NET-HTTP-Activation, NET-Non-HTTP-Activ
BI The .NET Framework version 4.0–4.6 (CLR 4.0) Windows features: NET-Framework-45-Features, NET-Framework-45-Core, NET-Framework-45-ASPNET, NET-WCF-Services45, NET-WCF-TCP-PortSharing45
BI The .NET Framework version 4.7.2 (CLR 4.0) https://dotnet.microsoft.com/download/thank-you/net472-offline
BI SQL Server Management Studio 17.9.1 SSMS 17.9.1
MR The .NET Framework version 2.0–3.5 (CLR 2.0) Windows features: NET-Framework-Features, NET-Framework-Core, NET-HTTP-Activation, NET-Non-HTTP-Activ
MR The .NET Framework version 4.0–4.6 (CLR 4.0) Windows features: NET-Framework-45-Features, NET-Framework-45-Core, NET-Framework-45-ASPNET, NET-WCF-Services45, NET-WCF-TCP-PortSharing45
MR The .NET Framework version 4.7.2 (CLR 4.0) https://dotnet.microsoft.com/download/thank-you/net472-offline
MR Visual C++ Redistributable Packages for Visual Studio 2013 https://support.microsoft.com/help/3179560
ORCH The Microsoft .NET Framework version 4.0–4.8 (CLR 4.0) https://dotnet.microsoft.com/download/thank-you/net48-offline

Step 1. Plan your domain name and DNS zones

We recommend that you use a publicly registered domain name for your production installation of AOS. In that way, the installation can be accessed outside the network, if outside access is required.

For example, if your company's domain is contoso.com, your zone for Finance + Operations might be d365ffo.onprem.contoso.com, and the host names might be as follows:

  • ax.d365ffo.onprem.contoso.com for AOS machines
  • sf.d365ffo.onprem.contoso.com for the Service Fabric cluster

Step 2. Plan and acquire your certificates

Secure Sockets Layer (SSL) certificates are required to secure a Service Fabric cluster and all the applications that are deployed. For your production and sandbox workloads, we recommend that you acquire certificates from a certificate authority (CA) such as DigiCert, Comodo, Symantec, GoDaddy, or GlobalSign. If your domain is set up with AD CS, you can use the Microsoft setup scripts to create the templates and certificates. Each certificate must contain a private key that was created for key exchange, and it must be exportable to a Personal Information Exchange (.pfx) file.

Self-signed certificates can be used only for testing purposes. For the sake of convenience, the setup scripts that are provided in LCS include scripts that generate and export self-signed certificates. If you're using self-signed scripts, you will be instructed to run the creation scripts during later steps in this topic. As has been mentioned, these certificates can be used only for testing purposes.

Important

Microsoft plans to discontinue support for the generation of self-signed certificates through the setup scripts, in favor of automatic certificate creation through AD CS.

Here are the recommended settings for certificates:

  • Signature algorithm: sha256RSA
  • Signature hash algorithm: sha256
  • Public key: RSA (2048 bits)
  • Thumbprint algorithm: sha1
Purpose Explanation Additional requirements
SQL Server SSL certificate This certificate is used to encrypt data that is transmitted across a network between an instance of SQL Server and a client application.

The domain name of the certificate should match the fully qualified domain name (FQDN) of the SQL Server instance or listener. For example, if the SQL listener is hosted on machine DAX7SQLAOSQLA, the certificate's Domain Name System (DNS) name is DAX7SQLAOSQLA.contoso.com.

  • Common name (CN): DAX7SQLAOSQLA.contoso.com
  • DNS name: DAX7SQLAOSQLA.contoso.com
Service Fabric Server certificate This certificate is used to help secure the node-to-node communication between the Service Fabric nodes. It's also used as the server certificate that is presented to the client that connects to the cluster.

For this certificate, you can also use the wildcard SSL certificate for your domain, such as *.contoso.com. (For more information, see the text that follows this table.) Otherwise, use the following values:

  • CN: sf.d365ffo.onprem.contoso.com
  • DNS name: sf.d365ffo.onprem.contoso.com
Service Fabric Client certificate Clients use this certificate to view and manage the Service Fabric cluster.
  • CN: client.d365ffo.onprem.contoso.com
  • DNS name: client.d365ffo.onprem.contoso.com
Encipherment certificate This certificate is used to encrypt sensitive information such as the SQL Server password and user account passwords.

The certificate must be created by using the Microsoft Enhanced Cryptographic Provider v1.0 provider.

The certificate key usage must include Data Encipherment (10), and should not include server authentication or client authentication.

For more information, see Managing secrets in Service Fabric applications.

  • CN: axdataenciphermentcert
  • DNS name: axdataenciphermentcert
AOS SSL certificate

This certificate is used as the server certificate that is presented to the client for the AOS website. It's also used to enable Windows Communication Foundation (WCF)/Simple Object Access Protocol (SOAP) certificates.

You can use the same wildcard SSL certificate that you used as the Service Fabric server certificate. Otherwise, use the following values:

  • CN: ax.d365ffo.onprem.contoso.com
  • DNS name: ax.d365ffo.onprem.contoso.com
Session Authentication certificate AOS uses this certificate to help secure a user's session information.

This certificate is also the File Share certificate that will be used at the time of deployment from LCS.

  • CN: SessionAuthentication
  • DNS name: SessionAuthentication
Data Encryption certificate AOS uses this certificate to encrypt sensitive information.

This certificate must be created by using the Microsoft Enhanced RSA and AES Cryptographic Provider provider.

  • CN: DataEncryption
  • DNS name: DataEncryption
Data Signing certificate AOS uses this certificate to encrypt sensitive information.

This certificate is separate from the Data Encryption certificate and must be created by using the Microsoft Enhanced RSA and AES Cryptographic Provider provider.

  • CN: DataSigning
  • DNS name: DataSigning
Financial Reporting Client certificate This certificate is used to help secure the communication between the Financial Reporting services and AOS.
  • CN: FinancialReporting
  • DNS name: FinancialReporting
Reporting certificate This certificate is used to help secure the communication between SSRS and AOS.

Important: Do not reuse the Financial Reporting Client certificate.

  • CN: ReportingService
  • DNS name: ReportingService
SSRS Web Server certificate This certificate is used as the server certificate that is presented to the client (AOS) for the SSRS web server.

The domain name of the certificate should match the FQDN of the SSRS node.

  • CN: BI1.contoso.com
  • DNS name: BI1.contoso.com
On-Premises local agent certificate

This certificate is used to help secure the communication between a local agent that is hosted on-premises and on LCS. It enables the local agent to act on behalf of your Azure AD tenant, and to communicate with LCS to orchestrate and monitor deployments.

Note: Only one on-premises local agent certificate is required for a tenant.

  • CN: OnPremLocalAgent
  • DNS name: OnPremLocalAgent

You can use the wildcard SSL certificate for your domain to combine the Service Fabric Server certificate and the AOS SSL certificate.

Here is an example of a Service Fabric Server certificate that is combined with an AOS SSL certificate.

Subject name

CN = *.d365ffo.onprem.contoso.com

Subject alternative names

DNS Name=ax.d365ffo.onprem.contoso.com
DNS Name=sf.d365ffo.onprem.contoso.com
DNS Name=*.d365ffo.onprem.contoso.com

Important

You can use the wildcard certificate to help secure only the first-level subdomain of the domain that it's issued to. Therefore, a certificate for *.onprem.contoso.com won't be valid for ax.d365ffo.onprem.contoso.com.

Step 3. Plan your users and service accounts

You must create several user or service accounts for Finance + Operations to work. You must create a combination of group managed service accounts (gMSAs), domain accounts, and SQL accounts. The following table shows the user accounts, their purpose, and example names that will be used in this topic.

User account Type Purpose User name
Financial Reporting Application Service Account gMSA Contoso\svc-FRAS$
Financial Reporting Process Service Account gMSA Contoso\svc-FRPS$
Financial Reporting Click Once Designer Service Account gMSA Contoso\svc-FRCO$
AOS Service Account gMSA You should create this user for future proofing. Microsoft plans to enable AOS to work with the gMSA in upcoming releases. By creating this user at the time of setup, you help to ensure a seamless transition to the gMSA.* Contoso\svc-AXSF$
SSRS bootstrapper Service Account gMSA The reporting service bootstrapper uses this account to configure the SSRS service. Contoso\svc-ReportSvc$
AOS Service Account Domain account AOS uses this user in the general availability (GA) release.* Contoso\AXServiceUser
AOS SQL DB Admin user SQL user Finance + Operations uses this user to authenticate with SQL**. This user will also be replaced by the gMSA user in upcoming releases***. AXDBAdmin
Local Deployment Agent Service Account gMSA The local agent uses this account to orchestrate the deployment on various nodes. Contoso\Svc-LocalAgent$

* These accounts should not have their regional settings changed. They should have the default EN-US region settings.

** If the password of the SQL user contains special characters, you might encounter issues during deployment.

*** The SQL user name and password for SQL authentication are secured because they are encrypted and stored in the file share.

Step 4. Create DNS zones and add A records

DNS is integrated with AD DS, and lets you organize, manage, and find resources in a network. The following procedures show how to create a DNS forward lookup zone and A records for the AOS host name and Service Fabric cluster. In this example, the DNS zone name is d365ffo.onprem.contoso.com, and the A records/host names are as follows:

  • ax.d365ffo.onprem.contoso.com for AOS machines
  • sf.d365ffo.onprem.contoso.com for the Service Fabric cluster

Add a DNS zone

  1. Sign in to the domain controller machine, select Start. Then open DNS Manager by entering dnsmgmt.msc and selecting the dnsmgmt (DNS) application.
  2. Right-click the domain controller name in the console tree, and then select New Zone > Next.
  3. Select Primary Zone.
  4. Leave the Store the zone in Active Directory (available only if the DNS Server is a writeable domain controller checkbox selected, and then select Next.
  5. Select To all DNS Servers running on Domain Controllers in this domain: Contoso.com, and then select Next.
  6. Select Forward Lookup Zone, and then select Next.
  7. Enter the zone name for your setup, and then select Next. For example, enter d365ffo.onprem.contoso.com.
  8. Select Do not allow dynamic updates, and then select Next.
  9. Select Finish.

Set up an A record for AOS

In the new DNS zone, for each Service Fabric cluster node of the AOSNodeType type, create one A record that is named ax.d365ffo.onprem.contoso.com. Don't create A records for the other node types.

  1. Find the newly created zone under the Forward Lookup Zones folder in DNS Manager.
  2. Select and hold (or right-click) the new zone, and then select New Host.
  3. Enter the name and IP address of the Service Fabric node. (For example, enter ax as the name and 10.179.108.12 as the IP address.) Then select Add Host.
  4. Leave both checkboxes cleared.
  5. Repeat steps 1 through 4 for each additional AOS node.

Set up an A record for the orchestrator

In the new DNS zone, for each Service Fabric cluster node of the OrchestratorType type, create an A record that is named sf.d365ffo.onprem.contoso.com. Don't create A records for the other node types.

  1. Select and hold (or right-click) the new zone, and then select New Host.
  2. Enter the name and IP address of the Service Fabric node. (For example, enter sf as the name and 10.179.108.15 as the IP address.) Then select Add Host.
  3. Leave both checkboxes cleared.
  4. Repeat steps 1 through 3 for each additional orchestrator node.

Step 5. Join VMs to the domain

Join each VM to the domain by completing the steps in Join a Computer to a Domain. Alternatively, use the following Windows PowerShell script.

$domainName = Read-Host -Prompt 'Specify domain name (ex: contoso.com)'
Add-Computer -DomainName $domainName -Credential (Get-Credential -Message 'Enter domain credential')

Important

You must restart the VMs after you join them to the domain.

Step 6. Download setup scripts from LCS

Microsoft has provided several scripts to help improve the setup experience. Follow these steps to download the setup scripts from LCS.

Important

The scripts must be run from a computer that is in the same domain as the on-premises infrastructure.

  1. Sign in to LCS.
  2. On the dashboard, select the Shared asset library tile.
  3. Select Model as the asset type, and then, in the grid, select the row for Dynamics 365 for Operations on-premises - Deployment scripts.
  4. Select Versions, and download the latest version of the zip file for the scripts.
  5. After the zip file is downloaded, select and hold (or right-click) it, and then select Properties. In the Properties dialog box, select the Unblock checkbox.
  6. Copy the zip file to the machine that will be used to run the scripts.
  7. Unzip the files into a folder that is named infrastructure.

Important

Make sure that all edits are made to the ConfigTemplate.xml file in this folder.

Step 7. Describe your configuration

The infrastructure setup scripts use the following configuration files to drive the setup:

  • infrastructure\ConfigTemplate.xml
  • infrastructure\D365FO-OP\NodeTopologyDefinition.xml
  • infrastructure\D365FO-OP\DatabaseTopologyDefinition.xml

Important

To ensure that the setup scripts work correctly, you must update these configuration files with the correct computer names, IP addresses, service accounts, and domain, based on the setup of your environment.

The infrastructure\ConfigTemplate.xml configuration file describes the following details:

  • The service accounts that are required for the application to work

  • The certificates that are required to help secure communications

  • The database configuration

  • The Service Fabric cluster configuration

    Important

    When you configure the Service Fabric cluster, make sure that there are three fault domains for the Primary node type (OrchestratorType). Also make sure that no more than one type of node is deployed on a single machine.

For each Service Fabric node type, the infrastructure\D365FO-OP\NodeTopologyDefinition.xml configuration file describes the following details:

  • The mapping between each node type and the application, domain and service accounts, and certificates
  • Whether User Account Control (UAC) is enabled
  • The prerequisites for Windows features and system software
  • Whether strong name validation should be enabled
  • The list of firewall ports that should be opened
  • Which permissions an account requires for a machine

For each database, the infrastructure\D365FO-OP\DatabaseTopologyDefinition.xml configuration file describes the following details:

  • The database settings
  • The mappings between users and roles

Create gMSA and domain user accounts

  1. Go to the machine that has the unzipped infrastructure scripts in the infrastructure folder.

  2. Copy the infrastructure folder to the domain controller machine.

  3. Open Windows PowerShell in elevated mode, change the directory to the infrastructure folder, and run the following commands.

    Important

    These commands don't create an AxServiceUser domain user for you. You must create it yourself.

    Import-Module .\D365FO-OP\D365FO-OP.psd1
    New-D365FOGMSAAccounts -ConfigurationFilePath .\ConfigTemplate.xml
    
  4. If you must make changes to accounts or machines, update the ConfigTemplate.xml file in the original infrastructure folder, copy it to this machine, and then run the following command.

    Update-D365FOGMSAAccounts -ConfigurationFilePath .\ConfigTemplate.xml
    

Step 8. Configure certificates

  1. Go to the machine that you originally unzipped the infrastructure folder to.

  2. Generate certificates:

    1. If you must generate certificates, run the following commands. These commands create the certificate templates in AD CS, generate the certificates from the templates, put the certificates in the CurrentUser\My certificate store on the machine, and update the thumbprints in the XML file.

      # If you must create self-signed certs, set the generateSelfSignedCert attribute to true.
      #.\New-SelfSignedCertificates.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
      
      .\New-ADCSCertificates.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -CreateTemplates
      .\New-ADCSCertificates.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
      

      Note

      You must run these commands on a domain controller machine, or on a machine that is running Windows Server and that has Remote Server Administration Tools (RSAT) installed.

    2. If you must reuse any certificates and therefore don't have to generate certificates for them, set the generateADCSCert tag to false.

  3. If you're using SSL certificates that were previously generated, skip certificate generation, update the thumbprints in the ConfigTemplate.xml file. The certificates must be installed in the CurrentUser\My certificate store, and their private keys must be exportable.

    Warning

    Because of a leading non-printable special character, the presence of which is difficult to determine, the Certificate Manager tool (certlm.msc) should not be used to copy thumbprints. If the non-printable special character is present, you will receive the following error message: "X509 certificate not valid." To retrieve the thumbprints, see the results from Windows PowerShell commands, or run the following commands in Windows PowerShell.

    dir cert:\CurrentUser\My
    dir cert:\LocalMachine\My
    dir cert:\LocalMachine\Root
    
  4. In the ProtectTo tag for each certificate, specify a semicolon-separated list of Active Directory users or groups. Only users and groups that are specified in the ProtectTo tag will have the permissions to import the certificates that are exported by using the scripts. The scripts don't support passwords to help protect the exported certificates.

  5. Export the certificates into .pfx files. As part of the export process, the following command will check that the correct cryptographic provider is set for your certificates.

    # Exports .pfx files into a directory VMs\<VMName>. All the certs will be written to the infrastructure\Certs folder.
    .\Export-PfxFiles.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
    

Step 9. Set up VMs

  1. Run the following command to export the scripts that must be run on each VM.

    # Exports the script files to be executed on each VM into a directory VMs\<VMName>.
    .\Export-Scripts.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
    
  2. Download the following Microsoft Windows Installers (MSIs) into a file share that is accessible by all VMs.

    Component Download link Expected file name
    SNAC – ODBC driver 13 ODBC Driver 13.1 msodbcsql.msi
    SNAC – ODBC driver 17.5.x ODBC Driver 17.5.2 msodbcsql_17.msi
    SQL Server Management Studio 17.9.1 SSMS 17.9.1 SSMS-Setup-*.exe
    Visual C++ Redistributable Packages for Microsoft Visual Studio 2013 https://support.microsoft.com/help/3179560 vcredist_x64.exe
    Visual C++ Redistributable Packages for Microsoft Visual Studio 2017 Go to https://lcs.dynamics.com/V2/SharedAssetLibrary, select Model as the asset type, and then select VC++ 17 Redistributables. vc_redist.x64_14_16_27024.exe
    Access Database Engine 2010 Redistributable https://www.microsoft.com/download/details.aspx?id=13255 AccessDatabaseEngine_x64.exe
    The .NET Framework version 4.8 (CLR 4.0) https://dotnet.microsoft.com/download/thank-you/net48-offline ndp48-x86-x64-allos-enu.exe
    The .NET Framework version 4.7.2 (CLR 4.0) https://dotnet.microsoft.com/download/thank-you/net472-offline ndp472-x86-x64-allos-enu.exe

Important

  • Make sure that the Management Studio setup is in the same language as the operating system of the target machine.
  • Make sure that the installer files have the names that are specified in the "Expected file name" column of the preceding table. Rename any files that don't have the expected name. Otherwise, you will encounter errors when you run the Configure-PreReqs.ps1 script.
  • When you download VC++ 17 Redistributables, the executable file is inside the zip file.

Next, follow these steps for each VM, or use remoting from a single machine.

Note

  • The following procedure requires execution on multiple VMs. However, to simplify the process, you can use the remoting scripts that are provided. These scripts let you run the required scripts from a single machine, such as the same machine that is used to run the .\Export-Scripts.ps1 command. When the remoting scripts are available, they are declared after a # If Remoting comment in the Windows PowerShell sections. If you use the remoting scripts, you might not have to run the remaining scripts in a section. In these cases, see the section text.
  • Remoting uses WinRM. In some cases, it requires that CredSSP be enabled. The remoting module enables and disables CredSSP on an execution-by-execution basis. We recommend that you disable CredSSP enabled when it isn't used. Otherwise, there is a risk of credential theft. When you've completed the setup, see the Step 20. Tear down CredSSP, if remoting was used section later in this topic.
  1. Copy the contents of each infrastructure\VMs\<VMName> folder to the corresponding VM. (If the remoting scripts are used, they will automatically copy the contents to the target VMs.) Then run the following command as an administrator.

    # Install prereq software on the VMs.
    
    # If remoting, execute
    # .\Configure-PreReqs-AllVMs.ps1 -MSIFilePath <share folder path of the MSIs> -ConfigurationFilePath .\ConfigTemplate.xml
    
    .\Configure-PreReqs.ps1 -MSIFilePath <path of the MSIs>
    

    Important

    • Each time that you're prompted, restart the machine. Make sure that you rerun the .\Configure-PreReqs.ps1 command after each restart, until all the prerequisites are installed. In the case of remoting, rerun the AllVMs script when all the machines are back online.
    • If you use the remoting scripts, make sure that the current user has access to the file share folder where the MSIs are located. Also make sure that no user is accessing machines of the AOSNodeType, MRType, and ReportServerType types. Otherwise, the remoting scripts will fail to restart the machines, because users are signed in to them.
  2. Run the following command to complete the VM setup.

    # If remoting, execute
    # .\Complete-PreReqs-AllVMs.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
    
    .\Complete-PreReqs.ps1
    
  3. Run the following command to validate the VM setup.

    # If Remoting, execute
    # .\Test-D365FOConfiguration-AllVMs.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
    
    .\Test-D365FOConfiguration.ps1 
    

Important

If you used remoting, be sure to run the cleanup steps after the setup is completed. For instructions, see the Step 20. Tear down CredSSP, if remoting was used section.

Step 10. Set up a standalone Service Fabric cluster

  1. Download the Service Fabric standalone installation package to one of your Service Fabric nodes.

  2. After the zip file is downloaded, select and hold (or right-click) it, and then select Properties. In the Properties dialog box, select the Unblock checkbox.

  3. Copy the zip file to one of the nodes in the Service Fabric cluster, and unzip it. Make sure that the infrastructure folder has access to this folder.

  4. Go to the infrastructure folder, and run the following command to generate the Service Fabric ClusterConfig.json file.

    .\New-SFClusterConfig.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -TemplateConfig <ServiceFabricStandaloneInstallerPath>\ClusterConfig.X509.MultiMachine.json
    
  5. You might have to make additional modifications to your cluster configuration, based on your environment. For more information, see Step 1B: Create a multi-machine cluster, Secure a standalone cluster on Windows using X.509 certificates, and Create a standalone cluster running on Windows Server.

  6. Copy the ClusterConfig.json file that is generated to <ServiceFabricStandaloneInstallerPath>.

  7. Open Windows PowerShell in elevated mode, go to <ServiceFabricStandaloneInstallerPath>, and run the following command to test the ClusterConfig.json file.

    .\TestConfiguration.ps1 -ClusterConfigFilePath .\clusterConfig.json
    
  8. If the test is successful, run the following command to deploy the cluster.

    # If using offline (internet-disconnected) install
    # .\CreateServiceFabricCluster.ps1 -ClusterConfigFilePath .\ClusterConfig.json -FabricRuntimePackagePath <Path to MicrosoftAzureServiceFabric.cab download>
    
    .\CreateServiceFabricCluster.ps1 -ClusterConfigFilePath .\ClusterConfig.json
    
  9. After the cluster is created, open Service Fabric Explorer on any client machine, and validate the installation:

    1. Install the Service Fabric client certificate in the CurrentUser\My certificate store if it isn't already installed.
    2. In Internet Explorer, select Tools (the gear symbol), and then select Compatibility View settings. Clear the Display intranet sites in Compatibility View checkbox.
    3. Go to https://sf.d365ffo.onprem.contoso.com:19080, where sf.d365ffo.onprem.contoso.com is the host name of the Service Fabric cluster that is specified in the zone. If DNS name resolution isn't configured, use the IP address of the machine.
    4. Select the client certificate. The Service Fabric Explorer page appears.
    5. Verify that all nodes appear as green.

    Important

    • If your client machine is a server machine (for example, a machine that is running Windows Server 2019), you must turn off the Internet Explorer Enhanced Security Configuration when you access the Service Fabric Explorer page.
    • If any antivirus software is installed, make sure that you set exclusion. Follow the guidance in the Service Fabric documentation.

Step 11. Configure LCS connectivity for the tenant

An on-premises local agent is used to orchestrate deployment and servicing of Finance + Operations through LCS. To establish connectivity from LCS to the Finance + Operations tenant, you must configure a certificate that enables the local agent to act on behalf on your Azure AD tenant (for example, contoso.onmicrosoft.com).

Use the on-premises agent certificate that you acquired from a CA or the self-signed certificate that you generated by using scripts. The on-premises agent certificate can be reused across multiple sandbox and production environments per tenant.

Only user accounts that have the Global Administrator directory role can add certificates to authorize LCS. By default, the person who signs up for Microsoft 365 for your organization is the global administrator for the directory.

Important

  • You must configure the certificate exactly one time per tenant. All on-premises environments under the same tenant must use the same certificate to connect with LCS.
  • If you run the script below on a server machine (for example, a machine that is running Windows Server 2019), you must temporarily turn off the Internet Explorer Enhanced Security Configuration. Otherwise, the content on the Azure sign-in page will be blocked.
  1. Sign in to the customer's Azure portal to verify that you have the Global Administrator directory role.

  2. From the infrastructure folder, run the following commands to determine whether the certificate is already registered.

    # If you have issues downloading the Azure PowerShell Az module, run the following:
    # [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    
    Install-Module Az
    Import-Module Az
    .\Add-CertToServicePrincipal.ps1 -CertificateThumbprint 'OnPremLocalAgent Certificate Thumbprint' -Test
    

    Important

    If you previously installed AzureRM, you should remove it, because it might not be compatible with any existing AzureRM installations in Windows PowerShell 5.1. For more information, see Migrate Azure PowerShell from AzureRM to Az.

  3. If the script indicates that the certificate isn't registered, run the following command.

    .\Add-CertToServicePrincipal.ps1 -CertificateThumbprint 'OnPremLocalAgent Certificate Thumbprint'
    

Note

If you have multiple tenants that are associated with the login account, you can run the following command to pass the tenant ID as a parameter. In this way, you can ensure that the context is set to the correct tenant.

.\Add-CertToServicePrincipal.ps1 -CertificateThumbprint 'OnPremLocalAgent Certificate Thumbprint' -TenantId 'xxxx-xxxx-xxxx-xxxx'

Step 12. Set up file storage

You must set up the following SMB 3.0 file shares:

  • A file share that stores user documents that are uploaded to AOS (for example, \\DAX7SQLAOFILE1\aos-storage).

  • A file share that stores the latest build and configuration files to orchestrate the deployment (for example, \\DAX7SQLAOFILE1\agent).

    Warning

    Keep this file share path as short as possible, to avoid exceeding the maximum path length on the files that will be put in the share.

For information about how to enable SMB 3.0, see SMB Security Enhancements.

Important

  • Secure dialect negotiation can't detect or prevent downgrades from SMB 2.0 or 3.0 to SMB 1.0. Therefore, we strongly recommend that you disable the SMB 1.0 server. In this way, you can take advantage of the full capabilities of SMB encryption.
  • To help ensure that your data is protected while it's at rest in your environment, you must enable BitLocker Drive Encryption on every machine. For information about how to enable BitLocker, see BitLocker: How to deploy on Windows Server 2012 and later.
  1. On the file share machine, run the following command.

    Install-WindowsFeature -Name FS-FileServer -IncludeAllSubFeature -IncludeManagementTools
    
  2. Set up the \\DAX7SQLAOFILE1\aos-storage file share:

    1. In Server Manager, select File and Storage Services > Shares.
    2. Select Tasks > New Share to create a share. Name the new share aos-storage.
    3. Leave Allow caching of share selected.
    4. Select the Encrypt data access checkbox.
    5. Grant Modify permissions for every machine in the Service Fabric cluster except OrchestratorType.
    6. Grant Modify permissions for the user AOS domain user (contoso\AXServiceUser) and the gMSA user (contoso\svc-AXSF$).

    Note

    To add machines, you might have to enable Computers under Object Types. To add service accounts, you might have to enable Service Accounts under Object Types.

  3. Set up the \\DAX7SQLAOFILE1\agent file share:

    1. In Server Manager, select File and Storage Services > Shares.
    2. Select Tasks > New Share to create a share. Name the new share agent.
    3. Grant Full-Control permissions to the gMSA user for the local deployment agent (contoso\svc-LocalAgent$).
    # Specify user names
    $AOSDomainUser = 'Contoso\AXServiceUser';
    $LocalDeploymentAgent = 'contoso\svc-LocalAgent$';
    
    # Specify the path
    $AosStorageFolderPath = 'D:\aos-storage';
    $AgentFolderPath = 'D:\agent';
    
    # Create new directory
    $AosStorageFolder = New-Item -type directory -path $AosStorageFolderPath;
    $AgentFolder = New-Item -type directory -path $AgentFolderPath;
    
    # Create new SMB share
    New-SmbShare –Name aos-storage -Path $AosStorageFolderPath -EncryptData $True
    New-SmbShare –Name agent -Path $AgentFolderPath
    
    # Set ACL for AOS storage folder
    $Acl = Get-Acl $AosStorageFolder.FullName;
    $Ar = New-Object system.security.accesscontrol.filesystemaccessrule($AOSDomainUser,'Modify','Allow');
    $Acl.SetAccessRule($Ar);
    Set-Acl $AosStorageFolder.FullName $Acl;
    
    # Set ACL for AgentFolder
    $Acl = Get-Acl $AgentFolder.FullName;
    $Ar = New-Object system.security.accesscontrol.filesystemaccessrule($LocalDeploymentAgent,'FullControl','Allow');
    $Acl.SetAccessRule($Ar);
    Set-Acl $AgentFolder.FullName $Acl;
    

Step 13. Set up SQL Server

  1. Install SQL Server with high availability, unless you're deploying in a sandbox environment, where one instance of SQL Server is sufficient. (Nevertheless, you might want to install SQL Server with high availability in sandbox environments to test high-availability scenarios.)

    Important

    You must enable the SQL Server and Windows Authentication mode.

    You can install SQL Server with high availability either as SQL clusters that include a Storage Area Network (SAN) or in an Always-On configuration. Verify that the Database Engine, SSRS, Full-Text Search, and SQL Server Management Tools are already installed.

    Note

    Make sure that Always-On is set up as described in Select Initial Data Synchronization Page (Always On Availability Group Wizards), and follow the instructions in To Prepare Secondary Databases Manually.

  2. Run the SQL service as either a domain user or a gMSA.

  3. Get an SSL certificate from a CA to configure SQL Server for Finance + Operations. For testing purposes, you can create and use a certificate that is generated through AD CS. You will have to replace the computer name and domain name in the following examples.

    AD CS certificate for an Always-On SQL availability group

    If you're setting up testing certificates for Always-On, use the following remoting script. This script works like the manual script that follows.

    #If you need to create self-signed certs
    #.\New-SelfSigned-SQLCert-AllVMs.ps1 -SqlMachineNames SQL1,SQL2 -SqlListenerName SQL-LS -ProtectTo CONTOSO\dynuser
    
    .\New-ADCS-SQLCert-AllVMs.ps1 -SqlMachineNames SQL1,SQL2 -SqlListenerName SQL-LS -ProtectTo CONTOSO\dynuser
    

    AD CS certificate for a single SQL availability group

    #If you need to create self-signed certs
    #.\New-SelfSigned-SQLCert-AllVMs.ps1 -SqlMachineNames SQL1 -ProtectTo CONTOSO\dynuser
    
    .\New-ADCS-SQLCert-AllVMs.ps1 -SqlMachineNames SQL1 -ProtectTo CONTOSO\dynuser
    

    Manual AD CS steps for an Always-On SQL availability group or Windows Server Failover Clustering with SQL Server

    For each node of the SQL cluster, follow these steps.

    1. Run the following Windows PowerShell command on each of the SQL Server Always-On replicas.

      #If you need to create self-signed certs
      #.\New-SelfSigned-SQLCert-AllVMs.ps1 -SqlMachineNames SQL1,SQL2 -SqlListenerName SQL-LS -ProtectTo CONTOSO\dynuser -GenerateCertOnly
      
      .\New-ADCS-SQLCert-AllVMs.ps1 -SqlMachineNames SQL1,SQL2 -SqlListenerName SQL-LS -ProtectTo CONTOSO\dynuser -GenerateCertOnly
      
    2. Grant certificate permissions to the account that is used to run the SQL service:

      1. Open the Certificate Manager tool (certlm.msc).
      2. Select and hold (or right-click) the certificate that was created, and then select Tasks > Manage Private Keys.
      3. Add the SQL Server service account, and grant it Read access.
    3. Enable ForceEncryption and the new certificate in SQL Server Configuration Manager:

      1. Open SQL Server Configuration Manager, expand SQL Server Network Configuration, select and hold (or right-click) Protocols for [server instance], and then select Properties.
      2. In the Properties dialog box, on the Certificate tab, in the Certificate field, select the desired certificate.
      3. On the Flags tab, in the ForceEncryption box, select Yes.
      4. Select OK to save your changes.
    4. Export the certificate (.cer file) from each SQL cluster node, and install it in the trusted root of each Service Fabric node. You will have at least two certificates for the Always-On cluster. However, you might have more if you have additional replicas.

    5. Restart the SQL service.

Important

If you used remoting, be sure to run the cleanup steps after the setup is completed. For instructions, see the Step 20. Tear down CredSSP, if remoting was used section.

Step 14. Configure the databases

  1. Sign in to LCS.

  2. On the dashboard, select the Shared asset library tile.

  3. Select Model as the asset type. Then, in the grid, select the data type for the release that you want, and download the zip file.

    Release Database
    On-premises Platform update 41 Dynamics 365 for Operations on-premises, Version 10.0.17 Demo Data
    On-premises Platform update 41 Dynamics 365 for Operations on-premises, Version 10.0.17 Empty Data
  4. The zip file contains a single backup (.bak) file. Select the file to download, based on your requirements.

  5. After the zip file is downloaded, verify that it's unblocked. Select and hold (or right-click) the file, and then select Properties. In the Properties dialog box, select the Unblock checkbox.

  6. Make sure that the database section in the infrastructure\ConfigTempate.xml file is correctly configured with the following information:

    • The database name.
    • The database file and log settings. The database settings should not be lower than the default values that are specified.
    • The path of the backup file that you downloaded earlier. The default name of the Finance + Operations database is AXDB.

    Important

    • The user who is running the SQL service and the user who is running the scripts should have Read access on the folder or share where the backup file is located.
    • If an existing database already has the same name, it won't be overwritten.
  7. Copy the infrastructure folder to the SQL Server machine. Then open Windows PowerShell in elevated mode, and go to the folder.

Configure the OrchestratorData database

  • Run the following command.

    .\Initialize-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName Orchestrator
    

    The Initialize-Database.ps1 script performs the following actions:

    1. Create an empty database that is named OrchestratorData. This database is used by the on-premises local agent to orchestrate deployments.
    2. Grant db_owner permissions on the database to the local agent gMSA (svc-LocalAgent$).

Configure the Finance + Operations database

  1. Run the following commands.

    .\Initialize-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName AOS
    .\Configure-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName AOS
    

    The Initialize-Database.ps1 script performs the following actions:

    1. Restore the database from the specified backup file.

    2. Create a new user that SQL authentication is enabled for (axdbadmin).

    3. Map users to database roles, based on the following table for the AXDB database.

      User Type Database role
      svc-AXSF$ gMSA db_owner
      svc-LocalAgent$ gMSA db_owner
      svc-FRPS$ gMSA db_owner
      svc-FRAS$ gMSA db_owner
      axdbadmin SqlUser db_owner
    4. Map users to database roles, based on the following table for the TempDB database.

      User Type Database role
      svc-AXSF$ gMSA db_datareader, db_datawriter, db_ddladmin
      axdbadmin SqlUser db_datareader, db_datawriter, db_ddladmin

    The Configure-Database.ps1 script performs the following actions:

    1. Set READ_COMMITTED_SNAPSHOT to ON.
    2. Set ALLOW_SNAPSHOT_ISOLATION to ON.
    3. Set the specified database file and log settings.
    4. Grant the VIEW SERVER STATE permission to axdbadmin.
    5. Grant the ALTER ANY EVENT SESSION permission to axdbadmin.
    6. Grant the VIEW SERVER STATE permission to [contoso\svc-AXSF$].
    7. Grant the ALTER ANY EVENT SESSION permission to [contoso\svc-AXSF$].
  2. Run the following command to reset the database users.

    .\Reset-DatabaseUsers.ps1 -DatabaseServer '<FQDN of the SQL server>' -DatabaseName '<AX database name>'
    

Configure the Financial Reporting database

  • Run the following command.

    .\Initialize-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName MR
    

    The Initialize-Database.ps1 script performs the following actions:

    1. Create an empty database that is named FinancialReporting.

    2. Map the users to database roles, based on the following table.

      User Type Database role
      svc-LocalAgent$ gMSA db_owner
      svc-FRPS$ gMSA db_owner
      svc-FRAS$ gMSA db_owner

Step 15. Encrypt credentials

  1. On any client machine, install the encipherment certificate in the LocalMachine\My certificate store.

  2. Grant the current user Read access to the private key of this certificate.

  3. Create the Credentials.json file, as shown here.

    {
        "AosPrincipal": {
            "AccountPassword": "<encryptedDomainUserPassword>"
        },
        "AosSqlAuth": {
            "SqlUser": "<encryptedSqlUser>",
            "SqlPwd": "<encryptedSqlPassword>"
        }
    }
    
    • AccountPassword – The encrypted domain user password for the AOS domain user (contoso\axserviceuser).
    • SqlUser – The encrypted SQL user (axdbadmin) that has access to the Finance + Operations database (AXDB)
    • SqlPassword – The encrypted SQL password.
  4. Copy the .json file to the SMB file share: \\AX7SQLAOFILE1\agent\Credentials\Credentials.json.

  5. Update the Credentials.json file with encrypted values.

    # Service fabric API to encrypt text and copy it to the clipboard.
    Invoke-ServiceFabricEncryptText -Text '<textToEncrypt>' -CertThumbprint '<DataEncipherment Thumbprint>' -CertStore -StoreLocation LocalMachine -StoreName My | Set-Clipboard
    

    Important

    • Before you can invoke the Invoke-ServiceFabricEncryptText command, you must install the Microsoft Azure Service Fabric software development kit (SDK).
    • After you install the Service Fabric SDK, you might receive the following error message: "Invoke-ServiceFabricEncryptText is not recognized command." In this case, restart the computer, and try again.

    Warning

    After you've finished invoking all the Invoke-ServiceFabricEncryptText commands, remember to delete the Windows PowerShell history. Otherwise, your non-encrypted credentials will be visible.

Step 16. Set up SSIS

To enable Data management and SSIS workloads, you must install SSIS on each AOS VM. Follow these steps on each AOS VM.

  1. Verify that the machine has access to the SSIS installation, and open the SSIS Setup wizard.
  2. On the Feature Selection page, in the Features pane, select the Integration Services and SQL Client Connectivity SDK checkboxes.
  3. Complete the setup, and verify that the installation was successful.

For more information, see Install Integration Services (SSIS).

Step 17. Set up SSRS

You can configure more than one SSRS node. For more information, see Configuring High Availability for SSRS nodes.

  1. Before you begin, make sure that the prerequisites that are listed at the beginning of this topic are in place.

    Important

    • You must install the Database Engine when you install SSRS.
    • Do not configure the SSRS instance. The reporting service will automatically configure everything.
    • Environments that were deployed with a base topology older than Platform update 41, do not need to go through the steps below. In those environments, SSRS should be configured manually according to Configure SQL Server Reporting Services for on-premises deployments.
  2. For each BI node, follow these steps:

    1. Copy the infrastructure folder. Then open Windows PowerShell in elevated mode, and go to the folder.

    2. Run the following commands.

      .\Initialize-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName BI
      .\Configure-Database.ps1 -ConfigurationFilePath .\ConfigTemplate.xml -ComponentName BI
      

      The Initialize-Database.ps1 script maps the gMSA to the following databases and roles.

      User Database Database role
      svc-ReportSvc$ master db_owner
      svc-ReportSvc$ msdb db_datareader, db_datawriter, db_securityadmin

      The Configure-Database.ps1 script performs the following action:

      • Grant the CREATE ANY DATABASE permission to [contoso\svc-ReportSvc$].

    Note

    These scripts will not configure SSRS. SSRS will get configured during deployment by the Service Fabric service (ReportingService) deployed to that node.

    These scripts will, instead, grant the necessary permissions for the Service Fabric service (ReportingService) to carry out the necessary configuration.

Step 18. Configure AD FS

Before you can complete this procedure, AD FS must be deployed on Windows Server. For information about how to deploy AD FS, see Deployment Guide Windows Server 2016 and 2012 R2 AD FS Deployment Guide.

Finance + Operations requires additional configuration of AD FS, beyond the default out-of-box configuration. The following Windows PowerShell commands must be run on the machine where the AD FS role service is installed. The user account must have enough permissions to administer AD FS. For example, the user must have a domain administrator account. For complex AD FS scenarios, consult your domain administrator.

  1. Configure the AD FS identifier so that it matches the AD FS token issuer.

    This command is related to adding new users by using the Import users option on the Users page (System administration > Users > Users) in the Finance + Operations client.

    $adfsProperties = Get-AdfsProperties
    Set-AdfsProperties -Identifier $adfsProperties.IdTokenIssuer
    
  2. You should disable Windows Integrated Authentication (WIA) for intranet authentication connections, unless you've configured AD FS for mixed environments. For more information about how to configure WIA so that it can be used with AD FS, see Configure browsers to use Windows Integrated Authentication (WIA) with AD FS.

    This command is related to using forms authentication upon sign-in to the Finance + Operations client. Other options, such as single sign-on, are not supported.

    Set-AdfsGlobalAuthenticationPolicy -PrimaryIntranetAuthenticationProvider FormsAuthentication, MicrosoftPassportAuthentication
    
  3. For sign-in, the user's email address must be acceptable authentication input.

    This command is related to setting up email claims. Other options, such as transformation rules, might be available but require additional setup.

    Add-Type -AssemblyName System.Net
    $fqdn = ([System.Net.Dns]::GetHostEntry('localhost').HostName).ToLower()
    $domainName = $fqdn.Substring($fqdn.IndexOf('.')+1)
    Set-AdfsClaimsProviderTrust -TargetIdentifier 'AD AUTHORITY' -AlternateLoginID mail -LookupForests $domainName
    

Before AD FS can trust Finance + Operations for the exchange of authentication, various application entries must be registered under an AD FS application group in AD FS. To speed up the setup process and help reduce errors, you can use the Publish-ADFSApplicationGroup.ps1 script for registration. Copy this script and the D365FO-OP directory to a machine where the AD FS role service is installed. Then run the script by using a user account that has enough permissions to administer AD FS. (For example, use an administrator account.)

For more information about how to use the script, see the documentation that is listed in the script. Make a note of the client IDs that are specified in the output, because you will need this information in LCS later. If you lose the client IDs, sign in to the machine where AD FS is installed, open Server Manager, and go to Tools > AD FS Management > Application Groups > Microsoft Dynamics 365 for Operations On-premises. You can find the client IDs under the native applications.

Note

If you want to reuse your previously configured AD FS server for additional environments, see Reuse the same AD FS instance for multiple environments.

# Host URL is your DNS record\host name for accessing the AOS
.\Publish-ADFSApplicationGroup.ps1 -HostUrl 'https://ax.d365ffo.onprem.contoso.com'

Application group properties.

Finally, verify that you can access the AD FS OpenID configuration URL on a Service Fabric node of the AOSNodeType type. To do this check, try to open https://<adfs-dns-name>/adfs/.well-known/openid-configuration in a web browser. If you receive a message that states that the site isn't secure, you haven't added your AD FS SSL certificate to the Trusted Root Certification Authorities store. This step is described in the AD FS deployment guide. If you're using remoting, you can run the following command to install the certificate on all nodes in the Service Fabric cluster.

# If remoting, execute
.\Install-ADFSCert-AllVMs.ps1 -ConfigurationFilePath .\ConfigTemplate.xml

If you can access the URL, a JavaScript Object Notation (JSON) file is returned. This file contains your AD FS configuration, and it will indicate that your AD FS URL is trusted.

You've now completed the setup of the infrastructure. The following sections describe how set up your connector and deploy your Finance + Operations environment in LCS.

Step 19. Configure a connector and install an on-premises local agent

  1. Sign in to LCS, and open your on-premises implementation project.

  2. Select the Menu button (sometimes referred to as the hamburger or the hamburger button), and then select Project settings.

  3. Select On-premises connectors.

  4. Select Add to create a new on-premises connector.

  5. On the 1: Setup host infrastructure tab, select Download agent installer.

  6. After the zip file is downloaded, verify that it's unblocked. Select and hold (or right-click) the file, and then select Properties. In the Properties dialog box, select the Unblock checkbox.

  7. Unzip the agent installer on one of the Service Fabric nodes of the OrchestratorType type.

  8. After the file is unzipped, go back to your on-premises connector in LCS.

  9. On the 2: Configure agent tab, select Enter configuration, and enter the configuration settings. To get the required values, run the following command on any machine that has the infrastructure folder and up-to-date configuration files.

    .\Get-AgentConfiguration.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
    
  10. Save the configuration, and then select Download configurations to download the localagent-config.json configuration file.

  11. Copy the localagent-config.json file to the machine where the agent installer package is located.

  12. In a Command Prompt window, go to the folder that contains the agent installer, and run the following command.

    LocalAgentCLI.exe Install <path of config.json>
    

    Note

    The user who runs this command must have db_owner permissions on the OrchestratorData database.

  13. After the local agent is successfully installed, go back to your on-premises connector in LCS.

  14. On the 3: Validate setup tab, select Message agent to test for LCS connectivity to your local agent. When a connection is successfully established, you will receive the following message: "Validation complete. Agent connection established."

Step 20. Tear down CredSSP, if remoting was used

If you used any of the remoting scripts during setup, be sure to run the following command during breaks in the setup process, or after the setup is completed.

.\Disable-CredSSP-AllVMs.ps1 -ConfigurationFilePath .\ConfigTemplate.xml

If the previous remoting Windows PowerShell window was accidentally closed, and CredSSP was left enabled, this command disables it on all the machines that are specified in the configuration file.

Step 21. Deploy your Finance + Operations environment from LCS

  1. In LCS, open your on-premises implementation project.

  2. Go to Environment > Sandbox, and select Configure. To get the required values, run the following command on the primary domain controller VM. That VM must have access to ADFS and the DNS server settings.

    .\Get-DeploymentSettings.ps1 -ConfigurationFilePath .\ConfigTemplate.xml
    
  3. For new deployments, select your environment topology, and then complete the wizard to start your deployment.

    During the preparation phase, LCS assembles the Service Fabric application packages for your environment. It then sends a message to the local agent to start deployment. You should notice that the environment state is Preparing.

    Environment in a Preparing state.

  4. Select Full details to open the environment details page. Notice that the upper-right corner of the page shows the environment status as Preparing.

    Environment details page showing Preparing status.

    The local agent picks up the deployment request, starts the deployment, and communicates back to LCS when the environment is ready. When deployment is started, you should notice that the environment state is changed to Deploying.

    Environment in a Deploying state.

  5. Select Full details to open the environment details page. Notice that the upper-right corner of the page shows the environment status as Deploying.

    Environment details page showing Deploying status.

  6. If the deployment fails, the environment state is changed to Failed, and the Reconfigure button becomes available for the environment. Fix the underlying issue, select Reconfigure, update any configuration changes, and then select Deploy to retry the deployment.

    Reconfigure button for an environment in a Failed state.

    For information about how to reconfigure an environment, see Reconfigure environments to take a new platform or topology.

The following illustration shows a successful deployment. Notice that the upper-right corner of the page shows the environment status as Deployed.

Successfully deployed environment.

Step 22. Connect to your Finance + Operations environment

Known issues

When you run the New-D365FOGMSAAccounts cmdlet, you receive the following error message: "Key does not exist"

If you're creating and generating gMSA passwords in your domain for the first time, you must first create the Key Distribution Services KDS Root Key. For more information, see Create the Key Distribution Services KDS Root Key.

When you run the remoting script Configure-Prereqs-AllVms cmdlet, you receive the following error message: "The WinRM client cannot process the request"

Follow the instructions in the error message to enable the Allow delegation fresh credentials computer policy on all machines of the Service Fabric cluster.

When you Configure-Prereqs on servers of the MRType and ReportServerType types, you receive the following error message: "Install-WindowsFeature: The request to add or remove features on the specified server failed"

The .NET Framework version 3.5 is required on servers of the MRType and ReportServerType types. However, by default, source files for the .NET Framework version 3.5 aren't included in Windows Server 2016 installations. To work around the error, install the .NET Framework version 3.5. When you use Server Manager to manually add new features, specify the source files by using the source option.

When you run the Publish-ADFSApplicationGroup cmdlet, you receive the following error message: "MSIS7628: Scope names should be a valid Scope description name in AD FS configuration"

This error occurs because an OpenID allatclaims scope that D365FO-OP-ADFSApplicationGroup requires might be missing in some Windows Server 2016 installations. To work around the error, open Server Manager, go to Tools /> AD FS Management /> Service /> Scope Descriptions, and add the allatclaims scope description.

When you run the Publish-ADFSApplicationGroup cmdlet, you receive the following error message: "ADMIN0077: Access control policy does not exist: Permit everyone"

If AD FS is installed with a non-English version of Windows Server 2016, the Permit everyone access control policy is created in the local language. Invoke the cmdlet in the following way to specify the AccessControlPolicyName parameter.

.\Publish-ADFSApplicationGroup.ps1 -HostUrl 'https://ax.d365ffo.onprem.contoso.com' -AccessControlPolicyName '<Permit everyone access control policy in your language>'

Additional resources