Creating an Enterprise Portal site with Forms-Based Authentication AX 2012

This article will cover some of the challenges that you can come across while attempting to deploy a Claims-aware Enterprise Portal site with forms-based authentication. 

Here are 2 great links you need to use with some discrepancies on some of the instructions relating to Self-Signed Certs. which I will detail out in this article. Also, I have included some tips on how to overcome some errors you might run into.  

Below is a great Technet document that describes step by step on how to setup your environment to support an EP site with forms-based authentication.  

The steps in this document are all you need if you want to give access to employees of the organization access to the EP site from outside the company. If you want to grant access to non-employees, you will also have to follow the instructions in the second link.  

https://technet.microsoft.com/en-us/library/dd361998.aspx 

Below is a great Technet document that describes step by step on how to setup a claims-aware site with form-based authentication. 

The form-based authentication allows users to access content on the EP site without needing accounts setup on your Active Directory. This protects your systems from vulnerabilities. You can create users outside the network and give them access to specific area’s in EP.  

https://technet.microsoft.com/en-us/library/hh575253.aspx 

Important & Notes sections: 

Make sure you read these sections as your going through the steps. There are very helpful tips in them.   

People you will need before you start: 

If you are not the Windows Server Engineer for your organization, you will need one assigned to this project.  

If you are not the Network/Security Engineer in control of firewalls in your organization, you will need one assigned to this project.  

If you are not the AX Administrator for your organization, you will need one assigned to this project. 

If you don’t have access to your SQL server that the aspnetdb will reside on. You will need the DBA who has access to the server.  

If you have a SharePoint/ IIS admin, this person could help you al lot as well 

Problems or errors that might come up:  

Error new-AXClaimsAwareEnterprisePortalServer : Object reference not set to an instance of an object. 

Error: The Web site http://XXX:yyy/sites/DynamicsAx was not created correctly. 

Error Could not load file or assembly 'Microsoft.Dynamics.SyncServices.Library, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. The system cannot find the file specified. 

Make sure you have SharePoint 2013 SP1 Re-release Version: 15.0.4571.1502 KB2880552 

Link to Share Point Build Numbers and Download Links: 

https://buildnumbers.wordpress.com/sharepoint/ 

Make sure your business connector configuration is pointing to the correct environment 

Make sure target environment is fully compiled and CIL generated with no errors 

Make sure the Business Connector account is part of the farm administrator group 

Make sure that the account you are logged on to the server with and the Business connector account is in the Local Admin Group.  

Make sure the account you are logged on to the server with is also in the farm administrator group 

Make sure the Business connector account has db_owner rights on asp.net database under membership.  

Error new-AXClaimsAwareEnterprisePortalServer : Exception has been thrown by the 

target of an invocation. 

These errors are very generic, most of the time they can be resolved by making sure AX compiles & CIL Generation are completing with no errors.  

If you have compiled and generated a full CIL with no errors but still get error Error new-AXClaimsAwareEnterprisePortalServer : Exception has been thrown by the target of an invocation.  

Make sure the 3 Share Point sites are started in IIS. Now you can run your new-AXClaimsAwareEnterprisePortalServer command without errors. 

Error New-AXUser : The entry 'FormsAuth' has already been added. (C:\Program Files\Common Files\Microsoft Shared\Web Server.  

Delete or rename the file C:\Windows\System32\WindowsPowerShell\v1.0\powershell.config if it exists. This will resolve the error.  

Error when you authenticate to the forms-Auth site you get Server Error in '/' Application. 

Check your event viewer for ASP.NET errors for example: Event 1309, ASP.NET 4.0.30319.0.  or

ID4220 SAML Assertion is either not signed or the signature's KeyIdentifier cannot be resolved to a SecurityToken

If you see this error that means your Signing cert to establish trust between EP and forms-based site is not configured properly. Make sure you are creating the cert from a Visual Studio thats connected to the instance of AX you are trying to deploy EP to.  

If you know you created the cert from the right Visual Studio server. run?Get-SPTrustedIdentityTokenIssuer SharePoint PowerShell command on SharePoint server. To check the Serial numbers and compare to the <string>.cer cert you copied to your EP site on C:\Certs folder. Double Click the cert to open it, Click Details. If the Serial Numbers doesn’t match. Follow instructions below.  

Run SharePoint Powers Shell command  

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(“C:\certs\<string>.cer”) 

$sts = Get-SPTrustedIdentityTokenIssuer 

$sts | Set-SPTrustedIdentityTokenIssuer -ImportTrustCertificate $cert 

This will resolve your issue.  

If you are unable to brows to the site using the friendly name. This is related to not adding an Alternate Access Mapping on SharePoint. See instructions below.  

Creating Alternate Mapping on SharePoint 2013 SP1 Rerelease Ver. 15.0.4571.1502 

Click Application Management > Click Configure alternate access mapping > Click Edit Pblic URLs > Select your EP site from Alternate Access Mapping Collection > Inter in your Friendly name followed by the port number. Example: Https://Portal.Contoso.com:8088 Note, if you used port 443 you don’t need the port number after the URL.  

Errors in the instructions:  

On the second link that gives you the steps to Deploy an Enterprise Portal site that uses forms-based authentication [AX 2012] I found a few errors. In the section Create a signing certificate to establish trust between the Enterprise Portal site and the forms-based site, Option B: Visual Studio is not installed on the Enterprise Portal server.  

I found that steps 12 is not correct. The cert is not placed into Trusted Root Certification Authorities > Certificates node. Once you execute the command makecert.exe on the Visual Studio. It is just put on the C:\Certs folder named with what you specified in c:\certs\<string>.cer and into the Personal > Certification node. You can continue to step 13, just do it from Personal > Certification node.

A few other issues are in Import the certificate to the Enterprise Portal server section. Step 8 says to Right-click Trusted Root Certification Authorities, and then click All tasks\Import. When you do this its looking for a .cer file extension which doesn’t exist on the server. Per the instructions you have only copied over the .pfx file. Furthermore, when you get to the Create a forms-based Security Token Service site section. Step 4 asks you to execute the SigningCert = Get-PfxCertificate c:\certs\<string>.cer command in Dynamics AX management Shell, but per the instructions you haven’t moved the .cer file over to the External EP server yet.  

FYI, I attempted to do this using the .pfx cert. and just changing the extension to .pfx in the Create a forms-based Security Token Service site section. On step 4 SigningCert = Get-PfxCertificate c:\certs\<string>.cer and the site didn’t work. It wouldn’t authenticate when logging on through Forms-Auth. I kept getting Error in '/' Application, which I have listed the SharePoint Power Shell commands above on how to resolve.  

So, my workaround to this went like this. since the .cer cert is already on the C:\Certs\<string>.cer on your Visual Studio server, you can just copy that .cer file and paste it on the External EP Server on C:\Certs along with the .pfx cert.

Now move to the Import the certificate to the Enterprise Portal server section.

From here on follow the instructions all the way through!  

The way the site Works: 

From the internet you go to the EP portal URL Example: https://Portal.Contoso.com this will rout you to the asp.net Forms-authentication web site.  Here users can select between Windows Authentication or FormAuth to authenticate to the site. 

If the user selects FormsAuth method for authentication. They get the screen below. Here they will put the username and password created for them in asp.net forms-authentication.  

You create asp.net forms-based authentication user accounts by executing the command below in MS Dynamics Ax 20102 Management Sell  

New-AXUser -AccountType ClaimsUser -AXUserId jdd -UserName johndoe -UserDomain FormsAuth -CreateInProvider -ClearTextPassword "Yukon!!90"  

Details are in the instructions Create a new user for forms-based authentication section of the Deploy an Enterprise Portal site that uses forms-based authentication [AX 2012] Technet document.  

If the user selects Windows Authentication.  They get the screen below. They use the AD credentials created for them. Same credentials they use to authenticate to the AX environment.   

Once authenticated they are routed back to the EP site.