How to setup claim based site on EP in AX2012

Alright. In last post, I jot down the steps to setup public portal on EP. In this post, I’ll extend it for those who wants to setup claim-aware (or secure site if you will) on top of that. The process of setting up claim based site on Enterprise Portal is specifically for AX2012 R2/R3. At the time of writing, the process is manual for the most part. We are looking at some ways to automate it (or some part of it) in near future.

Pre-Requisites and assumptions:

1. The SharePoint foundation 2010 or 2013 has already been installed and configured on the box.
2. The regular EP site must be installed and deployed. (refer to TechNet article for EP installation)
3. Admin access to Azure subscription.
4. Live/Google/Yahoo account for logging in as a claim-user.
5. This document uses the localhost address, and therefore the same machine must act as both server and client

Claim-aware EP sites 

Claim-aware or ACS enabled EP site are secured (HTTPS) SharePoint applications which the registered claim-based AX users can access outside of the Domain environment. This provides another way of authentication to AX other than the traditional active directory based domain users. If properly configured in conjunction with Windows Azure enabled services, an organization implementing AX, can offload the authentication mechanism to other third party Identity providers such as LiveID, Google and Yahoo.

Getting windows Azure subscription

In order to setup ACS, you need an Azure subscription (note that NOT all teams have access to Azure subscriptions). You might have to get your request approved from somebody in your line of managers. You might need a windows Live ID to get the subscription. Please check with your team and policies.

Setup ACS site on Azure management portal

Once you are provisioned as admin, you can access the azure control panel from this link. https://manage.windowsazure.com

1. Click Active Directory on the left panel and then select ‘Access control namespace’ in the main header.
2. If you haven’t already, create a New namespace for your service .This can be shared with other services that you may want to use in Azure (Service Bus, Caching). To create one, click ‘+New’ and then follow App Services -> Active Directory -> Access Control -> quick create. Your ACS URI will look like https://<acs_namespace>.accesscontrol.windows.net
3. Once you’ve created a namespace, select the ACS and then click Manage. NOTE: only the Admin of the Azure subscription will be able to access the ACS Management Portal. This person then needs to give access to other co-Admins as Portal administrators for them to be able to access ACS Access Control. Instructions are available here: http://msdn.microsoft.com/en-us/library/windowsazure/gg185956.aspx
4. We need to setup Identity Providers that we are going to allow. This can be done by clicking Identity providers on the left hand side inside ACS Management Portal.
5.  At the time of writing, following identity provider are supported and can be added in the new namespace.
   • Google
   • Yahoo
   • Facebook applications
     • FB requires specific Facebook application setup. Please consult the MS link here to setup Facebook as ACS identity provider.
     • Once you are finished with the steps mentioned in the above link, do the following two setting on Facebook app
       • In the App domain – Add “Windows.net” so you can include any of your relying app site
       • In the Canvas URL – Add AD namespace URL
6. Next add a Relying party application: select “Relying party applications” from the left side of the ACS Management Portal.
   • Select Add
   • Enter a meaningful name for the relying party (to be used internally in ACS Management Portal). For a regular secure site, it can be named as urn:<host_name>:AzureACS
   • Type in a Realm (where the authentication request will come from). For a regular secure site, it should be urn:<host_name>:AzureACS
   • Type in the return URL  (where the ACS will redirect the web browser after a successful authentication). For a regular secure site, it should be https://<host_name>:<acs_port>/_trust
     Note: At this point the claim-aware site is not created. Use any port number like 5000 and then use the same port number in section 3.3 while creating the secure site on the host machine
   • (Optional) Type in some Error URL to get redirect user in case of some unexpected exception. This is a good practice to do so
   • Token format : For AX 2012: SAML1.1
   • Token encryption policy : None
   • Token lifetime (secs) enter some large number so ACS token doesn’t expire too often, e.g. 24hrs = 86400 seconds
   • Select the Identity providers you would like to enable this application to get authentication from.
   • Rule group: select to create a new rule group.
   • Click Save.
7. Next, configure the Rule Group just created in the above step. It should be under Rule Groups and named “Default Rule Group for <your_application_name>”
   1. Click Add
   2. On the next page, select the Identity provider that you would like configured, for example “LiveID” or “Yahoo!” or all of those.
   3. Input claim type: leave the default value of ‘Any’
   4. Input claim value: ‘Any’
   5. Output claim type: select “Pass through first input claim type”
   6. Output claim value: select “Pass through first input claim value”
   7. Click Save
8. Now create and upload the custom token signing certificate to the ACS site
   1. Open up Server Manager and navigate to Web Server (IIS) node and select Server Certificates
   2. Open the “Server Certificates” feature and on the right panel, click “Create Self-Signed Certificate…”
   3. Specify a friendly name for the certificate and click OK
   4. Now right click that certificate on the middle panel and select “Export…”
   5. Set a path to export the file to <path_to_acs_signing_cert> and specify a password.
   6. Open up MMC.exe, File -> Add/Remove Snap-in…  and Add> Certificates node and select “Computer account” \ “Local Computer” and click Finish.
   7. Now expand Certificates (Local Computer)\Trusted Root Certification Authorities\Certificates\ and locate the certificate you just created, right click, All Tasks\Export…
   8. In the Certificate Export Wizard, select “No, do not export the private key” and use all default settings to export the certificate as .cer file. Note down the path.
   9. At this point, you should have both <acs_signing_cert>.pfx and <acs_signing_cert>.cer files.
   10. Now go back to ACS Management Portal, and on the left hand side, click “Certificate and keys”
   11. Click “Add” above the “Token Signing” section, select the relying party created in step 6 above, browse to the <acs_signing_cert>.pfx and type in the password, and click “Save”Note: The above steps are taken/derived from the AX foundation team link here

Creating claim-aware site

1. Create and export self-signing certificate to enable secure browser based communication. Steps to create the SSLCert are here.
2. Now import the SSLCert certificate created in the above step. Following are the steps to import it.
   1. On the Windows server that will host the forms-based Enterprise Portal site, click Start > Run, type mmc, and then click OK.
   2. Click File > Add/remove snap-in.
   3. Click Certificates, and then click Add.
   4. When the system prompts you to specify which type of account to manage certificates for, click Computer Account, and then click Next.
   5. Click Local computer, and then click Finish.
   6. In the Add or Remove Snap-ins dialog box, click.
   7. In the MMC snap-in, click the Certificates (Local Computer) node.
   8. Right-click Personal, and then click All tasks > Import. The Certificate Import Wizard opens. Click Next.
   9. Browse to the certificate, and then click Next.
   10. Enter the password for the certificate, and then click Next.
   11. Select the Mark this key as exportable option, and then click Next. The Certificate Store dialog box appears. Click Next.

1. Now run through the following steps to create a claim-aware site on a new SharePoint application.
   1. Open the Microsoft Dynamics AX 2012 Management Shell with administrator privileges. Click Start > Administrative Tools > right-click Microsoft Dynamics AX 2012 Management Shell and click Run as administrator.
   2. Enter the following command and press Enter.
      • $Cred=Get-Credential
   3. When prompted, enter the credentials for the .NET Business Connector proxy account. The credentials must be the .NET Business Connector proxy account and password that were specified when Enterprise Portal binaries were installed earlier in this document. If you specify an account other than the .NET Business Connector proxy account, then the cmdlet overwrites the existing .NET Business Connector account, which can cause existing Enterprise Portal installations to stop working. Also note, this cmdlet designates the .NET Business Connector proxy account as the Enterprise Portal site administrator.
   4. Execute the following command, replacing “PathToSSLCert” with the path to SSLCert, which you imported earlier in this document.$SSLCert = Get-PfxCertificate “<PathToSSLCert>”   (the one created in step 1, the .pfx file)
   5. When prompted, enter the password that you specified when you exported the SSL certificate.
   6. On the Enterprise Portal server, execute the New-AXClaimsAwareEnterprisePortalServer cmdlet. For descriptions of the required parameters and syntax, see New-AXClaimsAwareEnterprisePortalServer on TechNet. The following example shows the cmdlet with the required parameters. Note that the port value of 5000 is a user-defined value. You can specify any available port number. If you specify port 443, then you do not need to specify the port number when you type the web site URL.

      New-AXClaimsAwareEnterprisePortalServer -Credential $Cred -Port 5000 -SSLCertificate $SSLCert

   7. This cmdlet can take several minutes to be completed. After the cmdlet is completed, you can access a new instance of Enterprise Portal at the following URL: https://<host_name>:<acs_port>/sites/DynamicsAx
   8. In the production environment, the self-signing certificated wouldn’t be used. Since here we used the self-signing certificated, you’ll get the error in your browser. Continue with the ‘Not recommended’ option and it will show you the site.
   9. You can also double check if the new site is created properly by navigating to System Administration -> Setup -> Enterprise portal -> Web site

Configure claim-aware site