This article applies to:
Question:
- Authentication problems when using Apple clients through WebMarshal
- Authentication problems when using Microsoft Silverlight Player through WebMarshal
- Authentication problems with browser helper applications
Background:
In certain circumstances, browsers and browser plug-ins fail to authenticate with the Proxy. These pieces of software see the authentication request as a general failure and fail the request.
- This issue is known to affect Apple Macintosh operating systems. Other software such as Silverlight Player and iTunes are also affected.
The Authentication Bypass mechanism described here is an advanced feature designed to overcome this limitation in the client software. It is not limited to the named clients and could be used anywhere that a similar problem occurs.
This feature is applied on the WebMarshal server, and it requires no changes to client workstations.
Note: In WebMarshal 6.9 and above, with Windows clients another option is to use the WMProxyLogon helper application. See Trustwave Knowledgebase article Q14348. WMProxyLogon is simpler, but less flexible. WMProxyLogon is applied on the client workstations, and it does not require any changes on the WebMarshal server.
Procedure:
The authentication bypass mechanism makes a short-term association between an IP address and a user.
When a user is authenticated with WebMarshal from a particular workstation (normally with a standard browser session), any new connections made to the Proxy from that workstation will be automatically authenticated with the user's credentials, based on the IP address.
A number of configuration options are available to ensure that the feature applies only to an intended set of client workstations, and only to certain software clients.
This feature is configured by making changes to the WMProxy.config.xml file on the WebMarshal server, or on each processing node in a WebMarshal array.
- Back up the WMProxy.config.xml file before making changes.
- To apply the changes, restart the WebMarshal Proxy service.
Some sample configuration sections are shown below.
Note: You must modify the examples to suit the local environment.
1. Apple Macintosh client sample
<WebMarshal>
<Proxy>
<Config>
<Authentication>
<Bypass enabled="true" timeout="60">
<IPAddress default="exclude">
<Include>127.0.0.1</Include>
<Include>192.168.0.0-192.168.255.255</Include>
<Exclude>192.168.100.1-192.168.100.16</Exclude>
</IPAddress>
<UserAgent default="include">
<Exclude regex="true" matchCase="false">mozilla/[45]\.0 </Exclude>
<Include matchCase="true">compatible; MSIE</Include>
</UserAgent>
</Bypass>
</Authentication>
</Config>
</Proxy>
</WebMarshal>
2. Silverlight Player sample
<WebMarshal>
<Proxy>
<Config>
<Authentication>
<Bypass enabled="true" timeout="60">
<IPAddress default="exclude">
<Include>127.0.0.1</Include>
<Include>192.168.0.0-192.168.255.255</Include>
<Exclude>192.168.100.1-192.168.100.16</Exclude>
</IPAddress>
<UserAgent default="exclude">
<Include matchCase="true">NSPlayer</Include>
</UserAgent>
</Bypass>
</Authentication>
</Config>
</Proxy>
</WebMarshal>
3. Simple Shockwave Flash sample
<WebMarshal>
<Proxy>
<Config>
<Authentication>
<Bypass enabled="true" timeout="60">
<IPAddress default="exclude">
<Include>192.168.0.0-192.168.255.255</Include>
</IPAddress>
<UserAgent default="exclude">
<Include matchCase="true">Shockwave Flash</Include>
</UserAgent>
</Bypass>
</Authentication>
</Config>
</Proxy>
</WebMarshal>
4. iTunes sample
Some recent versions of iTunes are reported to have a problem with proxy authentication (affecting use with any proxy server).
In this sample, note the timeout value. The user may need to browse normally (to any website using an ordinary web browser) every few minutes to maintain the cached authentication.
Limit IP addresses to a defined range. Set the range (or single IP address) as required.
<WebMarshal>
<Proxy>
<Config>
<Authentication>
<Bypass enabled="true" timeout="300">
<IPAddress default="exclude">
<Include>192.168.0.0-192.168.255.255</Include>
</IPAddress>
<UserAgent default="exclude">
<Include matchCase="true">iTunes</Include>
</UserAgent>
</Bypass>
</Authentication>
</Config>
</Proxy>
</WebMarshal>
See below for more information on each of the configuration options.
Note: XML element and attribute names are case-sensitive, and elements must be closed correctly. Invalid XML syntax in this file can prevent the Proxy service starting.
- For general information about editing XML settings files, see Trustwave Knowledgebase article Q12705.
Authentication Bypass Parameters
<Authentication>
This XML element is an existing WebMarshal Proxy configuration option. If it does not currently appear in your configuration file, you can simply add it as it appears in the example.
If this XML element does appear in your configuration file, you might need to alter it in order to add XML elements within it.
- If the tag is in this form:
<Authentication ... />
- You will need to change it to this form:
<Authentication ...>
</Authentication>
<Bypass>
This XML element controls the basic operation of the authentication bypass mechanism.
This element can include the following XML attributes:
enabled=
This XML attribute determines whether the authentication bypass mechanism is activated or not.
- If the value is "true", "yes" or "1", the authentication bypass mechanism is activated and may automatically authenticate users.
- If the value is any other string or the enabled attribute is missing, the authentication bypass mechanism is not activated and authentication occurs normally.
timeout=
This XML attribute controls the period of time during which the Proxy will automatically authenticate requests based on the source IP address. The timeout period is measured in seconds and is specified by the value inside the quotation marks.
The value must be a positive whole number.
If the value is zero, negative or not a number, of if the timeout attribute is missing, the default timeout of 60 seconds is used.
This timeout value is evaluated from the last time that the client successfully connected to the Proxy. If the client continues to make connections within the timeout period, the Proxy will continue to use the credentials associated with the IP address. Large timeout values can cause problems in environments where IP addresses change frequently, or where workstations are shared between users.
<IPAddress>
This XML element controls which client IP addresses the authentication bypass mechanism may operate on. If an IP address is implicitly or explicitly excluded, it will not be automatically authenticated.
This element has a single attribute, but can contain any number of <Include> or <Exclude> elements.
If this XML element is not present, the authentication bypass will apply to all IP addresses.
This element can include the following XML attribute:
default=
This XML attribute specifies whether IP addresses should be included or excluded by default.
- If the value is "include" or if the default attribute is missing, the default action will be to include IP addresses unless explicitly excluded.
- If the value is present and is anything other than "include", the default action will be to exclude all IP addresses unless explicitly included.
Note that the default action will determine how the <Include> and <Exclude> rules operate.
- If the default action is to include, any IP addresses matched by <Include> rules will always be included, regardless of whether the user agent is also matched by an <Exclude> rule.
- If the default action is to exclude, any IP addresses matched by <Exclude> rules will always be excluded, regardless of whether the user agent is also matched by an <Include> rule.
<IPAddress>
<Exclude> </Exclude>
<Include> <Include>
</IPAddress>
These XML elements are used to specify which IP addresses are explicitly included or excluded in the set of user agents that the authentication bypass mechanism works on.
Both elements work in the same way. The text within the element (between the starting and ending tags) can contain either a single IP address or a range of IP addresses.
Examples:
To include the single IP address 1.2.3.4:
<Include>1.2.3.4</Include>
To exclude the IP address range 192.168.0.0/8 (192.168.0.0/255.255.255.0):
<Exclude>192.168.0.0-192.168.0.255</Exclude>
<UserAgent>
This XML element controls what client user agents the authentication bypass mechanism may operate on. If a user agent is implicitly or explicitly excluded, any requests from that agent will not be automatically authenticated.
User agents are the pieces of software that end-users use to access the Internet. The most common user agents are web browsers, but other software such as SSL VPN clients or antivirus updaters is also included.
User agents identify themselves by sending an identifying header with every request. This header is defined in the specification for HTTP (RFC-2616, sec 14.43). While user agents are supposed to send this header when possible, not all user agents do send this information.
This element has a single attribute, but can contain any number of <Include> or <Exclude> elements.
If this XML element is not present, the authentication bypass will apply to all user agents.
This element can include the following XML attribute:
default=
This XML attribute specifies whether user agents should be included or excluded by default.
- If the value is "include" or if the default attribute is missing, the default action will be to include user agents unless explicitly excluded.
- If the value is present and is anything other than "include", the default action will be to exclude all user agents unless explicitly included.
Note that the default action will determine how the <Include> and <Exclude> rules operate.
- If the default action is to include, any user agents matched by <Include> rules will always be included, regardless of whether the user agent is also matched by an <Exclude> rule.
- If the default action is to exclude, any user agents matched by <Exclude> rules will always be excluded, regardless of whether the user agent is also matched by an <Include> rule.
<UserAgent>
<Exclude> </Exclude>
<Include> <Include>
</UserAgent>
These XML elements are used to specify which user agents are explicitly included or excluded in the set of user agents that the authentication bypass mechanism works on.
Both elements work in the same way. For each request, WebMarshal searches for the text within the element (between the starting and ending tags) in the user agent identifier reported.
- If the text is found in the user agent identifier, the user agent is either included or excluded, depending on the XML element used.
This element can include either or both of the following XML attributes:
matchCase=
This XML attribute specifies whether or not character case is considered when examining the user agent identifier reported in the request. This attribute applies for both regular expressions and text string matching.
- If the value inside the quotation marks is "true", "yes" or "1", upper-case and lower-case letters must match exactly.
- If the value is anything else, or the matchCase attribute is missing, no distinction will be made between upper-case and lower-case letters.
regex=
This XML attribute specifies whether the text inside the <Include> or <Exclude> element specifies a regular expression.
Regular expressions are a powerful tool that can be used to match patterns of characters. They use a special syntax and can be hard to read and understand.
- If the value is "true", "yes" or "1", the text of the element defines a regular expression. The user agent identifier of each request will be evaluated using the regular expression. If the expression matches then the user agent is considered to match.
- To match the entire user agent string, start the regular expression with "^" (start of line) and end it with "$" (end of line).
- To specify case-sensitive matching, use the matchCase attribute.
- If the value is anything else, or the regex attribute is missing, the text inside the <Include> or <Exclude> element is evaluated as a text string. If this text is found in the user agent identifier then the user agent is considered to match.
- To specify case-sensitive matching, use the matchCase attribute.