Create a security file for Retail deployment [AX 2012]

Updated: December 17, 2014

This topic describes how to create a security file that can be used by Retail mass deployment tools.

To set up and secure communication among the various Retail components, you must provide credentials and obtain certificates. During deployment, you need a way to provide this information without allowing too many people access to it. You can do this by saving credentials and certificate information in a clear-text xml file that is stored on a secure file share at headquarters. This type of file is called a security file. By allowing only deployment tools and a limited number of users access to security files, you help make your credentials and certificates more secure.

NoteNote

The deployment tools for Retail components support security files starting in Microsoft Dynamics AX 2012 R3 Cumulative Update 8.

A security file is required when you use mass deployment tools to deploy the following components.

Component

Requires a certificate

Requires credentials

Channel database

No

Yes

Commerce Data Exchange: Real-time Service

Yes

Yes

Commerce Data Exchange: Async Client

No

Yes

Commerce Data Exchange: Async Server

Yes

Yes

Retail POS

No

Yes

Retail Server

Yes

Yes

Retail Hardware Station

Yes

Yes

Complete the following procedure to create a security file in XML format and its corresponding .xsd file.

ImportantImportant

We strongly recommend that you create a different security file for each store.

Outside of stores, it does not matter how you group credentials and certificates in a security file. For example, you could create one security file for credentials and one security file for certificates.

  1. Create a secure shared network folder.

    Limit access to this share to only domain users who need the information to complete deployment. A self-service user does not require access to the secured location. A self-service user needs to know only the display name that identifies the credential set or certificate information in the file. The deployment tool accesses the correct file and obtains the necessary information.

  2. Create a new .xml file using a tool such as Notepad.

    • You can copy the code from the Example security file in this topic.

    • Create a section for each set of credentials and each certificate that will be used in the deployment.

      For a set of credentials, the XML should be formatted as in the following example.

      <Credential ID="ExpressDeploymentAdmin">
          <UserName>domain\user</UserName>
          <Password>password2</Password>
      </Credential>
      
      

      For a certificate, the XML should be formatted as in the following example.

      <Certificate ID="ExpressDeploymentSSL">
          <Path>AsyncServer/connection.pfx</Path>
          <Password>password1</Password>
      </Certificate>
      
      
    • Save the file as <FileName>.xml in the secure shared folder.

  3. Optional. Create a corresponding .xsd file by using a tool such as Notepad. Perform this step if you would like to validate your modified XML file using a tool such as Visual Studio.

    • You can copy the code from the Example .xsd file in this topic.

    • Save the file as <FileName>.xsd in the secure shared folder.

To use the security file in a deployment, you must enter information about it in Microsoft Dynamics AX.

If the security file contains information about certificates, complete the following procedure.

  1. Click Retail > Setup > Retail mass-deployment > Security > Retail deployment certificates.

  2. Create a new line for each certificate ID. Enter the location of the security file and the identifier for the certificate.

    If your certificates are in multiple security files, enter them in this form.

If the security file contains credentials, complete the following procedure.

  1. Click Retail > Setup > Retail mass-deployment > Security > Retail deployment credentials.

  2. Create a new line for each credential ID. Enter the location of the security file and the identifier for the credentials.

    If your credentials are in multiple security files, enter them in this form.

For an example of XML to use in security files, click Security file example in the Retail deployment certificates form or the Retail deployment credentials form. You can also copy and paste one of the following examples to get started creating a security file or an .xsd file.

Dn858397.collapse_all(en-us,AX.60).gifExample security file

The security file contains the credential and certificate information that is used in Retail deployments.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<SecurityInformation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="AXRetail.xsd" xmlns="AXRetail">
     <Certificate ID="ExpressDeploymentSSL">
          <Path>AsyncServer/connection.pfx</Path>
          <Password>password1</Password>
     </Certificate>

     <Credential ID="ExpressDeploymentAdmin">
           <UserName>domain\user</UserName>
           <Password>password2</Password>
     </Credential>

</SecurityInformation>

Dn858397.collapse_all(en-us,AX.60).gifExample .xsd file

The .xsd file is used to validate the XML in the security file. The .xsd file defines which elements and attributes are permitted and in which order.

<?xml version="1.0" encoding="utf-8">
<xs:schema attributeFormDefault="unqualified" xmlns:xs="http://www.w3.org/2001/XMLSchema" version="6.3.0" xmlns:r="AXRetail">
  <xs:simpleType name="noEmptyString">
    <xs:restriction base="xs:string">
      <xs:length value="1" />
      <xs:whiteSpace value="collapse" />
      <xs:pattern value="[A-Za-z0-9!@#$%‘*+,\\/=?^_‘[|]~-}*[A-Za-z0-9!#@$%‘*+.\\/=?^_‘{|}~-]*"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="relativePath">
    <xs:restriction base="xs:string">
    </xs:restriction>
  </xs:simpleType>
            </xs:schema>

Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).

Community Additions

ADD
Show: