VSA API Web Service Security

General

The VSA API Web Service is accessible, by default, from any IP address in the world using any valid VSAuser credentials. In this default configuration, valid username /password combinations are considered for authentication originating from any machine.

In any configuration, the hash.dll provided by the VSA must be used to encrypt the password for submission. Implementation details for the hash.dll are contained in the sample source code provided.

Once a successful Authenticate request issues a SessionID, this SessionID must be submitted with every service invocation, and is only valid when received from the IP address it was issued to. The issued SessionID expires after a period of inactivity.

Security can be enhanced by preparing and deploying an AccessRules.xml file. This file is used by the VSA API Web Service to define access rules based on the IP addresses requests are received from. IP filtering is a mechanism commonly used in business-to-business systems to ensure that requests are honored only from the partner’s servers.

The AccessRules.xml file is divided into three sections:

• Default Access Rules
• IP Ranges
• User Mapping

Note: 127.0.0.1 (localhost) always has access for any account, regardless of configuration.

XML Structure

<AccessRules>

	<DefaultAccessRules>

		<GrantAnyIPToUndefinedUsers/>

		<GrantAllIPRangesToUndefinedUsers/>

		<DenyAccessToUndefinedUsers/>

	</DefaultAccessRules>

	<IPRanges>

		<IPRange RangeID="" FromIPAddress="" ToIPAddress="" RangeDescription=""/>

		<IPRange RangeID="" FromIPAddress="" ToIPAddress="" RangeDescription=""/>

	</IPRanges>

	<UserMapping>

		<User UserName="" RangeID="" GrantAllRanges="" GrantAnyIP="" DenyAccess=""/>

		<User UserName="" RangeID="" GrantAllRanges="" GrantAnyIP="" DenyAccess=""/>

	</UserMapping>

</AccessRules>

Default Access Rules

The elements in this section define the access rules for those accounts that are not specifically addressed in the User Mapping section.

<GrantAnyIPToUndefinedUsers/> true/false

true: Any user not in UserMapping gets access from any IP address.

<GrantAllIPRangesToUndefinedUsers/> true/false

true: Any user not in UserMapping gets access from any IP address contained in IPRanges.

<DenyAccessToUndefinedUsers/> true/false

true: Any user not in UserMapping denied access.

IP Ranges

This section is used to define specific machines, or ranges of machines, by IP, that are used to assign user access.

RangeID="integer"

An arbitrary, user assigned integer used to refer to the Range in UserMapping.

FromIPAddress="string"

Starting IP address, inclusive. First three positions of the quartet must match ToIPAddress.

ToIPAddress=" string"

Ending IP address, inclusive. First three positions of the quartet must match FromIPAddress.

RangeDescription=" string"

Description of the IP Range. For example: “Production Servers”.

User Mapping

UserName="string"

The VSA Admin name. The VSA API Web Service uses the same credentials and password encryption as VSA. So, if you change your password in VSA, be sure to change it in your VSA API Web Service client implementation, as well.

RangeID="integer"

Used to point to a defined IP Range in the IP Ranges section. A user can have multiple UserMapping elements to express all the IP Ranges he has access from. Not used when one of the Grant / Deny attributes below are used.

GrantAllRanges="true/false"

true: User has access from any range defined in the IP Ranges section.

GrantAnyIP=" true/false"

true: User has access from any IP address.

DenyAccess=" true/false"

true: User has no access at all.

Sample Access Configuration XML

<AccessRules>

	<DefaultAccessRules>

		<GrantAnyIPToUndefinedUsers>false</GrantAnyIPToUndefinedUsers>

		<GrantAllIPRangesToUndefinedUsers>false</GrantAllIPRangesToUndefinedUsers>

		<DenyAccessToUndefinedUsers>true</DenyAccessToUndefinedUsers>

	</DefaultAccessRules>

	<IPRanges>

		<IPRange RangeID="1" FromIPAddress="192.168.214.01" ToIPAddress="192.168.214.10" RangeDescription="Partner X Production Web Farm"/>

		<IPRange RangeID="2" FromIPAddress="192.168.15.102" ToIPAddress="192.168.15.102" RangeDescription="Senior Developer Machine"/>

		<IPRange RangeID="3" FromIPAddress="192.168.15.105" ToIPAddress="192.168.15.109" RangeDescription="Sales Demo Machines"/>

		<IPRange RangeID="4" FromIPAddress="192.168.210.35" ToIPAddress="192.168.210.35" RangeDescription="Interal QA Machine"/>

	</IPRanges>

	<UserMapping>

		<User UserName="B2BMasterAdmin" RangeID="1" GrantAllRanges="false" GrantAnyIP="false" DenyAccess="false"/>

		<User UserName="DevTestAccount" RangeID="2" GrantAllRanges="false" GrantAnyIP="false" DenyAccess="false"/>

		<User UserName="SalesTestAccount" RangeID="3" GrantAllRanges="false" GrantAnyIP="false" DenyAccess="false"/>

		<User UserName="SalesTestAccount2" RangeID="3" GrantAllRanges="false" GrantAnyIP="false" DenyAccess="false"/>

		<User UserName="QAMasterAdmin" RangeID="4" GrantAllRanges="false" GrantAnyIP="false" DenyAccess="false"/>

		<User UserName="SalesTravellingTestAccount" RangeID="" GrantAllRanges="false" GrantAnyIP="true" DenyAccess="false"/>

		<User UserName="Bob" RangeID="" GrantAllRanges="true" GrantAnyIP="false" DenyAccess="false"/>

		<User UserName="Sally" RangeID="" GrantAllRanges="false" GrantAnyIP="false" DenyAccess="true"/>

	</UserMapping>

</AccessRules>