xWeb: Configuration Settings
Below is a list of xWeb configuration settings that are set in /xweb/web.config.
- This page is geared toward the netFORUM System Administrator. If you are an integrator/vendor, this information is useful to you but only a system administrator can alter these settings.
- Depending on the xWeb version, these settings might need to be added manually into the web.config file.
Authentication Settings
These are authentication settings:
Expiration
Expiration = [Absolute | Sliding ] - this attribute defines the expiration policy for the message exchange. Sliding expiration resets the authentication token's value after each call and returns a new token value in the response. The newly generated token will have its Timeout reset so that each use will extend its lifetime. Absolute sets an absolute time for the token to expire. This expiration date/time is set when Authenticate is first called, and does not change after that, even after subsequent web method calls. Subsequent uses of that token do not prolong or extend the expiration date/time. The default value is Absolute.
Timeout
Timeout = [integer] - sets the time interval (in minutes) the token will remain valid. The default value is 20 minutes.
FailCount
FailCount = [integer] - the number of authentication attempts per distinct user account + IP Address combination that yield a credential verification error. If the requesting party attempts to authenticate more than the FailCount value, the requesting party will receive a LockOut soap:fault. The value of this attribute and the LockOutHours support each other. The default value is 25. A value of -1 will disable this check. If this number is exceeded you will get the error message Credentials Locked Out when calling Authenticate. See Credentials Locked Out.
LockOutHours
LockOutHours = [integer] - once a requesting party receives a LockOut soap:fault, the value of this attribute governs the number of hours that a requesting party must wait until their account is reset and available for them to commence a message exchange (or NetForum Admin can reset). The default value is 6 hours.
MethodsFaultLimitPerDay
MethodsFaultLimitPerDay = [integer] - the number of non-authenticating soap:faults allowed per day per distinct user account + IP Address combination. If the requesting party exceeds this number, they will have to wait until the next day to re-commence message exchange (or NetForum Admin can reset). The default value is 100. A value of -1 will disable this check. If this number is exceeded you will get the error message Credentials Locked Out when calling Authenticate. See Credentials Locked Out.
Here is an example of how to set the above five settings in the /xweb/web.config file:
<!--
Expiration defines the type of expiration, valid values are Sliding|Absolute.
Sliding expiration resets the authentication token's value after each call, Absolute
sets an absolute time for the token to expire.
Timeout sets the time interval that the token will reamin valid.
-->
<xWebConfig Expiration="Sliding" Timeout="20" LockOutHours="6" FailCount="10" MethodsFaultLimitPerDay="100"/>
<appSettings>...
The settings below are configured in the appSettings section in /xweb/web.config:
FaultWarningEmail
FaultWarningEmail [string] If an email address is entered in this setting, then if either FailCount or MethodsFaultLimitPerDay is exceeded, then xWeb will automatically send an alert email to this address to inform of the lockout, including the IP Address of the account and the userName that was being used. By default, a standard email is sent, but a custom template may be developed and configured with the FaultWarningTemplate setting.
FaultWarningTemplate
FaultWarningTemplate [string as GUID] This is the GUID of the Correspondence Template to be used for this email. There are some special fields that will be parsed. If no value is provided, a default message will be sent.
The special fields are:
- {xws_usr_code} - user account getting locked out
- {xws_usr_ip_address} - ip address getting locked out
- {xws_fail_count} - the count of failures
- {xws_fault_count} - the fault count
- {xws_fail_limit} - the authentication failure limit
- {xws_fault_limit_per_day} - the fault limit
- {xws_add_date} - the current datetime
- {xws_expiration} - for use in Subject line, and body, the expiration date on which the account is re-enabled
ValidateIPaddress
ValidateIPaddress [true | false] This ensures the IP address of the program that requested a token in the Authenticate web method is able to use that token in subsequent web method calls.
MethodsInvokeLimitPerDay
MethodsInvokeLimitPerDay [integer] - not currently used.
AuthenticationTokenCachingPolicy
AuthenticationTokenCachingPolicy [ NoCaching | WebServerCache ] Determines if Authentication Tokens are managed in a database table or in server memory cache. NoCaching (which manages tokens in the database) is the default.
Summary of Authentication Setting
Both FailCount and MethodsFaultLimitPerDay log failures (in Authentication) and faults (in other web method calls) in a userName plus IP Address combination.
For example, suppose a NetForum Site has a single valid xWeb User with the userName/password combination of xWebUserCMS and 8987bXo0. Let's assume that the FailCount setting is 10 and the MethodsFaultLimitPerDay is 50.
Suppose a calling program from IP 13.13.13.13 tries and fails ten times to Authenticate with the correct userName but incorrect passwords. After the 10th failure, then that IP address is locked out. The 13.13.13.13 IP address cannot authenticate under xWebUserCMS or any other user name until the LockOutHours time period elapses. The userName of xWebUserCMS is not locked out -- other IP's can still Authenticate with this account if they submit the correct userName/password combination. Put another way, xWeb doesn't care which userName you try to authenticate with; it only matters which IP Address you try (and fail) to authenticate with. This means that an xWeb User doesn't get locked out, only IP addresses get locked out.
Method Settings
These settings are referenced by one or more xWeb Web Methods.
xwebRecordReturn
xwebRecordReturn [integer] This value determines how many records can be returned in any given query. This setting is important for the GetQuery web method. The default number of records return is a system option setting - DataGridRowLimit. If desired, you may override this default value in xWeb by adding this configuration setting and setting a different value. For NetForum system administrators, this setting will go in the /xweb/web.config in within the <appSettings />. If you are satisfied with the default value in DataGridRowLimit then do not add this configuration setting. See example below.
keyOverrideValue
keyOverrideValue [string as GUID] = this value should be sent by the requesting party as the third parameter in the xWeb: WebLogin method. By passing exactly this value, then the requesting party can return the cst_key for the credentials. For NetForum system administrators, generate a new key, place the value in the appropriate place in xweb/web.config within the <appSettings /> and send to the requesting party. See example below.
To generate a new value for keyOverrideValue run the following in SQL:
SELECT newid()
Get the resultant value and use this value for keyOverrideValue. In reality, you could use any value you want, as long as the value is a proper GUID.
AllowAnyType
AllowAnyType [true | false] - If this is true, the xWeb schema produced by the GetFacadeXMLSchema web method will allow nodes with the any type.
NetForum System Administrator Notice
Except for the first five settings under Authentication, the rest of these settings above are configured in the <appSettings /> section of the /xweb/web.config file. Baseline NetForum xWeb does not ship with these configuration settings. If you want to use either or both of these settings, you will need to modify your /xweb/web.config file and put these settings into it. See example:
<appSettings>
<!-- ... snip ... -->
<add key="xwebRecordReturn" value="50" />
<add key="keyOverrideValue" value="8BCA2B05-48B7-49A6-9AA3-1133BB7C5948" />
<!--If this is true, the xWeb schema will allow nodes with the 'any' type-->
<add key="AllowAnyType" value="true"/>
<!--This is the email to send warnings to when fault limits are reached-->
<add key="FaultWarningEmail" value=""/>
<!--This is the correspondence template to be used for this email. There are some special fields that will be parsed.
If no value is provided, a default message will be sent-->
<add key="FaultWarningTemplate" value=""/>
<!--This will ensure that only the IP that requested a token is able to use that token-->
<add key="ValidateIPaddress" value="true"/>
<add key="SystemGuid" value="96F971DD-694A-4E34-A859-E60B9E5DD73A"/>
<!-- ... snip ... -->
</appSettings>
Miscellaneous Settings
A Timeout setting of -1 will do the following: make all Tokens observe the Absolute Expiration policy, regardless of that setting, and set the expiration date of the cookie to be 100 years in the future.