Previous Contents Index Next |
iPlanet Portal Server Administration Guide |
Chapter 8 Configuring the Gateway
This chapter has the following topics:
Configuring Web Proxies
Web proxies can be configured to contact the Profile Service and to contact the Server and all other machines on the intranet.
Configuring the Web Proxies Used To Contact the Profile Service
Requests from the Gateway to the Server follow the same rules listed below. However these rules do not apply to requests from the Gateway to the Profile Service. Therefore if the Gateway cannot contact the Server directly, and a proxy is necessary, then the following changes must be made on the Gateway, or it will never be able to read its profile information:
From the command line, open to edit the gateway file:
Add the following entries to the DEFINES variable:
-Dhttp.proxyHost=<the name of the proxy host>
-Dhttp.proxyPort=<the proxy's port>
Manually restart the Gateway to use the specified proxy for Profile Service requests made to the server.
Note The gateway is restarted manually since there is no method to tell the Profile Service of the proxy without restarting the gateway; requests would only be received and not processed.
Configuring the Web Proxies for the Server and All Other Machines
The gateway may be configured to contact HTTP resources using web proxies. Different proxies may be used for different domains and subdomains.
Web Proxies for DNS Domains and Subdomains
These entries tell the gateway what web proxy (if any) to use when contacting specific subdomains in specific domains. The syntax for each entry in this list is:domain_name [web_proxy1:port1]|subdomain1 [web_proxy2:port2]|......
* is a wild card that matches everything
The first entry in the list is special. The domain (in the example below, iplanet.com) is considered the 'default domain'. The first subdomain that appears in the first entry (in this case, red) is the 'default subdomain. The default subdomain and domain are relevant for proxying and rewriting URLs that contain hostnames that do not specify a subdomain and domainthe gateway assumes that the hostnames are in the default subdomain and domain, and acts accordingly.
The list entries are processed in order from top to bottom, so the first match that can be made for a requested URL is applied. So, given this example list for DNS Domains and Subdomains:
iplanet.com wp1:8080|red wp2:8080|yellow|* wp3:8080
When the destination host in the requested URL is a fully qualified host name, a particular proxy is specified accordingly. Table 8-1 identifies this URL condition.
When the destination host in the URL is not a fully qualified host name, a particular proxy is specified accordingly (see definition of 'default domain' and 'default subdomain' in ). Table 8-2 identifies this URL condition.
The last two hostnames in Table 8-2 might in fact be fully qualified, and therefore the gateway's assumption that they are in the default domain might be incorrect. However, in most cases this assumption will be correct, since 'red' and 'yellow' are explicitly listed as subdomains in the default domain.
In the final example shown in , however, 'blue' is not in any of the default domain's subdomains. Rather than apply the wildcard subdomain that wp3:8080 applies to, the gateway assumes that this is a fully-qualified name.
To be treated as a host in the default domain, 'blue' would have to be explicitly added to the default domain's list of subdomains, as shown in Table 8-3.
Table 8-3 Destination Host Without A Reference to a Default Domain's Subdomain
Subdomain wildcard in default domain does not apply in this case, so apply wildcard in final list entry.
If a web proxy is not indicated for the target URL through the 'DNS Domains and Subdomains' list as described above, the gateway will connect to the destination host directly.
If a web proxy is indicated, the gateway will check the attribute 'Use Intranet Web Proxy'.
If 'Use Intranet Web Proxy' is true, the gateway will make the request via the web proxy unless the requested URL is found in the list 'Don't Use Web Proxy Enabled', which is a list of URLs. If the requested URL is in that list, then the destination host is contacted directly.
If 'Use Intranet Web Proxy' is false, the gateway will send the request to the destination host directly, unless the requested URL is found in the list 'Use Web Proxy Enabled' which is a list of URLs. If the URL appears there, the gateway will fetch the URL using the web proxy that was indicated by the 'DNS Domains and Subdomains' list.
This list also describes to the gateway which URLs it may rewrite -- only references to hosts in the specified sub/domains are candidates for rewriting. (This can be overridden by the Rewrite All URLs Enabled selection, described in "Rewrite All URLs Enabled" on page 160).
When the URL host is a fully qualified host name, the URL is either rewritten or not rewritten, as shown in (from the list of hosts originally defined in Table 8-1). When the URL host is not a fully qualified name, shown by the last three entries in this table, the URL is not rewritten.
In the final entry of , 'blue' is not in any of the default domains subdomains. Rather than apply the wildcard subdomain, the gateway assumes that this is a fully-qualified name. To be treated as a host in the default domain, 'blue' would have to be explicitly added to the default domain's list of subdomains.
Rewrite All URLs Enabled
If true, the Gateway will rewrite any URL without checking the URLs sub/domains against entries in 'DNS Domains and Subdomains'. If false, the 'DNS Domains and Subdomains' list applies as described above.
Using Virtual IP and DNS Names
Initial user contact with iPlanet Portal Server depends on the gateway configuration and whether a multiple domain configuration exists.For example, users may contact iPlanet Portal Server through a single gateway and domain configuration named https://my.sun.com. Alternatively, each domain within a multi-domain configuration may require users to use different gateway names such as:
https://employee.sun.com and https://partner.sun.com.
The following sections describe the different configurations which may be deployed.
Using One Gateway Name
This is the default configuration after installation. A user may specify which domain they would like to authenticate to by typing in a keyword after the gateway name in the URL. For example, if the gateway name is my.sun.com and there are two iPlanet Portal Server domains, sales and engineering, contact with the gateway will occur from the following URLs:https://my.sun.com/sales, for sales domain users
https://my.sun.com/engineering, for engineering domain users
Each iPlanet Portal Server domain has an attribute "Domain URLs" which contains a list of all the possible strings which the user's may use when authenticating to a particular domain. When the user enters http://my.sun.com/eng, the string my.sun.com/eng is used to set the user's domain for that session. If there is no match for my.sun.com/eng, then the just the /eng is used to check the list. This way if the admin adds a new domain, they do not have to add the name of the gateway.
For example, if the admin wanted to add /eng to the list for the engineering domain, the "Domain URLs" attribute for the engineering domain would be stated as follows:
From the Manage Domains > <domainname>, click on the Authentication profile and locate the Domain URLs attribute.
Click the Add button to add these domain URLs to the list window.
Click the Submit button to submit this change to the Profile Server.
When the `Profile Successfully Updated' message is displayed, click the Continue button.
Multi-hosting or Multiple Gateway Names
If it is not desirable to require the user to type in their domain, the gateway can be configured to use multiple DNS names or virtual IP addresses. For example, instead of the sales employees using:and your engineering employees using:
https://eng.sun.com and https://sales.sun.com.
In order to configure the gateway for multiple DNS names or virtual IP addresses, perform the following steps.
Navigate to the domain of interest (engineering or sales) and click the Authentication profile link to find the Domain URLs attribute.
For the engineering domain add the following link:
To provide both choices for users, add /eng and /sales to the attributes above.
Click the Server Management link at the left frame of the admin console.
Click on the Manage Server Profile link.
- If the company domain for the gateway names does not match that of the installed name for the gateway, that domain must be added to the "Cookie Domain List" attribute in the server profile.
Add the company DNS domain to the "Cookie Domain List" attribute.
Add the gateway name to the ips.virtualhost parameter in the file /etc/opt/SUNWips/platform.conf on the gateway. This parameter is a space separated list of all the gateway names and IP addresses. For this example, the ips.virtualhost parameter appears as follows:
ips.virtualhost=eng.sun.com sales.sun.com 129.122.22.33
Restart the gateway. This may be done through the admin console under Gateway Management or via command line as:
- /opt/SUNWips/bin/ipsgateway start.
Configuring the Rewriter
The Gateway's Rewriter function allows end users to browse to Intranet web pages, and also makes links and other URL references on those pages (e.g., an image's source) operate correctly.The basic operation performed by the gateway to achieve this is to pre-pend a reference to itself for each link that it encounters. Thus, within the user's browser, an HTMl fragment such as:
<a href="http://mymachine.intranet.com/mypage.html>
could be translated by the gateway's rewriter to:
<ahref="https://gateway.company.com/http://mymachine.intranet.
Now, when the user clicks a link associated with this anchor, the browser will contact the gateway, which will then fetch the content of mypage.html from mymachine.intranet.com. Thus machines which are not normally accessible from the intranet may be browsed via the gateway's rewriting function.
The gateway uses several rules to determine what elements of a fetched HTML page will be rewritten. These rules are also referred to as translation. Strings starting with "/", "../", "http" and "https" are considered to be URLs and are candidates for rewriting. If a string is considered a URL, then it must refer to a machine within a subdomain or domain that can be rewritten by the gateway. Subdomains and domains that the gateway rewrites for are determined by the entries in the list 'DNS Domains and Subdomains'. This list is also used to assign web proxies to the various subdomains and domains that are rewritten.
Additionally, the variable syntaxes of JavaScript and Java may require the administrator to specify customized rules to handle web pages on their intranet.
The following lists in the Gateway Profile page allow the administrator to specify URLs for the gateway to rewrite. This customization is necessary in several situations as:
JavaScript can contain URLs in arbitrary locations, therefore the gateway cannot parse JavaScript and determine which elements are URLs
In the examples below, assume that 'urlX' is a string that appears to the gateway to be a URL. Strings starting with "/", "../", "http" and "https" are considered to be URLs. Strings starting with any other substrings are not considered to be URLs and will not be rewritten.Java Applet parameters are interpreted by the applets, so the syntax of the parameters is unpredictable. Hence the gateway cannot locate URLs in applet parameters without guidance.
Rewriting HTML Attributes
This entry contains a list of HTML attributes. The gateway will rewrite URLs in the value of these attributes.<a href="some URL">some text</a>
By default, "some URL" will be rewritten if 'href' is in the list.
Rewriting Form Input Tags List
Each entry in this list has syntax:object_of_url_with_form form_name input_or_option_name [url_pattern]
The url_pattern is used to match the substring before the URL in the value. If url_pattern is missing, the value is a pure URL. The gateway will rewrite the URL in input of option value if there is a match. The wild card will match any string.
Suppose the gateway receives a request with the following URL:
http://some_server/some_dir/some.html
The response content is as follows:
<Form name=form1 method=POST action="http://some_server/demo">
<input type=text name=iplanet1 value="url1">
<input type=text name=iplanet2 value="0|234|test|url2">
<option value="url3">text1</option>
<option value="url4">text1</option>
object_of_url_with_form doesn't match the object of the requested URL.
/some_dir/some.html * * url1, url3, url4
*/some.html * * url1, url3, url4
/some_dir/* * * url1, url3, url4
form_name doesn't match the form name.
Rewriting HTML Attributes Containing JavaScript
This entry contains a list of HTML attributes. The gateway will rewrite JavaScript in the value string of these attributes.<body bgcolor="white" onLoad="surl='/index.html';" topmargin="0"
will be rewritten if 'onLoad' is in the list (the default).
Rewriting JavaScript Function Parameters
Each entry in this list has the following syntax:java_script_function_name:[y|],[y|],......
The gateway will rewrite URLs in parameters of JavaScript functions if there is a match.
Suppose the list has 3 entries:
<script language="JavaScript">
func1("url1", "url2", "url3");
func2("url4", "url5", "url6", "url7", "url8");
func3("url9", "url10", "url11", "url12", "url13");
The gateway will rewrite url1, url6, url8, url9, url10, url12.
Rewriting JavaScript Variables in URLs
This function contains a list of JavaScript variables. The gateway will rewrite the URL in the value assigned to the variables.<script language="JavaScript">
The gateway will rewrite url1, url2 if x1 and x2 if they are in the list.
Rewriting JavaScript Variables Function
This function contains a list of JavaScript variables. The gateway will wrap the value that is assigned to the variables with a function called iplanet. This function is inserted into HTML pages (if necessary) before they are sent back to the user's browser. The function indicated below programmatically determines whether, and how, to rewrite the URL.<script language="JavaScript">
x1 = "some text" + some_var + some_function();
<script language="JavaScript">
x1 =iplanet( "some text" + some_var + some_function());
return 'https://' + gwhost + ':443/http://server host:8080' +
index = url.indexOf('http://127.0.0.1');
index = url.indexOf('https://127.0.0.1');
index = url.indexOf('http://localhost');
index = url.indexOf('https://localhost');
index = url.indexOf('https://' + gwhost + ':443/');
index = url.indexOf('https://' + gwhost + '/');
return ('https://' + gwhost + ':443/redirect/' + url);
Rewriting JavaScript Function Parameters in HTML
Each entry in this list has the following syntax:java_script_function_name:[y|],[y|],......
The gateway will rewrite the HTML in the parameters of the JavaScript function if there is a match.
<script language="JavaScript">
document.write('<html><a href="/index.html">link</a></html>');
The gateway will rewrite the HTML embedded in the function's parameters:
<html><a href="/index.html">link</a></html>
Rewriting JavaScript Variables in HTML
This entry contains a list of JavaScript variables. The gateway will rewrite HTML in the value that is assigned to the variables.<script language="JavaScript">
varHTML x = "<a href=http://peregringo.eng.sun.com/appliance/index.html>";
<a href=http://peregringo.eng.sun.com/appliance/index.html>
will be rewritten if varHTML is in the list.
Rewriting Applet Parameter Values List
Each entry in this list has this syntax:object_of_appplet_url applet_class applet_parameter_name [url_pattern]
If url_pattern is omitted, the value of the applet parameter is examined be a single URL, and the gateway will rewrite accordingly.
If url_pattern is included, then it contains one or more strings separated by the character that is used in the applet startup code to separate the fields of the value. If the url_pattern matches the start of the string in the specified applet parameter, then the remainder of the parameter value will be considered a URL to be rewritten.
A wildcard (*) in the url_pattern will match any string in all of the above entries.
Suppose the gateway receives a request for the URL:
http://some_server/some_dir/some.html
<applet archive=iplanet.jar code=iplanet.class>
<param name=server1 value="url1">
<param name=server2 value="url2">
<param name=server3 value="0|234|test|url3">
<param name=anotherParam value="yes,5,url4">
Then, if the list contains this entry, the following URLs will be rewritten as noted in Table.
some.html iplanet.class * none object_of_applet_url doesn'tmatch object of the requested URL.
/some_dir/some.html iplanet.class * url1, url2 but not url3 or url4, since they are embedded within strings that do not appear tobe URLs (i.e. they do not start with "/", "http" or "https").
/some_dir/some.html iplanet2.class * none iplanet2.class is not in the applet tag.
* * server* *|*|*| url3 *|*|*| matches 0|234|test|
Running In HTTP mode
The gateway runs in HTTPS mode after installation, accepting SSL connections from browsers and rejecting non-SSL connections. However, you can configure the gateway to run in HTTP mode using the following steps. The benefits of doing this are performance related since there is overhead involved in managing SSL sessions and encrypting and decrypting the SSL traffic. Eliminating these steps speeds gateway performance.
Log in to admin console.
Click 'Gateway Management' in left frame.
Click 'Manage Gateway Profile' in right frame.
Click 'Show Advanced Options' button at the bottom of the page.
Locate the 'Gateway Port' attribute and change to the port desired for http protocol.
Locate the 'Gateway Protocol' attribute and change it to http.
Click the 'Submit' button at the bottom of the page.
Click 'Server Management' in left frame.
Click 'Manage Server Profile' in right frame.
Locate the 'Gateway Port' attribute and change to the port entered in step 5.
Click the 'Submit' button at the bottom of the page.
From the terminal window, log on as root on the gateway machine.
Open the file: /etc/opt/SUNWips/platform.conf.
Locate the string 'ips.gateway.protocol' and change the value to http
Locate the string 'ips.gateway.port' and change it to the value of the port defined in step 5.
Save the file and exit the text editor.
From the terminal window, restart the gateway by issuing the command:
Configuring The Gateway Proxy
The gateway proxy is essentially a second gateway that can be run on the Server machine. When used, the gateway will send HTTP requests to the gateway proxy instead of directly to the destination host. The gateway proxy will then send the request to destination server. There are two advantages when using the gateway proxy:
If there is a firewall between the gateway and server, the firewall needs only open one hole.
The gateway proxy doesn't run after installation. Instead, enable the gateway proxy as follows.The HTTP traffic is now secure between the gateway and the intranet even if the destination server only supports http protocol (no HTTPS).
Login to admin console.
Click 'Gateway Management' in left frame.
Click 'Manage Gateway Profile' in right frame.
Click 'Show Advanced Options' button at the bottom of the page.
Click the 'HTTP Proxy Enabled' button to enable the http proxy.
Click the 'HTTP Proxy Port' and change to the desired port for gateway proxy listening.
Run /opt/SUNWips/bin/certadmin on the Server to create a certificate for the Gateway proxy.
Start the gateway proxy on the Server by typing:
/opt/SUNWips/bin/ipshttpd start
Note This may be added to init.d so that the proxy will be started whenever the machine is restarted.
Restart the gateway by typing:
/opt/SUNWips/bin/ipsgateway start
Enabling PDC
This section is described in Chapter 6, "Configuring Personal Digital Certificates (PDCs) and Encoded Devices Authentication" on page 110.
IP Address Validation
IP address validation is an attribute that can be set on or off from a check box on the Admin Console using the link Gateway Profile>Manage Gateway Profile on the admin console. With this attribute enabled, when a user logs in to iPlanet Portal Server, the gateway will store the source IP address of the client that made the login request. The source IP address of the client's subsequent requests will be compared to the IP address stored in the session. If there is a mismatch, the request will be denied.If the client browser uses a web proxy to connect to the gateway, the source IP address will be the IP address of the web proxy, not the browser. If the web proxy is using load balancing, the source IP address may change during the user's session causing an incorrect session invalidation. Thus, for general purpose deployments, it is recommended to turn off this attribute.
HTTP Basic Authentication
HTTP basic authentication can be set from the Gateway Profile page in the Admin Console. This page is accessed from the Gateway Management link on the left frame.Web sites may be protected with HTTP Basic Authentication, requiring visitors to enter a username and password before viewing the site (the HTTP response code is 401 and WWW-authenticate: BASIC). iPlanet Portal Server can save the username and password so that users need not re-enter their credentials when they revisit BASIC-protected web sites.
This setting does not determine whether or not a user may visit BASIC-protected sites, but only whether the credentials the user enters will be saved in the user's profile.
This setting applies to all web sites that the user is permitted to access (i.e., HTTP BASIC authentication caching can not be enabled for some sites and disabled for others).
Forward Cookie Configuration
iPlanet Portal Server utilizes a cookie to track user sessions. This cookie is forwarded to the Server when the Gateway makes HTTP requests to the Server (e.g. when the desktop servlet is called to generate the user's desktop page). Applications on the Server use the cookie to validate and identify the user using the Portal Server's APIs.The Portal Server's cookie is not forwarded to HTTP requests made to machines other than the server, unless URLs on those machines are specified in the Forward Cookie URL List. Adding URLs to this list therefore enables servlets and CGIs to receive the Portal Server's cookie and use the APIs to identify the user.
URLs are matched using an implicit trailing wildcard. For example, the default entry in the list:
causes the cookie to be forwarded to all URLs starting with "http://server:8080".
http://newmachine.eng.sun.com/subdir
will cause the cookie to be forwarded to all URLs starting with that exact string.
Similarly, the cookie would not be forwarded to URLs starting with "https://newmachine.eng.sun.com/subdir" unless an appropriate entry were added to the list.
Non-Portal Server Cookie Management
Many web sites use cookies to track and manage user sessions. When the gateway proxies requests to web sites that set cookies in the HTTP header, the gateway will either discard or pass-through those cookies in the following manner:
discard all cookies if this attribute is set 'false'
This setting does not apply to the cookie used by the iPlanet Portal Server to track Portal Server user sessions. It is controlled by the 'Forward Cookie URL List' described above.pass-through all cookies to the user's browser and back to the appropriate web site(s) when the user makes subsequent visits to the web site(s) if this attribute is set 'true'
This setting applies to all web sites that the user is permitted to access (i.e., you cannot choose to discard cookies from some sites and retain cookies from others).
Previous Contents Index Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated May 04, 2000