Create XML File for Credentials

The username and password used during authentication are set in an XML file. Refer to the ASG_CONFIG_HOME/BookQuerySecurity/security/resource/XmlAspUsers.xml file as a template.

The XML file contains the users credentials, which are defined as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<realm xmlns="http://xsd.tns.tibco.com/trinity/realm/2013" hashAlgorithm="PBKDF2WithHmacSHA256" repetitionCount="128">
   <users>
      <user>
      <name>john</name>
         <!-- specify the password as follows using the <plaintext> element.
         The code will replace <plaintext/> with <password salt=...>hash</password>
         in the file on the first authentication attempt.
            Alternatively use the command-line asg-password-hasher utility.
         Make sure that the hashAlgorithm and repetitionCount attributes at
         line 2 match the input to the command-line tool.

         <plaintext>password</plaintext>

         -->
         <password salt="tHpKLGzd92xa2A4Skkdv/oxxeq0=
          ">ES7VlmB26+h4wXaRfhj6PEze8rwYjUijzj2/5L3Cd2A=</password>
      </user>
      <user>
         <name>alex</name>
         <!--  the password is secret -->
         <password salt="qEd8Hq7ObiuzvJUrq6lv1eIRUKYxBAEQc+x6byFFOXg=
          ">s34OkB7FjnhZcNm0z3XSvdWKQUKqdsckkjpXj3O+cE8=</password>
      </user>
      <user>
         <name>username1</name>
         <password salt="rBPcqwHagVwVSRi3ndbjcHCkEk2TV0zmEnHBnkfbf+U=
          ">836tSikrJDFgKfVDQn332khxjQt/xzeLym3i5dAzqFg=</password>
      </user>
      <user>
         <name>username2</name>
         <password salt="k8YuHe/QxhimlmfFLFMMSClGL6rx9Kuzb94VXDlx3gg=
          ">xgCmSLnmjoy1CCnvXK+D+kiuAaGBPcRSyKkk6Qh1H24=</password>
      </user>
      <user>
         <name>username3</name>
         <password salt="PuPZQnsuVnC0QTTgMA1LWvL7T38yVhKslcQviZfoD1U=
          ">ljPyYXbAmQVdzV13Hrk7UbRVl8WD8DSLD4mKxCedpFQ=</password>
      </user>
      <user>
         <name>username4</name>
         <password salt="kBV40kbnFJcD94kyHl1DJ4ATjStQ/Z8rEGxFJo0Hx1s=
          ">RO3VI95GR/VlM+d8pPpSw/sxPwUN4cj49oG9KzUvclY=</password>
      </user>
      <user>
         <name>username5</name>
         <password salt="tta7NUkzBypyqS7EXnl+gR2MSZ/bT6kV6DVoR4pVmJA=
          ">q4g4rnJkUfIGS0jkuLlgoN5xgfhgLxATuNXp9MhfVhU=</password>
      </user>
      <user>
         <name>username6</name>
         <password salt="gTYrCR11ZfTDlp4pZ9hlga50UcpseqiasS0cT98KBto=
          ">Jic75Qs0U7yktbZyLDkvWXHiYKx8aloI1KSQXSwuI30=</password>
      </user>
      <user>
         <name>username7</name>
         <password salt="TgB9quAYdUY9St4zvMK8Uqq921Hcb7sUb8jMj5+V1Ks=
          ">Sf4CwL19/ON9Jmyp12yM9PuQpQW3nqYtHzhLCjOB42U=</password>
      </user>
   </users>
   <group-mapping>
      <group-name>Administrator</group-name>
      <user-name>john</user-name>
   </group-mapping>
   <group-mapping>
      <group-name>child1subgroup</group-name>
      <user-name>username7</user-name>
   </group-mapping>
   <group-mapping>
      <group-name>childgroup1</group-name>
      <child-group>child1subgroup</child-group>
      <user-name>username4</user-name>
      <user-name>username5</user-name>
   </group-mapping>
   <group-mapping>
      <group-name>childgroup2</group-name>
      <user-name>username6</user-name>
   </group-mapping>
   <group-mapping>
      <group-name>parentgroup1</group-name>
      <child-group>childgroup1</child-group>
      <child-group>childgroup2</child-group>
      <user-name>username1</user-name>
      <user-name>username2</user-name>
      <user-name>username3</user-name>
   </group-mapping>
</realm>
Note:
  • The password specified in the XML file can be plain text or hashed.
  • Plain text passwords can be specified using the <plaintext> element in the XML file. Any plain text passwords inside <plaintext> elements are converted automatically. The file is rewritten and all plain text entries are replaced with hashed passwords according to the hashAlgorithm and repetitionCount attributes defined in the same XML file.
  • To generate the password hashes, you can use the asg-password-hasher.exe utility provided by TIBCO API Exchange Gateway. See asg-password-hasher Tool.

For the hashed password, the following attributes must be defined in the XML file:

  • hashAlgorithm

The hashAlgorithm attribute can have one of the following values: 

  • SHA1
SHA-256
SHA-384
SHA-512
PBKDF2WithHmacSHA1
PBKDF2WithHmacSHA256
PBKDF2WithHmacSHA384
PBKDF2WithHmacSHA512

    The default value is PBKDF2WithHmacSHA256

  • repetitionCount

    repetitionCount is the number of iterations used to compute the hash for the password. The higher the repetitionCount, the harder it becomes for an attacker to crack the password. However, using a higher repetition consumes more CPU time during the password verification.

    The default value is 1000.

    Note: The values of hashAlgorithm and repetitionCount apply to all hashed passwords in the XML file.

Schema for XML File

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- (C) Copyright 2009-2014, Cloud Software Group, Inc. All rights reserved.
-->
<!-- ********************************
this is schema is for illustration.  The real version is shipped as part of the code.
***********************************
-->
<schema targetNamespace="http://xsd.tns.tibco.com/trinity/realm/2013"
 xmlns:tns="http://xsd.tns.tibco.com/trinity/realm/2013" xmlns="http://www.w3.org/2001/XMLSchema"
 version="2.0" elementFormDefault="qualified">
 <element name="realm">
  <complexType>
   <sequence>
    <element name="users">
     <complexType>
      <sequence>
       <element name="user" minOccurs="0" maxOccurs="unbounded">
        <complexType>
         <sequence>
          <element name="name" type="tns:non-empty-string" />
          <choice>
           <element name="plaintext" type="string" />
           <element name="password">
            <complexType>
             <simpleContent>
              <extension base="base64Binary">
               <attribute name="salt" type="base64Binary" use="required" />
              </extension>
             </simpleContent>
            </complexType>
           </element>
          </choice>
         </sequence>
        </complexType>
       </element>
      </sequence>
     </complexType>
    </element>
    <element name="group-mapping" minOccurs="0" maxOccurs="unbounded">
     <complexType>
      <sequence>
       <element name="group-name" type="tns:non-empty-string" />
       <element name="child-group" type="tns:non-empty-string"
        minOccurs="0" maxOccurs="unbounded" />
       <element name="user-name" type="tns:non-empty-string"
        minOccurs="0" maxOccurs="unbounded" />
      </sequence>
     </complexType>
     <unique name="non-redundant-users">
      <selector xpath="tns:user-name" />
      <field xpath="." />
     </unique>
     <unique name="non-redundant-child-groups">
      <selector xpath="tns:child-group" />
      <field xpath="." />
     </unique>
    </element>
   </sequence>
   <attribute name="hashAlgorithm" type="tns:non-empty-string"
    default="PBKDF2WithHmacSHA256" />
   <attribute name="repetitionCount" type="int" default="1000" />
  </complexType>
  <key name="uniqueUser">
   <selector xpath="./tns:users/tns:user/tns:name" />
   <field xpath="." />
  </key>
  <keyref name="group-refers-to-existing-user" refer="tns:uniqueUser">
   <selector xpath="tns:group-mapping/tns:user-name" />
   <field xpath="." />
  </keyref>
  <unique name="unique-top-level-groups">
   <selector xpath="./tns:group-mapping/tns:group-name" />
   <field xpath="." />
  </unique>
 </element>
 <simpleType name="non-empty-string">
  <restriction base="string">
   <minLength value="1" />
   <maxLength value="255" />
  </restriction>
 </simpleType>
</schema>