Create a security file for Retail deployment

Article
11/29/2021

Important

This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.

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.

Note

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

Create a security file

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

Important

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.

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.
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.
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.

Enter the path to the security file in Microsoft Dynamics AX

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.

Click Retail > Setup > Retail mass-deployment > Security > Retail deployment certificates.
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.

Click Retail > Setup > Retail mass-deployment > Security > Retail deployment credentials.
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.

Example XML

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.

Example 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>

Example .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>