Claims-Based Flexible Authentication in Dynamics AX 2012

Dynamics AX 2012 provides a new way to authenticate users in AX, called claims-based / flexible authentication. In this approach, you don't have to create users in Active Directory first to give them access to use AX Enterprise Portal / AIF. And this is really a very nice and a way to go approach for giving AX access to external users who are not part of the organization's Active Directory structure. For example; now you are no longer required to create vendors and customers in Active Directory to have them access vendor self-service portal or customer self-service portal respectively.

AX achieves this by using the concept of trusted intermediary. This trusted intermediary can be anything (a website, service, or mobile app etc) that runs under the identity of a authenticated AX user account. This means that AX trusts the intermediary users or user groups and allows them to impersonate another user. In other words, the user authentication is done by trusted intermediary instead of AX. This also means that authenticated users, call into AX as trusted intermediary user and execute AX code / functionality as that authenticated user.

On Enterprise Portal, we implement this by creating a Trusted Identity Provider on SharePoint 2010 that will authenticate users on behalf of AX.

Dynamics AX 2012 introduces two new kind of user types other then Active Directory user, called Active Directory group and Claims user. For this post, we are dealing with Claims users only.

In this post, we will create a claims aware Enterprise Portal site to authenticate users by using a forms-based authentication provider site. On forms-based site, users will be able to enter their credentials in a logon form. By default, Dynamics AX 2012 supports the forms-based authentication providers in ASP.NET.

Ok, enough talking.... it's time to get hands dirty.

Before getting started we need to make sure that following components are already installed.

• .Net Business Connector
• Management utilities 
• Enterprise Portal: If you have it installed then nothing needs to be done here, else, while installing make sure that you don't configure SharePoint and create website at this point, we will do it later in this post.

SSL certificate:
We need to register a Secure Sockets Layer (SSL) certificate on the Enterprise Portal Server. For now, we can create a self-signed server certificate in IIS 7.0 but for production server, you must register an SSL certificate from a certificate authority on the Enterprise Portal Server.This certificate helps to make sure that user's claim was not changed in transit.

Create a Self-Signed Server Certificate in IIS 7.0:

1. Open IIS Manager (command line: inetmgr) and select server or the level you want to manage.
2. In Features view, double-click "Server Certificates".
   

• In the Actions pane, click "Create Self-Signed Certificate".
• On the "Create Self-Signed Certificate" page, type a friendly name for the certificate in the "Specify a friendly name for the certificate" box, and then click OK.
  I created mine with the name "Rah-SelfSignedCert".
• Export it with password and save it on a file location. We will need it while registering it.
  

Register SSL certificate on the Enterprise Portal server:

1. On the Windows server that will host the claims-aware 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 OK.
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.
9. Click Next.
10. Browse to the SSL certificate  "Rah-SelfSignedCert.pfx"  for the Enterprise Portal site, and then click Next.
11. Enter the password for the certificate, and then click Next.
12. Select the Mark this key as exportable option, and then click Next. The Certificate Store dialog box appears.
13. Click Next.
14. Click Finish.

Create claims-aware Enterprise Portal site:
In this section, we will use Microsoft Dynamics AX 2012 Management Shell (Microsoft Windows PowerShell) cmdlet. This cmdlet will first creates a claims-aware web application in SharePoint and then deploys an Enterprise Portal site on that web application.

1. Click Microsoft Dynamics Ax 2012 Management Shell.
2. Execute following command.
   $Cred = Get-Credential
3. When prompted, enter the credentials of the user that you want to set up as the site administrator of the Enterprise Portal site that will be created.
4. Execute following command, replacing “PathToSSLCertificate” with the path of the SSL certificate that you imported earlier in this post.
   $SSLCert = Get-PfxCertificate "PathToSSLCertificate"
5. On the Enterprise Portal server, execute the New-AXClaimsAwareEnterprisePortalServer cmdlet. new-AXClaimsAwareEnterprisePortalServer -Credential $Cred -Port 90 -SSLCertificate $SSLCert

In the above example, 90 is a port number we are using to create Enterprise Portal site though you can use any free port number. Once this command is done, you can browse the new instance of Enterprise Portal at:
https://ServerName:PortNumber/sites/DynamicsAx

Forms-based authentication:
In this section, we will setup and create a custom authentication mechanism to authenticate external users. Forms authentication enables you to authenticate the user name and password of your users using a login form that you create. So for this, we will be creating a forms-based website and a database to hold external user credentials.

External user credential database:
For this post, we will use ASP.NET database to store external user credentials. This database works with standard ASP.NET forms-based authentication provider. Use following command to create ASP.NET database:

• Open a Command Prompt window by using an administrator account on the server. Execute the following command.
  %windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regsql.exe
• The ASP.NET SQL Server Setup Wizard opens.

• Complete the wizard. The wizard creates a new database in Microsoft SQL Server called aspnetdb if you choose <default> in database name or whatever name you give.

NOTE: If you change the default name of the database then don't forget to change it in the web.config of forms-based provider's website as well.

Create a self-signed certificate:

A self-signed certificate is used to establish trust between the claims-aware Enterprise Portal site and the forms-based site. The command in the following procedure creates a self-signed certificate and registers that certificate with the local computer.

1. On the Enterprise Portal server, click Start > All Programs.
2. Click Microsoft Visual Studio 2010. If Visual Studio is not installed on the local server, execute the command on a server where Microsoft Visual Studio 2010 is installed, and then copy the certificate to the Enterprise Portal server.
3. Click Visual Studio Tools > Visual Studio Command Prompt.
4. Let's name this certificate as "Rah-Forms-Cert". 

makecert.exe -r -pe -a sha1 -n "CN=Rah-Forms-Cert" -ss My -sr LocalMachine -sky exchange -len 2048 -sp "Microsoft Enhanced RSA and AES Cryptographic Provider" -sy 24 c:\certs\Rah-Forms-Cert.cer

Create forms-based provider and register it as a claims provider in SharePoint for Enterprise Portal:

1. Click Microsoft Dynamics Ax 2012 Management Shell.
2. Execute following command.
   $Cred = Get-Credential
3. When prompted, enter the credentials of the user that you want to set up as the site administrator of the forms-based STS site that will be created.
4. Execute following command, replacing “PathToSSLCertificate” with the path of the SSL certificate that you imported earlier in this post.
   $SSLCert = Get-PfxCertificate "PathToSSLCertificate"
5. Execute the following command.
   $SigningCert = Get-PfxCertificate c:\certs\Rah-Forms-Cert.cer
6. On the Enterprise Portal server, execute the Add-AXSharepointClaimsAuthenticationProvider cmdlet.

Add-AXSharepointClaimsAuthenticationProvider -Type Forms -Name FormsAuth -SigningCertificate $SigningCert -Credential $Cred -Port 91 -SSLCertificate $SSLCert

In the above example; our Trusted Identity Provider's name is FormsAuth and the forms-based security token service (STS) website is deployed on port 91. You can choose any name and free port.

To make sure that we have registered the provider on our Enterprise Portal site, do following:
Go to SharePoint Central Administrator site >> Security >>  Manage trust, and make sure that you have FormsAuth there.





Also, go to SharePoint Central Administrator site >> Security >> Specify authentication provider, and make sure that you have Claims Based Authentication provider registered with proper settings.



The main thing is to see if it has Trusted Identity Provider set to FormsAuth.


NOTE: One last thing to check if you have a custom name for your ASP.NET database then you need to change the  database name in the connection string of provider's web.config as well.



Create claims users:
Now as we have our Enterprise Portal site and forms-based site created and ready to test, it's time to create few user for testing. We need to create users first in forms-based credentials database for authentication and then in AX for giving them access to different AX modules.

We can create our users by using New-AXUser cmdlet of the AX Management Shell. This cmdlet will create users in both the databases. For example; below command will create a user with the name of rahul, account type Claims user, AXUserId rahul, domain name will be the name of the claims provider we created above that is FormsAuth and finally the password.

New-AXUser -AccountType ClaimsUser -AXUserId rahul -UserName rahul -UserDomain FormsAuth -CreateInProvider -ClearTextPassword "manager@1"

NOTE: You can change password policy in the provider's web.config file.

By default New-AXUser cmdlet adds the new user in System user role. You can assign required roles in AX if needed.

You also need to define the relationship of this user to a AX person in system, like vendor / customer.


This relationship will allow user rahul to logon in to the vendor portal for vendor "Contoso Asia" as contact "Biran Groth". You can assign more then one person or vendor or customer to a single user and on Enterprise Portal you can change the role accordingly.

Grant permission to all forms-based authenticated users:
This can be achieved in any of the following ways:

• Browse to SharePoint Administrator site
• Go to your Enterprise Portal web application
• Open User Policy and add Read only access for all authenticated FormsAuth users.

Another way to grant permission is:

• Browse to the SharePoint Server 2010 Enterprise Portal site that you created and log on using the administrator account.
• On the Site Actions menu click Site Settings.
• In the Users and Permissions section, click Site Permissions.
• Click Site Name Visitors group, where Site Name is the name of the site.
• Click New, and then click Add Users.
• In the Grant Permissions window, click the browse icon.
• In the Select People and Groups window, click All Users, and then click All Users (FormsAuth) in the right pane.
• Click Add.
• Click OK.
• Verify that All Users (FormsAuth) is now part of the visitor’s group. You should now be able to log on to the SharePoint Server 2010 site with FormsAuth user’s credentials.

Test functionality:
Now if you go to the Dynamics AX Enterprise Portal URL (https://ServerName:PortNumber/sites/DynamicsAx), the Sign In page will prompt you to select a logon option in a drop-down list. In our setup URL will be, https://ServerName:90/sites/DynamicsAx


If you select FormsAuth, you will be redirected to the forms-based authentication logon site.


After sign in, depending on the roles of that user in AX, you will be redirected to the Enterprise Portal. In our case, user only has vendor portal roles assigned for one vendor. If user has more than one relationship defined then he can navigate from one role to another on Enterprise Portal itself.



Note: There can be instances where instead of having Vendor credential database, organization can decide to go with having a separate Active Directory for vendors. For this, same concept can be used where you will setup Active Directory Federation Services instead of Forms-based authentication.

That's it for today. Next time we will see how to use this concept with AIF where you can access AIF service using claims user.