Dynamics AX Enterprise Portal in a Farm - The rest of the story

by Ed Sparks

Updated for SharePoint 2013 

From time to time we work with customers to get their Dynamics AX Enterprise Portal ("EP") working correctly in multi-tier production SharePoint environments. Additionally many times an external vendor or customer portal site is a separate requirement. 

One quickly discovered this was not a well documented or easy task, as Microsoft seems to think everyone will just blindly deploy these products using the wizard defaults onto a blank SharePoint Foundation install on the AX server itself.  For something called "Enterprise Portal" that's a sad and hilarious oversight.  To make matters worse, the AX Installer is a train wreck. Even the tiniest of anomalies anywhere, on any of the layers of servers will cause the installation to fail and roll back.  It's a highly frustrating experience for administrators experienced and not.  The complete clean-sheet rewrite of AX is long overdue. We digress.

As the out of the box option isn't scalable or supportable, we decided to investigate and create a proper reproducible way to install EP into a SharePoint Enterprise environments. 

As part of Dynamics AX, the Enterprise Portal provides a web-based dashboard of AX data including user self-service, customer and vendor portals.  It consists of a reasonably stock SharePoint site that is deployed into any existing Web Application with a large number of custom web parts, and hooks into code on the AX server.  It authenticates with and accesses all of the AX data via a "Business Connector Proxy."  This .NET AX BCP account has a high level of permissions in AX, and then separately gets the information for the user who is accessing SharePoint and passes that along to AX for the appropriate role and access permissions.

General

Here are the required install steps.  These must be followed particularly closely in regards to accounts and permissions, or the EP install will consistently fail and roll back.   Other issues you may encounter include the installer not "finding" your AO server or SharePoint Web Applications.

If you are using SharePoint 2013, ensure you are running Dynamics AX 2012 R2 or R3 with up to date Cumulative Updates slip-streamed into the installer.  Review the following article and slipstream the required patches:   Enterprise Portal on Microsoft SharePoint 2013

Accounts

You must create and pay special attention to two Active Directory accounts:
The "Install Account" - must be a SharePoint Farm Admin (and ideally local admin during the setup process itself), and a user configured in AX with the "System Administrator" role.  Yes, seriously.

The "Proxy Account" (also known as the ".NET Business Connector Account")  - this must be configured as a Managed Account in SharePoint, and is used as the Application Pool account for the SharePoint Web Application.  It must also be defined in the Dynamics AX configuration under System Administration > Setup > System > System service accounts.  

Create these accounts ahead of time, and double check the permissions.  We recommend you also temporarily add the Install Account to the local Administrators group on each of your SharePoint servers.   

The Steps

ON THE SHAREPOINT SERVER HOSTING CENTRAL ADMIN SITE:
In a Farm, the first install of EP MUST BE DONE ON THE CENTRAL ADMIN SERVER.

  1. Log into the server as the Install Account user (defined above)
  2. Ensure this server is running Central Admin AND the SharePoint Foundation Web Application service is started and running.  (only required during install) 
  3. Create a new Web Application that will host EP.  
  4. We recommend doing this from the SP Shell using the New-SPWebApplication command in order to specify your settings, accounts and database names cleanly. Alternatively do this through Central Admin.  For the Application Pool identity, be sure to use the AX BC Proxy Account created earlier.  
    Be sure to use Windows Authentication (or Claims/Windows on SP 2013)
    This will create the new Web Application and appropriate content and config databases on the SQL server.
  5. We must now discuss host names/headers.  The EP Installer will break (surprise!) if there is a host header used in IIS.  If you wish to use a host name for EP (so that users may go to http://AXEP for example, instead of http://SPSERVER2013) then you must make sure to add the host header AFTER the EP install.  Ideally you don't want to install EP into an existing web application, so this makes it another frustrating step to take, as you can't use a host header, but you are likely sharing IPs on your server.  
    We often recommend creating a web application on a different port, then change after the fact, or assign an additional IP address to your SharePoint server that can be dedicated to the host name that will be used for EP.  Make sure your web application and AAMs are all using the right names, and nothing is shared with your other web applications.  
    Clear any host headers in IIS Admin, and change your Alternative Access Mappings     before continuing.

ON THE APPROPRIATE SQL DB INSTANCE:
Special permissions need to be assigned in order for the EP installer to complete successfully.  Be sure you are using the correct databases for the New Web Application - keeping in mind the strange GUID names SharePoint loves to use for databases if you used Central Admin.
The Install Account must be assigned to the DBO role on several of the databases – the SharePoint Config database and its related AdminContent database, and the web application Content database.   Using the Add-SPShellAdmin command is a good way to add these users in from SharePoint in a supported way.  Alternatively, check them on the SQL Server in SQL Manager.  

FAILURE TO ASSIGN THESE EXACT PERMISSIONS WILL OFTEN BREAK THE EP INSTALL PROCESS AND CAUSE THE EP INSTALLER TO ROLL BACK THE INSTALL.  Over, and over.

BACK ON THE SERVER HOSTING CENTRAL ADMIN SITE:

  1. Login as the Install Account user
  2. Slipstream any patches into the Updates folder of the AX Source, then run the AX Setup program
  3. Choose to use Microsoft Update, and select the Custom Install type
  4. Under Select Components, choose to install only Enterprise Portal.  Run through the various steps to install the pre-requisites either by choosing the Configure check boxes or via the installer download links
  5. At the AX Configuration Settings page, choose to store the AX AOS configuration in the Registry , or load from a saved config if you have these from your AX deployment/servers
  6. Enter/confirm the name of the AX AOS server as per the environment that is being connected to.
    AOS SERVER NAME NOTE: The installer is fussy about name resolution for the AOS server as well.  It appears to not respect fully qualified names, so they single name of your server MUST be resolvable via DNS or HOSTS file.  (i.e. AOS1.domain.internal vs AOS1.  If AOS1 won't resolve, the installer will fail)
  7. Choose the correct Web Application from the list.  This should NOT be your normal SharePoint site, Central Admin or the Web Services site, but the new one you created.  In addition, you can choose to create the site at the / (root) site or under /sites/DynamicsAX.  We recommend the root site, as the rest seems redundant and more for the users to remember
    The installer will configure a new site collection and install various web parts. 
  8. On the final page of the installer take note of the options to restart IIS if this will interrupt other SharePoint tasks on the server, so uncheck if necessary
  9. After IIS is restarted, load the new EP portal once, and ensure it connects to AX by browsing to http://<web application host name> or http://<web application host name>/sites/DynamicsAX.  This MUST be done once on the first server to initialize the components properly
  10. Only continue after the EP site loads correctly

ON EACH ADDITIONAL WFE SERVER: 

  1.  Repeat steps 1 – 9 from above on each Web Front-end Server, but choose NOT to Configure SharePoint or create a new site collection by unchecking the appropriate boxes.  This will just install the required files and features into the WFE server
  2. Test access to the EP site via each WFE

Permissions

Another source of confusion after EP is setup, is how to assign permissions to users to actually access their EP site, Role Centers or Vendor Portal.

It is important to note that you must assign SharePoint permissions through the Site Settings links while logged into the appropriate EP site as a Site Collection Administrator.  After the initial install, this is often only assigned to the Install Account.  Generally, we recommend that you Grant an Active Directory Group with the level of access such as Read or Contribute.  

Reference: https://technet.microsoft.com/en-ca/library/dd361998.aspx#users

Until you have granted these SharePoint permissions, nobody will be able to access the Enterprise Portal regardless of their AX Permissions!

Once the SharePoint Permissions are granted, then add or confirm users in AX to ensure they are assigned the appropriate roles and permissions, and this will automatically define what parts of the overall Enterprise Portal site they can see and access.

Still stuck?  Give us a call or email for help - particularly if you're trying to setup an external Vendor or Client Portal in a DMZ or with domain trusts.  This is beyond the scope of this article, but we'd be happy to help!