Introduction

CRM.web is built on top of CRM.win, and interfaces with the core ACRM modules through the use of several special or master users. These users can be configured in the Rights module, and will be accessed by the web application using credentials stored in the corresponding users.xml file.

Note that the above is true for a variety of ACRM modules (e.g.: CRM.connector), although the specific users, as well as the credentials referenced, will change for each of these. In this article, we will discuss the users specific to CRM.web.

Configuring the Users

While these users are normally configured during deployment, it may be necessary to modify the settings for these to resolve certain issues, change the credentials, or encrypt the information. Other than modifying the Rep (ID) users in the Rights module, if required, this is done through the use of the update.users.exe program, which edits the users.xml file.

Please be aware that it is important that the correct program is used, and that the correct file is selected once the program is opened. The exact folder locations are discussed below.

The users.xml File

The users.xml file used for CRM.web is the one located under ...\update.web\web\system\settings. It is an XML file that contains the credentials of various special ACRM users and is used by CRM.web for authentication. The special users specific to CRM.web are the following:

User of type Default, called WWW by default: Used for sessions that are not authenticated yet (before login) or not authenticated anymore (after logout). An issue with this user will prevent the system from initializing.
User of type Special, called SU by default: Used during start-up and for processes that require elevated rights. This user is often used to perform certain tests and will ignore any rights limitations imposed.
User of type Server, called U8SERVER by default: Used for background processing of queries and To-Dos. An issue with this user will prevent the system from working.
User of type Maintenance, which is disabled by default: This enables a series of Maintenance operations, such as modifying field names, or updating catalogs, the data model, and roles. To enable this user, you will need to manually uncomment the user in the users.xml file.

Note: Other ACRM modules have different user types. Please refer to the product documentation for more information.

The update.users.exe Editor

The tool update.users.exe is an editor that allows for manipulating, encrypting, and decrypting the users.xml file. The tool has a front-end UI, but also supports command line operations.

Although it is possible to edit the file users.xml with any text editor, it is recommended to use update.users.exe only when making changes. The program configured for use with the CRM.web users.xml file is located under ...\update.web\web\bin.

Using the tool with the UI front end is as simple as clicking on each of the users to change the User and Password fields, then saving the changes before leaving. To learn more on the command line mode, you can type the following to display usage information:

update.users.exe --help

Note: If you want to copy/move and execute update.users.exe from a different location than web/bin, you also need to copy update.Lib.Contracts.dll and update.Lib.dll.

Encryption

Since users.xml contains the usernames and passwords of CRM users, it is highly recommended to encrypt the contents of the file. This can be done in the UI interface of update.users.exe, by checking the option 'Use Xml Encryption'.

The following is a list of commands related to encryption of users.xml:

; Encrypt file ..\system\settings\users.xml
update.users.exe encrypt
 
; Encrypt file c:\myfolder\users.xml
update.users.exe encrypt -f=c:\myfolder\users.xml
 
; Encrypt file c:\myfolder\users.xml using encryption key named 'mykey'
update.users.exe encrypt -f=c:\myfolder\users.xml -k=mykey
 
; Decrypt file ..\system\settings\users.xml
update.users.exe decrypt
 
; Decrypt file c:\myfolder\users.xml
update.users.exe decrypt -f=c:\myfolder\users.xml
 
; Decrypt file c:\myfolder\users.xml using encryption key named 'mykey'
update.users.exe decrypt -f=c:\myfolder\users.xml -k=mykey

Note that update.users.exe uses the WC3 XML Encryption standard to encrypt users.xml. If no key is specified, the key update.eight.users will be used.

The keys used for encryption/decryption are expected to be stored in the Local Machine store of the Windows operating system. This means that encrypted users.xml files cannot be copied from one machine to another without also transferring the encryption keys.

Note: When encrypting your users.xml file via RSA, the credentials assigned to the update.CRM web application pool must have access to the RSA key.

Copying RSA keys from one machine to another

The ASP.NET IIS Registration tool (Aspnet_regiis.exe) can be used to administer your RSA key containers. Please refer to Finding the Correct Version of Aspnet_regiis.exe to locate the correct program to be used.

The process to create a specific RSA key container, encrypt a file with that key, and export the key container is as follows:

; Create a RSA key container that is exportable
aspnet_regiis.exe -pc "mykey" –exp
 
; Use that key to encrypt your xml file
update.users.exe encrypt -k=mykey -f=c:\myfolder\users.xml
 
; Export the key into a xml
aspnet_regiis.exe -px "mykey" c:\myfolder\mykey.xml
Copy the exported xml to another machine and import the key

aspnet_regiis.exe -pi "mykey" d:\mydirectory\mykey.xml
 
; Now you can use that key to decrypt the file
update.users.exe decrypt -k=mykey -f=d:\mydirectory\users.xml

For more information: Importing and Exporting Protected Configuration RSA Key Containers.