Copyright © Cloud Software Group, Inc. All Rights Reserved

Configure User Authentication Policy using File

Configure the user authentication policy using a file resource as described in the following steps:

 

Task A Create a shared resource

See Create a Shared Resource Properties File.

Task B Create an XML file for user credentials

See Create XML File for Credentials.

Task C Create policy

See Create Policy File.

Task D Register the policies in the system

See Register Policy.

Task E Apply the policies to the target operation

See Apply Policy.

Create a Shared Resource Properties File

TIBCO API Exchange Gateway uses a shared resource properties file to support the user authentication using a file resource. For example, the shared resource properties file defines a property which refers to an XML file containing the user credentials.

TIBCO API Exchange Gateway provides a sample properties file XmlAsp.properties for the shared resource. Use this file as a template and edit the properties, as required.

Sample Property File

The location of the shared resource property file for user authentication using the file resource is as follows:

ASG_CONFIG_HOME/BookQuerySecurity/security/resource/XmlAsp.properties

XmlAsp.properties

---

 

com.tibco.trinity.runtime.core.provider.lookup=com.tibco.trinity.runtime.core.provider.authn.xml

# Location of the users, password, and group file.

com.tibco.trinity.runtime.core.provider.authn.xml.fileLocation=XmlAspUsers.xml

---

 

Properties

The following table describes the properties for the user authentication using file resource.

Table 111 Shared Resource Property for XML File Based Authentication

Property	Description
com.tibco.trinity.runtime.core.provider.authn.xml.fileLocation
	Specifies the name of the XML file containing the credentials of the user(s) required for authentication. The location of the XML file can be either a relative path or an absolute file path. The relative file path is relative to the ASG_CONFIG_HOME/ASGProjectConfiguration/security/resource directory. For example, XmlAspUsers.xml is found in the following directory: ASG_CONFIG_HOME/BookQuerySecurity/security/resource. See Create XML File for Credentials.

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="1000">

<users>

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

---

 

 

• 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

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>

---

 

asg-password-hasher Tool

TIBCO API Exchange Gateway provides a command-line asg-password-hasher.exe utility to generate hash passwords which is located in the ASG_HOME/bin directory.

Input Parameters

The asg-password-hasher.exe utility prompts you to specify the following parameters:

•	HashAlgorithm

The HashAlgorithm parameter is configured as hashAlgorithm attribute in the XML file. The possible values are as follows:

−

SHA1

−

SHA-256

−

SHA-384

−

SHA-512

−	PBKDF2WithHmacSHA1

−	PBKDF2WithHmacSHA256

−	PBKDF2WithHmacSHA384

−	PBKDF2WithHmacSHA512

If you do not specify any value, the default value PBKDF2WithHmacSHA256 is accepted.

•	Iteration count

The Iteration count parameter specifies the repetitionCount attribute in the XML file. If you do not specify any value, the default value 1000 is accepted.

•

password

Specifies the password to hash.

Output

The asg-password-hasher.exe utility generates the password with the salt and hash. The generated hashed password is configured in the XML file.

Sample Output

---

 

C:\tibco\asg\2.1\bin>asg-password-hasher.exe

********************************************************

Calculate the hash for a given password and random salt.

********************************************************

HashAlgorithm (PBKDF2WithHmacSHA256):

[hashAlgorithm=PBKDF2WithHmacSHA256]

Iteration count (1000):

[repetitionCount=1000]

 

Type in password to hash (<Enter> or Ctrl-C to stop): <Type your password at the prompt>

Type in same password again: <Re-type the same password>

log4j:WARN No appenders could be found for logger (com.tibco.security.TIBCOSecurity).

log4j:WARN Please initialize the log4j system properly.

<password salt="XLowtTUDQj6ocTCwpWlPkMwv2wbh/ZBCzBVKBgUglOs=">zfDDla/mcaVUaQj3Vq3kkwnWrA47YPG7kNBfz+8u91g=</password>

---

 

 

Ensure that the values of HashAlgorithm and Iteration count parameters for the asg-password-hasher utility match the hashAlgorithm and repetitionCount attributes specified in the XML file.

Create Policy File

Before you create a policy, ensure that you have created the shared resource properties file. See Create a Shared Resource Properties File for details.

Create the policy file as follows:

1.	Copy the sample template file for your configuration project from the following location:

ASG_CONFIG_HOME/BookQuerySecurity/security/policy/AuthenticationByXml.policy

2.	Edit the parameters in the file, as required. For example, change the ResourceInstance parameter to match the shared resource name as follows:

ResourceInstance="XmlAsp"

The properties for the XmlAsp shared resource are defined in the XmlAsp.properties file which is found in the ASG_CONFIG_HOME/BookQuerySecurity/security/resource directory.

• The policy must be a well formed WS policy. • All the resource instances in the policy must have a shared resource defined.

Sample Policy

The sample file for user authentication using the XML file is located as follows:

ASG_CONFIG_HOME/BookQuerySecurity/security/policy/AuthenticationByXml.policy

 

 

AuthenticationByXml.policy

---

 

<wsp:Policy

xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"

xmlns:wssp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"

xmlns:tpa="http://xsd.tns.tibco.com/governance/policy/action/2009" >

<wsp:All>

<wsp:ExactlyOne>

<tpa:AuthenticationByJaas>

<wssp:SupportingTokens>

<tpa:ExactlyOne>

<wssp:HttpBasicAuthentication />

</tpa:ExactlyOne>

</wssp:SupportingTokens>

<tpa:SharedResourceLoginModule ResourceInstance="XmlAsp" />

</tpa:AuthenticationByJaas>

</wsp:ExactlyOne>

</wsp:All>

</wsp:Policy>

---

 

Register Policy

Register the authentication policy on the Config UI as follows:

−	Upload the policy file.

−	Set the name for a policy.

To register a policy, perform the following steps:

1.	Start the Config UI, if not running.

2.	Log in to the Config UI using your credentials.

3.	Create a new project or select an existing project under Projects.

4.	Click the SECURITY tab.

5.	Click the Policy Mapping tab on the top menu.

6.	Click the Add Property icon to add a new policy mapping.

7.	Enter the following parameters for the policy:

Table 112 Policy Mapping Parameters

Type	Description
Policy Name	• Specifies the name for the policy. • Required.
Intent	Set the intent for the policy. Select Authentication from the drop-down list.
Qualifier	Set the qualifier for policy intent. Select UsernameToken or Basic from the drop-down list, as per your requirement.
New Policy File	Specifies the policy definition file. Browse to choose a new policy file. See Create Policy File to create the policy definition file.
Existing Policy File	Specifies an existing policy definition file. The policy file must exist in the gateway ASG_CONFIG_HOME/ASGProjectConfiguration/policy folder. For example, for the BookQuerySecurity project configuration, the policy file must exist in the ASG_CONFIG_HOME/BookQuerySecurity/policy folder. Select AuthenticationByXml.policy from the drop-down list to use the example policy file.

8.	Save the changes to the project or configuration.

Apply Policy

To apply the registered policy to a target operation, perform the following steps:

1.	Start the Config UI, if not running.

2.	Log in to the Config UI using your credentials.

3.	Create a new configuration or select an existing configuration.

4.	Click the SECURITY tab.

5.	Click the Policy Binding tab on the top menu.

6.	Click the Add Property icon to add a new policy binding.

7.	Specify the following parameters for the policy:

Table 113 Policy Binding Parameters

Type	Description
Policy	Specifies a name for the policy. The policy name must be configured under the Policy Mapping tab.
URI	Specifies the URI of the operation to which the policy is applied.
Facade Operation	Specifies the facade operation to which the policy is applied. The facade operation must be configured in the Facade Operations tab.
Binding	Specifies the binding component that the policy is applied to. The possible values are service and reference. Select service from the drop-down list.
Flow	Specifies the flow of the request. Select IN from the drop-down list as this is applicable only to the facade operation (service).
Target Operation	This field is not applicable for user authentication using the file resource.

8.	Save the changes to the project or configuration.

Copyright © Cloud Software Group, Inc. All Rights Reserved