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&gt;:<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&gt;:<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

Pre-Requisites:

  • Claims Aware EP site is deployed successfully in the AX box  ==> https://<host_name&gt;:<acs_port>/Sites/DynamicsAx  (Section 3.3)
  • Access to ACS Management Portal ==> https://<acs_namespace&gt;.accesscontrol.windows.net/v2/wsfederation  (Section 3.2)
  • A certificate file (without the private key) of the signing certificate that was uploaded to ACS (.cer file) ==> <ACS_signing_cert>

Steps

  1. Open up Sharepoint 2010 Management Shell and execute the following three commands one by one to establish claims mappin

$claim1 = New-SPClaimTypeMapping -IncomingClaimType “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier” -IncomingClaimTypeDisplayName “ACS Name Identifier Claim” -LocalClaimType “http://schemas.microsoft.com/custom/claim/type/2013/07/acs-nameidentifier

$claim2 = New-SPClaimTypeMapping -IncomingClaimType “http://schemas.microsoft.com/accesscontrolservice/2010/07/claims/identityprovider” -IncomingClaimTypeDisplayName “ACS Identity Provider” -LocalClaimType “http://schemas.microsoft.com/custom/claim/type/2013/07/acs-identityprovider

$claim3 = New-SPClaimTypeMapping -IncomingClaimType “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name” -IncomingClaimTypeDisplayName “ACS username” -LocalClaimType “http://schemas.microsoft.com/custom/claim/type/2013/07/acs-username

Now register the Token.

          $acscert = Get-PfxCertificate <ACS_signing_cert>

          New-SPTrustedIdentityTokenIssuer -Name <name_of_your_SP_Trusted_Identity_Provider> -Description <description_of_your_SP_Trusted_Identity_Provider>
         -Real <realm_of_your_SP_trusted_identity_provider> -ImportTrustCertificate $acscert -SignInUrl “https://<acs_namespace&gt;.accesscontrol.windows.net/v2/wsfederation”
         -ClaimsMappings $claim1,$claim2,$claim3 -IdentifierClaim $claim1.InputClaimType

In this example, here are the values used:

<host_name> The name of your server box.
<acs_port> 5000
<ACS_signing_cert> .cer file created above
<name_of_your_SP_Trusted_Identity_Provider> “AzureACS”
<description_of_your_SP_Trusted_Identity_Provider> “Azure ACS”
<realm_of_your_SP_trusted_identity_provider> urn:<host_name>:AzureACS
<acs_namespace> <Namespace created above>
After execution, do not close the SharePoint Management Shell window yet.
  • Import <ACS_signing_cert> as trusted root certificate in compute account through MMC.exe
  • Now import <ACS_signing_cert> as trusted root certificate in SharePoint by going back to the SharePoint Management Shell window from step 1 and run the following:

    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($acscert)

    $spcert = New-SPTrustedRootAuthority -Certificate $cert -Name “ACSTokenSigningCert”

  • To setup the claims on EP Authentication Provider through SharePoint Central Administration site, add the “Azure ACS” to your Claims Aware EP site. To do this, navigate to SharePoint Central Administration -> Manage Web applications and select the claim-aware application you created in section 3.3. Now click on “Authentication providers” on the ribbon bar and click Default. Make sure ‘Azure ACS’ is checked as mentioned in the following screenshot.
  • Setup the Security -> Users -> Specify web application user policy, Add Users: All Users\All Users (AzureACS) and give Full Read access
  • Now you are able to sign into secure site (https://<host_name&gt;:<acs_port>/Sites/DynamicsAx) using the Windows Live ID credentials from step 6:

How to setup a Public site on Enterprise portal in AX2012

The public site is a custom site collection deployed/created on top of regular SharePoint app (Sharepoin-80) that we configure while installing EP on AX2012. This post will list down steps to setup a public site.

Pre-Requisites:

  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)

Public Site Creation in SharePoint 2010/2013

  1. Launch SharePoint Central Administration
  2. Under Application Management, click Manage web applications
  3. Select the Web Application hosting the public site. It is SharePoint – 80 in our case.
  4. Click Authentication Providers button from the ribbon
  5. Click the Default Zone
  6. Under Anonymous Access, make sure Enable anonymous access check box is unchecked (required for EP Public Site Creation)
  7. Click Save
  8. Under Application Management, click Create Site Collections
  9. On the following page, enter page Title as EP Public Site (or any meaningful name)
  10. Set Web Site Address URL as Public (or anything meaningful)
  11. SP2013 ONLY: Select 2010 from ‘Select experience version’ drop down
  12. Select Microsoft Dynamics Public template under Custom tab
  13. Set Primary Site Collection Administrator as your alias
  14. Press OK

After the site has successfully been created, click on the site URL to verify that you can access it

Configure IIS

  1. Open Internet Information Services (IIS) Manager (Start > Administrative Tools > Internet Information Services Manager).
  2. Select the Web Site SharePoint-80
  3. Double click on Authentication
  4. Enable Anonymous Authentication (if not already)
  5. Enable Windows Authentication (if not already)

Enable Guest Account in AX

  1. From the Microsoft Dynamics AX client, click System Administration > Common -> Users -> Users.
  2. Double click the Guest User
  3. Click on Edit
  4. Select the Enabled check box.
  5. Assign Guest user to Vendor anonymous (external) role. (note: needed to expose vendor portal on Public site, you can add more external roles as needed)

Configuring SharePoint

  1. Launch SharePoint Central Administration
  2. Under Application Management, click Manage web applications
  3. Select Web Application hosting the public site. It is SharePoint – 80 in our case.
  4. Click Authentication Providers button from the ribbon
  5. Click the Default Zone
  6. Under Anonymous Access, check Enable anonymous access (if not already)
  7. Click Save
  8. Now go to the EP Public site http://<host_name>/sites/Public
  9. Click Sign In to login using system account
  10. Navigate to Menu Site Actions > Site Permission
  11. From the Ribbon click Anonymous Access button
  12. In the popup dialog, select Entire Web site and click OK
  13. 13.Launch SharePoint Central Administration
  14. Click Application Management > Web Applications > Configure alternate Access Mapping
  15. Click Add Internal URLs
  16. Choose Alternate Access Mapping collection to be the Web application Sharepoint-80
  17. Type http://localhost as the internal URL and Zone =Default.
  18. 18.   Click Save

Setup Internet Explorer for anonymous access

To ensure that you are accessing the page in anonymous access mode and not automatically logged in using Windows authentication:

  1. In Internet Explorer, Go to Tools > Internet Options > Security tab
  2. Select the Trusted zone
  3. Click on Custom Level
  4. Scroll to the bottom, under User Authentication > Login
  5. Select Anonymous logon.
  6. Click OK 

Now you should be able to access your public site at the URL  http://<host_name>/sites/Public

publicsite

How to launch the internet browser with a data field bound to URL data?

While working on a project, I figured out a way in AX that could trigger your system default internet browser within the AX. Many of you already have seen this while playing with SSRS or EP when you click on ‘view in browser’ kind of a buttons.

Its really simple. For the sake of example, suppose we have a stringEdit control (name: URL) with a normal button. There is a method urlLookup() in the global infolog instance that when executed opens up the default browser with the website link provided as the parameter.

Write the following code in the click event of the button ‘View in browser’.

void clicked()
{
    infolog.urlLookup(URL.text());
}

Alternatively, if you have a databound field, you can extend it from WebsiteURL EDT to get a small web lookup icon on the form control that takes you to the browser. No coding needed.


Dynamics AX 2012: Role based security framework

In addition to many new frameworks that are introduced in the current release of Microsoft Dynamics AX (a leading ERP of Microsoft Business Solution suite), role based authorization framework is one of the key elements that would make the life of AX 2012 customers and vendors easier. Though the security rights and user access management has been an integral part of all enterprise level software systems, it becomes more significant when it comes to business applications. A substantial change was needed to make the security management of Dynamics AX much more aligned with organizational needs and easy maintenance for the customers.

A little background: Some pain points

Administration of user based authorization to different modules in previous versions of AX is based on the concept of user groups and domains. Users are added to user groups and companies are added to domains. Then permission to different forms and data are set for a combination of User group and domain.

The main issue with the old system is that permissions in AX are defined at the table/field/Menu Item/controls level. Moreover, the security management UI doesn’t help the administrators easily identify the tables requiring access in order to perform an operation on a form. Customers have to spend a very long time trying to figure out what underlying tables require what access level in order to enable a user to perform a particular operation.

Furthermore, following key issues are also tamping the customers/vendors.

  • The user groups are not reusable. If the two users exist in different companies and need access to a single set of operations, two user groups need to be created.
  • The security administration is different for heterogeneous client types. For instance, rich clients and web users are granted access using the AX administration form while reports, cubes and services, security needs to be managed separately.
  • Functional consultants and administrators needs to have database-centric knowledge and hence to be more technical about the system in order to setup authorization. Need extra effort to either train them or assign a separate technical resource. Not cost effective.

Fundamentals of the new role-based security model in 2012

The new role based security framework in AX 2012 is designed with two goals in mind.

  • Make the security administration easier for the customer and align to the business needs
  • Make the product more secure.

Based on the facts described above, a significant change was needed to revamp the whole authorization concept in AX. Most businesses would like the security management in their companies to align with how their businesses are structured. They would like it to be set up for users based on the roles the various users are playing in respect to the organization. Instead of creating arbitrary groups of users and granting them permissions, the access grant based on the role and job functions and being able to control what users are allowed to see or do based on business processes makes much more sense. The following diagram helps to comprehend the real world scenario.

In the figure above, the job function can be described as the most granular level task which is termed as privilege. Those privileges define the access levels that are exposed to user through roles and duties. A duty can be defined as an extra layer b/w roles and privileges to group together job functions. For example, AR clerk may have multiple duties and each duty comprises of multitude of tasks or privileges.

In addition to simplifying security setup greatly, using role based security also allows setting up other rules such as segregation of Duties Analysis (SoDA) which ensures that companies can place checks and balances in their system. This ensures that their systems are not only secured but also well audited and that a user cannot bypass the processes that they have in place.

How to persist values on runtime in SysLastValue?

Sometimes we need to store values on runtime which are not really worthy of storing in database. Examples could be the fiscal calendar year and period entered by a particular user last time during the session. In many situations, the user would like to know what values he entered last time while doing some processing. Since this information is not required to be persisted in database therefore we should have some way to store them either in some session type variable or cache. Fortunately in AX we have a pack/unpack pattern along with a table called SysLastValue that stores such information. To illustrate the concept, lets create a very simple form with two unbound controls.

  • Gender combo box hooked to gender base enum. AutoDeclaration = Yes
  • Date of birth: dateEdit control, extended with TransDate EDT. AutoDeclaration = Yes

Now we want to persist the values of both of these controls in SysLastValue table. Here are the steps to do that.

  • Declare variables in the class declaration and define macros to store them into container.

public class FormRun extends ObjectRun{

// form level variables to store control values.
Gender      gender;
TransDate   DOB;

#define.CurrentVersion(1)
#localmacro.CurrentList
gender,
DOB
#endmacro
}

  • Write the following methods at the form level. They return application and client level information to the SysLastValue framework. This information is needed to uniquely identify the last value stored in the SysLastValue table.

dataAreaId lastValueDataAreaId(){    return curext(); }

private identifierName lastValueDesignName(){    return ”; }

private identifierName lastValueElementName(){    return this.name(); }

private UtilElementType lastValueType(){    return UtilElementType::Form; }

private userId lastValueUserId(){    return curUserId(); }

  • Add the pack/unpack methods.

public container pack(){

gender = cmbGender.selection();
DOB = str2Date(dateOfBirth.valueStr(), 1);
return [#CurrentVersion,#CurrentList];

}

public boolean unpack(container packedClass){

Integer     version     = conpeek(packedClass,1);

switch (version)    {

case #CurrentVersion:

[version,#CurrentList] = packedClass;

break;

default:

return false;

}

return true;
}

  • Override the close and init methods of the form to save and retrieve values from SysLastValue table. There is a system class xSysLastValue which contains some static methods to perform these operations.

public void close(){

super();
xSysLastValue::saveLast(this);

}

public void init(){

super();
xSysLastValue::getLast(this);
cmbGender.selection(gender);
dateOfBirth.dateValue(DOB);

}

  • One last thing. In order to initialize the default values for the first time form executed in the current session, we need to provide a method called initParmDefault() to do such settings. This is the required method, otherwise the framework complains at the time form initialization.

public void initParmDefault()
{

gender = gender::Unknown;

}

Now suppose you run the form and entered the data as shown in the follow figure. Close the form and run it again, you’ll see these values already filled up.

The SysLastValue framework works well for providing runtime persistence in AX. The source code of this example can be found here. Happy Daxing!!

Everything tool

Recently, I came across a very light and handy tool to find out files stored anywhere on computer at the blink of an eye. Although, windows search have been improved alot lately but still its quite slow. This tool creates file indexes very quickly and therefor privide search results earlier then windows search. its simple and easy to instal and above all its free. You might wanna look.

http://www.voidtools.com/

 

AOT Maps – the consistent approach to access same data

The AOT maps residing in the data dictionary is very useful element under DD node after tables, enums and EDTs. Perhaps they aren’t as widely used as they should be in usual application programming. However, they have the power to solve some key daily problems in AX running in the production environment.

Map defines X++ elements that wrap table objects at runtime. We can associate a map field (just a like a table field) to a data field in one or more tables. This enables us to use same field name to access fields with multiple names in multiple tables. Unlike tables, maps are not database objects and hence they dont synchronize with the sql server.

Lets consider an example. In AX application, we have a map called CustVendGroup. As it name shows, it appears to be the combination of both Customer and vendor related data.

Underneath mappings, we can define multiple mappings to multiple tables to associate map fields with different tables’ fields. In this example, we actually have two tables (CustGroup & VendGroup), storing same information but for different entities. Now writing consistent logic for both of these tables is easier for us and we dont have to do separately for each of them. Suppose we want to do a validation around ClearingPeriod field, write a method on the map.

boolean validateClearingPeriod(CustVendGroup _group)
{
// do validation on CustVendGroup.ClearingPeriod and return boolean
}

Now use that validation based on map in your business logic.

CustGroup custGroupTable;
VendGroup vendGroupTable;
CustVendGroup custVendGroupMap;
custGroupTable.ClearingPeriod = “Period 1”;
vendGroupTable.ClearingPeriod = “Period 2”;

if (custVendGroupMap.validateClearingPeriod(custGroupTable))
{
// do something here
}

if (CustVendGroupMap.validateClearingPeriod(vendGroupTable))
{
// do something here
}

We are using the same method here with different tables buffers as parameters. AX does automatic binding here from map fields to table fields.

Benefits

  • Simplicity – single interface to fields in multiple tables
  • Consistency – table fields with varying names can be accessed
  • Re-usability – code written on map methods runs against map fields.

How to cache records on run-time in AX?

The simple answer is RecordViewCache class. This class is used to implement set-based caching in your code at run-time.

1.    First declare the variables.

CustTrans                    custTrans;
RecordViewCache      recordViewCache;

2 .  Call a nofetch query to create a record buffer. It will define the set of records that you want to cache.

//Define records to cache
select nofetch custTrans
where custTrans.AccountNum == ‘4000’;

3.   Pass the record buffer to instantiate RecordViewCache Object. It will also cache the records that are returned in the buffer.

recordViewCache  =  new RecordViewCache(custTrans);

4.   The records in the following query will be returned from the cache.

select firstOnly custTrans  where custTrans.AcccountNum == ‘4000’ &&
custTrans.CurrencyCode == ‘USD’;