NAV Team: How to: Set up your Microsoft Dynamics NAV installation for Single Sign-on with Office 365 using Windows PowerShell

[Blog bot]

// Copyright © Microsoft Corporation. All Rights Reserved.

// This code released under the terms of the

// Microsoft Public License (MS-PL, http://opensource.org/licenses/ms-pl.html.)

In our blog post How to: Validate that Microsoft Dynamics NAV 2013 R2 is correctly configured to support Single Sign-on with Office 365, we presented the Microsoft Dynamics NAV Best Practices Analyzer, a tool that you can use in order to validate your single sign-on (SSO) configuration of Microsoft Dynamics NAV. Not only does it validate your Microsoft Dynamics NAV and Windows Azure Active Directory (WAAD) configuration, it has another big advantage of assisting you in setting up your environment for SSO by providing meaningful and suggestive error messages which help you build your way through this lengthy process. The entire list of steps needed for setting up SSO with Office 365 in Microsoft Dynamics NAV is completely described in this how-to video.

In the previous paragraph I have just mentioned that this is a “lengthy process” which many times can become a rather unpleasant troubleshooting experience. We have collected this feedback and addressed this problem by providing the system administrators willing to set this environment up with a powerful Windows PowerShell cmdlet.

This cmdlet is called Set-NavSingleSignOnWithOffice365 and it can completely automate the process of configuring your Microsoft Dynamics NAV Web Client to support SSO with Office 365. For more information on the usage of this cmdlet and all the possible scenarios where its power can be leveraged, refer to the official Microsoft Dynamics NAV Help topic, which will be released with the next MSDN Library refresh: Walkthrough: Setting up your Microsoft Dynamics NAV installation for Single Sign-on with Office 365 using Windows PowerShell.

Note: The cmdlet can fully automate the configuration process provided that the needed parameters are specified when executing it. Generating and importing the security certificates that secure the Client – Server communication channel is performed separately and is subject to another upcoming topic with the next MSDN Library refresh: How to: Create a Self-signed Security Certificate Using PowerShell Script.

In the following section, you will find information about setting up your Microsoft Dynamics NAV installation for single sign-on with Office 365 using Windows PowerShell.


Setting up your Microsoft Dynamics NAV Installation for Single Sign-on with Office 365 using Windows PowerShell
Microsoft Dynamics NAV supports federated user authentication with Windows Azure Active Directory (Windows Azure AD). This is the Identity Provider service used by Office 365. As a matter of fact, every time a new Office 365 subscription is provisioned, the Windows Azure AD tenant for this subscription is also created. Thus, when Microsoft Dynamics NAV is configured for federated authentication with a WAAD tenant, a single sign-on (SSO) user experience is achieved between Microsoft Dynamics NAV and the Office 365 Web Applications and any other applications that leverage the single sign-on capability provided by the Windows Azure AD tenant.

The Set-NavSingleSignOnWithOffice365 cmdlet can help you perform this configuration task by automating all the steps of this process. To sum up, this cmdlet performs the following operations:

1. It first validates that both your Microsoft Dynamics NAV Server and Microsoft Dynamics NAV Web Server are ready for this change.
2. It validates that your Office 365 credentials are valid.
3. Once the validation steps are performed, the cmdlet starts the configuration:
   1. It links your Microsoft Dynamics NAV User account to your Office 365 account by providing your Office 365 email address as the AuthenticationEmail for the Microsoft Dynamics NAV User account.
   2. It configures the Microsoft Dynamics NAV Server by changing the values of the following configuration settings: ClientServicesFederationMetadataLocation, ClientServicesCredentialType and ServicesCertificateThumbprint.
   3. It configures the Microsoft Dynamics NAV Web Server by changing the values for the following configuration settings: ClientServicesCredentialType, ACSUri and DnsIdentity.
   4. It configures the WAAD tenant by creating a Service Principal that represents the Microsoft Dynamics NAV Web Client.
4. If any of the configuration sub-steps of step 3 fail, the cmdlet reverts all the changes made to your Microsoft Dynamics NAV Server and Web Server up until that point.

Prerequisites

• Office 365 subscription
  If you already have your Office 365 subscription, you can ignore this step. Otherwise, sign up for a free trial Office 365 plan. We recommend that you use a plan such as Office 365 Enterprise E1 as your test site, or that you sign up for a trial developer plan. A trial plan includes an administrative account whose credentials you will need to provide for the WAAD configuration. 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 your system:Microsoft Online Services Sign-In Assistant for IT Professionals
  
  Windows Azure Active Directory Module for Windows PowerShell
  
  You can download and install these components from the links provided above. If you have to choose between 32-bit and 64-bit versions of components, then download the version that matches your Windows Operating System type. To determine the operating system type, open File Explorer, and then choose This PC in the navigation pane. On the ribbon, in the System group, choose System properties. The operating system type appears next to System type in the System section.
• Microsoft Dynamics NAV user account
  You have to have a valid NAV user account. For more information, see How to: Create Microsoft Dynamics NAV Users in the MSDN Library.
• Microsoft Dynamics NAV environment
  Setting up SSO requires that you have both the Microsoft Dynamics NAV Server and Web Server installed.
• Security Certificate Used to Secure the Server – Web Server Communication Channel
  Setting up user authentication types other than Windows for the Microsoft Dynamics NAV environment requires securing the Server – Client (or Web Server in this case) communication. This can be done using a security certificate. The Set-NavSingleSignOnWithOffice365 cmdlet assumes that you have already imported the security certificate in your certificate store. You can either use a security certificate issued by a trusted certificate authority (see Walkthrough: Implementing Security Certificates in a Test Environment) or you can use a self-signed certificate (see How to: Configure User Authentication for the Microsoft Dynamics NAV Web Client). The latter approach is not recommended in a production environment; however, it is an alternative to consider when testing your environment.

Importing the Automated Configuration Module
In order to run the Set-NavSingleSignOnWithOffice365 cmdlet, you first need to open Windows PowerShell as an administrator. This can be done by right-clicking on the Windows PowerShell program and choosing “Run as administrator”.

Then navigate to your Microsoft Dynamics NAV DVD, then to the WindowsPowerShellScripts NAVOffice365Administration folder.

Next, run the following cmdlet in order to import the NAVOffice365Administration PowerShell module:

Import-Module .NAVOffice365Administration.psm1


Automating the Single Sign-on Configuration in a One-Computer Microsoft Dynamics NAV Environment
Once the prerequisites are fulfilled and the Office 365 Administration module is imported, the sufficient condition for setting up SSO with Office 365 is satisfied by simply running the Set-NavSingleSignOnWithOffice365 cmdlet with the following parameter set on the computer that hosts the Microsoft Dynamics NAV components:

Set-NavSingleSignOnWithOffice365-NavServerInstance “ServerInstanceName” -NavWebServerInstanceName “WebServerInstanceName” -NavUser “YourNavUser” -AuthenticationEmail “YourOffice365Email” -NavServerCertificateThumbprint “SecurityCertificateThumbprint”

ServerInstanceName represents the name of your Microsoft Dynamics NAV Server instance. You can find the names for the Microsoft Dynamics NAV Server instances running on your computer by running the Get-NAVServerInstance cmdlet.

WebServerInstanceName represents the name of your Microsoft Dynamics NAV Web Server instance. You can find the names for the Microsoft Dynamics NAV Web Server instances running in your IIS by running the Get-NAVWebServerInstance cmdlet.

YourNavUser represents the name of your NAV User account.

YourOffice365Email represents the email address of your Office 365 User account. It is in the form username@o365tenant.onmicrosoft.com. This user should have administrative privileges.

SecurityCertificateThumbprint represents the thumbprint for the security certificate used for securing the Client – Server communication channel. For more information, refer to the “Prerequisites” section of this article. You can get the list of thumbprints for your certificates by issuing this Windows PowerShell command:

Get-ChildItem -Path "Cert:LocalMachineMy"

Note: You can avoid providing this parameter if you already have your Microsoft Dynamics NAV Server configured with a security certificate. This applies to Microsoft Dynamics NAV installations in the Windows Azure environment, and other environments where any credential type other than Windows is active and functional.

Once 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 Web Server are on different computers. This means that you need 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 SSO with Office 365.


Running the cmdlet on the Microsoft Dynamics NAV Server computer
To configure your Microsoft Dynamics NAV Server for SSO, you need to run the cmdlet with the following parameter set:

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

Notice the SkipWebServerConfiguration switch, which specifies that the Microsoft Dynamics NAV Web Server components should not be configured at all.


Running the cmdlet on the Microsoft Dynamics NAV Web Server computer
To configure your Microsoft Dynamics NAV Web Server for SSO, you need to run the cmdlet with the following parameter set:

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

Notice the SkipNavServerConfiguration switch, which specifies that the Microsoft Dynamics NAV Server should not be configured at all.


Additional Remarks and Considerations
Running the cmdlet fails because the NAV Server fails to start / restart

You can find more information about the Microsoft Dynamics NAV Server failure reason in the event log. This error most likely occurs because of the impossibility of the Microsoft Dynamics NAV Server to properly configure the ACL for the ports used by the server’s communication endpoints. In some situations, when there are URLACL entries for the same ports but reserved by other services (including other installed Microsoft Dynamics NAV Servers), the removal procedure fails because of insufficient privileges. The user account running the Microsoft Dynamics NAV Server needs to have administrative permissions for the modification of the URLACL to succeed. That is why, in order to overcome this issue, you can try one of the following:

1. Remove the URL ACL entries manually (see Walkthrough: Configuring Web Services to Use SSL (SOAP and OData) for more information) or
2. Set your Microsoft Dynamics NAV Service to run as on Administrator account on your computer.

Running the cmdlet in a multitenant Microsoft Dynamics NAV environment

Only one tenant can be automatically configured at a time, so the Microsoft Dynamics NAV Tenant name needs to be provided as the NavTenant parameter to the Set-NavSingleSignOnWithOffice365 cmdlet.

Avoiding the Office 365 Credentials dialog box

You can fully automate the script, and thus avoid the Office 365 Credentials dialog box by providing the credentials as parameters:

You use the AuthenticationEmail parameter to specify the Office 365 account email and the AuthenticationEmailPassword parameter to specify the Office 365 account password. Be aware that the latter parameter should be a SecureString.

Running the cmdlet for a Microsoft Dynamics NAV Web Server that is hosted in complex network topology

Setting the trust relationship between the Microsoft Dynamics NAV Web Client and Windows Azure AD requires specifying a remote endpoint for the Microsoft Dynamics NAV Web Client in the Windows Azure AD Service Principal that is created for this web application.

If the Microsoft Dynamics NAV Web Server runs behind a DNS or another network component that changes / rewrites the Web Client’s address, the Set-NavSingleSignOnWithOffice365 cmdlet is not able to compute this address, since it only runs on the local computer.

You can overcome this situation by providing the cmdlet the address as seen remotely for your Microsoft Dynamics NAV Web Client. The parameter you need to pass this address to is NavWebAddress.



Best regards

The Microsoft Dynamics NAV Office 365 team.



Источник: http://feedproxy.google.com/~r/Micro...owershell.aspx