This method allows the access of Dynamics AX to users and services that are not a part of your Active Directory.
There are two main reasons to use Claims users: allowing external users (including suppliers and customers) to access the Enterprise portal and allowing external applications or web services access to the AX AIF (Application Integration Framework) services with non-Active Directory accounts. An example of this is a mobile application that requires access to AX services but cannot log in to the domain. You cannot use basic authentication with the AIF. Unless you want to write a set of proxy services to act as intermediaries, you need some way of accessing AX without using Active Directory accounts.
Note
These users cannot log in to the AX client application directly. It is typically used to allow external parties (customers, suppliers, and so on) access to the Enterprise portal (SharePoint) or web services without creating Active Directory accounts.
The following example is for a mobile application that does not support the Active Directory accounts.
The method is the same as creating an Active Directory user, except for the following fields:
|
User Id |
This is a unique ID, but you should create a strict standard that allows you to identify these accounts. If this is a series accounts for a warehouse management application, perhaps we could use |
|
Alias |
This is the user ID of the external user that the user or service uses to log in with, often an email address. |
|
Domain |
This is the name of the authentication provider. When your application logs in to the AX AIF service, it uses this, along with the user ID as the |
|
Account type |
This is a Claims user. |
Note
For Claims users, no validation of the details entered is performed when the record is saved or enabled.
If the account is for an external party, it may be governed by that party (for example, using Active Directory Federated Services (ADFS). The purpose here is to inform AX that we trust this membership provider (the Domain field) to authenticate the user (the Alias field).
Where we do control the usernames (for example, in the internal applications), we should be careful while choosing the naming conventions, as these can't easily be changed later (if at all).
Closing the form will save the record and complete the task.
In your mobile application (this is not restricted to mobile devices, AIF HTTP integration ports would also use Claims users), the users log in with a user ID and password. Once they have logged in, they are classed as authenticated in your application. When this application tries to access AX, it will do so with the application's user account. Since you have entered these details within AX as a claims user, AX will trust that your application has authenticated the user.
Here we will provide a working example of a sample mobile application logging in as a Claims user with the following assumptions:
AIF is installed and functioning
Visual Studio 2012 is installed (although for this test, any version that can connect to WCF services is sufficient)
Users have the knowledge of how to create a simple Windows console project
We can create a claims user with the following details:
|
User Id |
|
|
Alias | |
|
Domain |
|
|
Account type |
|
We can configure an InventItem Service inbound AIF port by performing the following steps:
Navigate to System administration | Setup | Services and Application Integration Framework.
Click on Inbound ports. In the Inbound ports form, click on New and complete the form as follows:
Some of the fields are discussed in the following table:
Port name
This is the unique identifier of the port. Naming of these ports is important. A good tip is to use the module or a functional area as the first part of the port name.
Description
This is the description of the port.
Adapter
Retain the default values in this field.
URI
Leave this field with the default value.
Next, click on Service operations and move
InventItemService.findto the left-hand side pane:
Click on Close, and in the Inbound ports form, click on Activate.
The system will produce an InfoLog message listing the services that were started. At the end, it should state The port 'ItemsPort' was deployed successfully.
The Inbound ports form will now display the web service definition (WSDL) URI of the port. In my case, this is http://ZEUS:8101/DynamicsAx/Services/ItemsPort.
We can create a Visual Studio application by performing the following steps:
Open Visual Studio 2012 and create a Windows Console C# application.
On the project tree, right-click on References and select Add Service Reference, the following form will be opened:
In the Address field, insert the WSDL URI from the Inbound ports form and click on Go.
Open the code file,
Program.cs, so that we can write the application.Note
The first part of the program is to declare our security context, which is the important part we are trying to demonstrate with Claims users.
The first few lines of code of the
Program.csfile are as follows:// Set up the call context to use our Claims user ItemReference.CallContext context = new ItemReference.CallContext(); context.Company = "HHF"; context.LogonAsUser = "MyAppAuthProvider\\[email protected]"; context.Language = "en-gb";
You should remember that our user has the
MyAppAuthProviderdomain and the alias<[email protected]>. This is used as domain\alias when the application logs in to AX.The following code snippet is purely to demonstrate that the Claims user can log into AX and read the port we configured earlier:
ItemReference.AxdItem myItem = new ItemReference.AxdItem(); ItemReference.ItemServiceClient client = new ItemReference.ItemServiceClient(); ItemReference.QueryCriteria criteria = new ItemReference.QueryCriteria(); ItemReference.CriteriaElement itemIdCriteria = new ItemReference.CriteriaElement(); itemIdCriteria.DataSourceName = "InventTable"; itemIdCriteria.FieldName = "ItemId"; itemIdCriteria.Operator = ItemReference.Operator.Range; itemIdCriteria.Value1 = "A"; itemIdCriteria.Value2 = "Z"; criteria.CriteriaElement = new ItemReference.CriteriaElement[1]; criteria.CriteriaElement[0] = itemIdCriteria; try { myItem = client.find(context, criteria); if (myItem != null && myItem.InventTable != null && myItem.InventTable.Length > 0) { foreach (ItemReference.AxdEntity_InventTable item in myItem.InventTable) { Console.WriteLine( String.Format("Item Id {0} - {1}", item.ItemId, item.NameAlias)); } } } catch (Exception e) { Console.WriteLine(String.Format("Error {0}", e.Message)); }
The result of this is that the application logs in to AX as the Claims user, not as the Active Directory user. You will also note that no password is required, as AX does not have its own cryptography and we trust that the application has already done the authentication for us.
Flexible (Claims) authentication is a much welcomed new feature for AX 2012. In the past, we had to write proxy services to do this authentication for us, and for the Enterprise portal, we had to add the external users as the Active Directory accounts in our domain.