How to: Set up Microsoft Dynamics NAV for Single Sign-on With Office 365 using Windows PowerShell

Microsoft Dynamics NAV supports federated user authentication with Microsoft Azure Active Directory (Azure AD). This is the Identity Provider service that is used by Office 365. Every time a new Office 365 subscription is provisioned, the Azure AD tenant for this subscription is also created. Thus, when Microsoft Dynamics NAV is configured for federated authentication with an Azure AD tenant, a Single Sign-on (SSO) user experience is achieved between Microsoft Dynamics NAV and the Office 365 Web Applications or/and any other applications which use the Single Sign-on capability provided by the Azure AD tenant.

The Set-NavSingleSignOnWithOffice365 cmdlet also supports enabling Office 365 account authentication both for Microsoft Dynamics NAV Web client and for Microsoft Dynamics NAV Windows client. Office 365 authentication is described in this topic for both clients.

The Set-NavSingleSignOnWithOffice365 cmdlet can be used to perform the configuration task by automating all the steps of this process. The cmdlet performs the following operations:

• It validates that both your Microsoft Dynamics NAV Server and Microsoft Dynamics NAV Web Server components are ready for this change.

• It validates your Office 365 credentials.

• Once the validation is over, the cmdlet starts the configuration:

  • It links your Microsoft Dynamics NAV user account to your Office 365 provided account by providing your Office 365 email address as the AuthenticationEmail for the provided Microsoft Dynamics NAV user account.

  • It configures the Microsoft Dynamics NAV Server by changing the values of the following configuration settings: ClientServicesFederationMetadataLocation, ClientServicesCredentialType, and ServicesCertificateThumbprint.

  • It configures the Microsoft Dynamics NAV Web Server components by changing the values for the following configuration settings: ClientServicesCredentialType, ACSUri, and DnsIdentity.

  • It configures the Azure AD tenant by creating a Service Principal that represents the Microsoft Dynamics NAV Web Server components.

If the configuration sub steps fail, the cmdlet reverts all of the changes in the sub steps made to the Microsoft Dynamics NAV Server and Microsoft Dynamics NAV Web Server components.

To follow this how-to, you will need:

• Microsoft Dynamics NAV with a user account. For more information, see How to: Create Microsoft Dynamics NAV Users

• Microsoft Dynamics NAV Server

• Microsoft Dynamics NAV Web Server components

• An Office365 subscription

  If you want to sign up for an Office 365 plan, you can use a plan such as Office 365 Enterprise E1 as your test site, or sign up for a trial developer plan. A trial plan includes an administrative account which you will use to access the Azure management portal. For example, if your Office 365 site is Solutions.onmicrosoft.com, your administrative account can be admin@solutions.onmicrosoft.com. For more information, see Select an Office 365 plan for business.

• Azure Active Directory Tenant Management Components

  The cmdlet relies on the presence of the following components on the system:

  • Microsoft Online Services Sign-In Assistant for IT Professionals

  • Microsoft Azure Active Directory Module for Windows PowerShell

  You can download and install these components from the links provided earlier in this section. If you have to decide between 32-bit and 64-bit versions of components, download the version that matches the Windows Operating System type.

• Security Certificate Used to Secure the Server – Web Server Communication Channel

  Setting up user authentication types other than Windows for the Microsoft Dynamics NAV Development Environment requires securing the communication between the server and the client. This can be done by using a security certificate. The Set-NavSingleSignOnWithOffice365 cmdlet assumes that you have already imported the security certificate in your certificate store. You can use a security certificate issued by a trusted certification authority. For more information, How to: Implement Security Certificates in a Production Environment. You can also use a self-signed certificate. For more information, see Walkthrough: Implementing Security Certificates in a Test Environment. We do not recommend the latter approach in a production environment; however, it is an alternative to consider when testing your environment.

To Import the NAVOffice365Administration Module

1. Open Windows PowerShell as administrator, by right-clicking the program and selecting Run as administrator.

2. Navigate to your Microsoft Dynamics NAV DVD, and then to the WindowsPowerShellScripts\NAVOffice365Administration folder.

3. Run the following cmdlet in order to import the NAVOffice365Administration PowerShell module: Import-Module .\NAVOffice365Administration.psm1.

When you have imported the NAVOffice365Administration module, you can now run the Set-NavSingleSignOnWithOffice365 cmdlet on the computer that hosts the Microsoft Dynamics NAV components with the relevant parameters set.

To Automate the Single Sign-on Configuration in a One-Computer Microsoft Dynamics NAV Environment

1. In Windows PowerShell, at the prompt, enter Set-NavSingleSignOnWithOffice365 -NavServerInstance “ServerInstanceName” -NavWebServerInstanceName “WebServerInstanceName” -NavUser “YourNavUser” -AuthenticationEmail “YourOffice365Email” -NavServerCertificateThumbprint “SecurityCertificateThumbprint”. See the table below for a description of parameters.

   Parameter Name	Description
   ServerInstanceName	Specifies the name of your Microsoft Dynamics NAV Server instance. To find the names for the Microsoft Dynamics NAV Server instances, run the Get-NAVServerInstance cmdlet
   WebServerInstanceName	Specifies the name of your Microsoft Dynamics NAV Server instance. To find the names for the Microsoft Dynamics NAV Web client instances running in your IIS, run the Get-NAVWebServerInstance cmdlet.
   YourNavUser	Specifies the name of your Microsoft Dynamics NAV user account. YourNavUser links the Microsoft Dynamics NAV user account to your Office 365 account by providing your Office 365 email address as the AuthenticationEmail for the provided Microsoft Dynamics NAV user account. This parameter is optional.
   YourOffice365Email	Specifies the email address of your Office 365 user account. The syntax is username@o365tenant.onmicrosoft.com. This parameter is optional. Important This user must have administrative permissions, such as the Global Administrator role. If you create a custom administrator role for this account, the account must have permission to create service principals in Azure. For more information, see Assigning admin roles.
   SecurityCertificateThumbprint	Specifies the thumbprint for the security certificate that was used for securing the client–server communication channel. Get the list of thumbprints for your certificates by issuing this Windows PowerShell command: Get-ChildItem -Path "Cert:\LocalMachine\My" Note You can avoid providing this parameter if you already have your Microsoft Dynamics NAV Server configured to use a security certificate. This applies to Microsoft Dynamics NAV installations in the Azure environment, and other environments where any credential type other than Windows is active and functional.

2. When the Set-NavSingleSignOnWithOffice365 cmdlet is run, a dialog box will open, requesting your Office 365 account user name and password.

Automating the Single Sign-on Configuration in a Multi-Computer Microsoft Dynamics NAV Environment

This configuration type assumes that your Microsoft Dynamics NAV Server and Microsoft Dynamics NAV Web Server components are on different computers. This means that you have to run the Set-NavSingleSignOnWithOffice365 cmdlet on each of these computers separately with a different parameter set in order to correctly configure your Microsoft Dynamics NAV Web client for single sign-on with Office 365.

To automate single sign-on configuration in a multi-computer Microsoft Dynamics NAV environment

1. Run the Set-NavSingleSignOnWithOffice365 cmdlet on the Microsoft Dynamics NAV Server computer.

2. To configure your Microsoft Dynamics NAV Server for single sign-on, you have to run the cmdlet with the following parameter set:

   Set-NavSingleSignOnWithOffice365 -NavServerInstance “ServerInstanceName” -NavUser “YourNavUser” -NavServerCertificateThumbprint “SecurityCertificateThumbprint” –SkipWebServerConfiguration -SkipWinClientConfiguration
   

   Note

   The SkipWebServerConfiguration switch specifies that the Microsoft Dynamics NAV Web client configuration should not be generated.

3. Run the Set-NavSingleSignOnWithOffice365 cmdlet on the Microsoft Dynamics NAV Web Server components computer

4. To configure your Microsoft Dynamics NAV Web Server components for single sign-on, you have to run the cmdlet with the following parameter set:

   Set-NavSingleSignOnWithOffice365 -NavWebServerInstanceName “WebServerInstanceName” -AuthenticationEmail “YourOffice365Email” –SkipNavServerConfiguration -SkipWinClientConfiguration
   

   Note

   The SkipNavServerConfiguration switch specifies that the Microsoft Dynamics NAV Web client configuration should not be generated.

To Enable Office 365 Account Authentication for Microsoft Dynamics NAV Windows client

The Set-NavSingleSignOnWithOffice365 can be also used to perform most of the configuration steps necessary for enabling user authentication with Office 365 accounts for Microsoft Dynamics NAV Windows client. The example in this section only configures the Microsoft Dynamics NAV Service and the Azure AD tenant in order to enable Office 365 authentication for the Microsoft Dynamics NAV Windows client.

$result = Set-NavSingleSignOnWithOffice365 -AuthenticationEmail “YourOffice365Email” –SkipNavWebServerConfiguration -SkipNavServerConfiguration

Note

The SkipNavWebServerConfiguration switch specifies that the Microsoft Dynamics NAV Server should not be configured. The SkipNavServerConfiguration switch specifies that the Microsoft Dynamics NAV Web Server components should not be configured.

Because this cmdlet is usually run on the computer that is hosting the Microsoft Dynamics NAV service, the value returned by the cmdlet, which in this case is the sign-in page, must be copied and pasted in the ACSUri setting from the ClientUserSettings.config file.

Important

When setting ACSUri in the ClientUserSettings.config file, make sure that the ClientServicesCredentialType is set to AccessControlService.

Adjusting the Client User Settings

To make sure that the account authentication for the Microsoft Dynamics NAV Windows client works correctly, the ClientUserSettings.Config file needs two settings to be of a specific type. The default location for the ClientUserSettings.Config file is C:\Users\<username>\AppData\Roaming\Microsoft\Microsoft Dynamics NAV\90. For more information, see Configuring the Windows Client.

The ClientServicesCredentialType must be set to AccessControlService.

Depending on the Security Certificate that you are using, you may also need to change the DnsIdentity setting. For more information, see How to: Implement Security Certificates in a Production Environment.

AcsUri should have the following format https://login.windows.net/<tenant>/wsfed?wa=wsignin1.0%26wtrealm=<realm>%26wreply=<reply>.

Note

The difference between configuring the Microsoft Dynamics NAV Web client and Microsoft Dynamics NAV Windows client for single sign-on with Office 365 is the addition of the wreply parameter in the URL. The Microsoft Dynamics NAV Web client automatically sets the wreply parameter to the web site login page, whereas the Microsoft Dynamics NAV Windows client requires that it is preconfigured.

Tip

Use the Set-NavSingleSignOnWithOffice365 PowerShell script to get the AcsUri for Azure AD by running the following statement: Set-NavSingleSignOnWithOffice365 -SkipNavServerConfiguration -SkipWebServerConfiguration

To change the client user settings in a ClickOnce environment, see Deploying Microsoft Dynamics NAV Using ClickOnce.

See Also

Tasks

Troubleshooting: Running the Cmdlet Fails Because the Microosft Dynamics NAV Server Fails to Start/Restart
Troubleshooting: Running the Cmdlet in a Multitenant Microsoft Dynamics NAV Environment
Troubleshooting: Avoiding the Office 365 Credentials Dialog box
Troubleshooting: Running the Cmdlet for a Microsoft Dynamics NAV Web Server Hosted in Complex Network Topology

Concepts

Authenticating Users with Azure Active Directory