Sun logo      Previous      Contents      Index      Next     

Sun ONE Portal Server, Secure Remote Access 6.2 Administrator's Guide

Chapter 2
The Gateway

This chapter describes Gateway related concepts and information required for the smooth running of the Gateway. For information on configuring the Gateway, see Chapter 9, "Configuring the Gateway".

This chapter covers the following topics:

Overview of the Gateway

The Gateway provides the interface and security barrier between remote user sessions originating from the Internet and your corporate intranet. The Gateway presents content securely from internal web servers and application servers through a single interface to a remote user.

Creating a Gateway Profile

A gateway profile contains all the information related to gateway configuration, such as the port on which the Gateway listens, SSL options, and proxy options.

When you install a Gateway, if you choose the default values, a default Gateway profile called "default" is created. A configuration file corresponding to the default profile exists at:

/etc/opt/SUNWps/platform.conf.default

where /etc/opt/SUNWps is the default location for all the platform.conf.* files.

See "Understanding the platform.conf File" for more information on the contents of the platform.conf file.

You can:

Caution

Do not assign the same profile to different instances of the Gateway running on the same machine. This will cause a conflict since the port numbers will be the same.

Do not specify the same port numbers in the different profiles created for the same Gateway. Running multiple instances of the same Gateway with the same port will cause a conflict.

    To Create a Gateway Profile
  1. Log in to the Sun™ ONE Identity Server administration console as administrator.
  2. Select the Service Configuration tab.
  3. Click the arrow next to Gateway under SRA Configuration.

    4. The Gateway page displays in the right pane.

  4. Click New.

    5. The Create New Gateway Profile page displays.

  5. Enter the name of new Gateway Profile.
  6. Select the profile to use for creating the new profile from the drop-down list.

    7. By default, any new profile that you create is based on the pre-packaged default profile. If you have created a custom profile, you can select that profile from the drop-down list. The new profile inherits all the attributes of the selected profile.

  7. Click Create.

    8. The new profile is created and you are returned to the Gateway page, where the new profile is listed.

  8. Restart the Gateway with this gateway profile name if you want the changes to take effect:

    9. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

To configure the Gateway, see Chapter 9, "Configuring the Gateway".

Understanding the platform.conf File

The platform.conf file is located at:

/etc/opt/SUNWps

The platform.conf file contains the details that the Gateway needs. This section provides a sample platform.conf file and describes all the entries.

The advantage of including all the machine-specific details in the configuration file is that a common profile can be shared by Gateways running on multiple machines.

Here is a sample:

#

# Copyright 11/28/00 Sun Microsystems, Inc. All Rights Reserved.

# "@(#)platform.conf  1.38 00/11/28 Sun Microsystems"

#

gateway.user=noaccess

gateway.jdk.dir=/usr/java_1.3.1_06

gateway.dsame.agent=http://pserv2.iportal.com:8080/sunportal/RemoteConfigS ervlet

portal.server.protocol=http

portal.server.host=pserv2.iportal.com

portal.server.port=8080

gateway.protocol=https

gateway.host=siroe.india.sun.com

gateway.port=333

gateway.trust_all_server_certs=true

gateway.trust_all_server_cert_domains=false

gateway.virtualhost=siroe1.india.sun.com 10.13.147.81

gateway.virtualhost.defaultOrg=o=root,dc=test,dc=com

gateway.notification.url=/notification

gateway.retries=6

gateway.debug=error

gateway.debug.dir=/var/opt/SUNWps/debug

gateway.logdelimiter=&&

gateway.external.ip=10.12.147.71

gateway.certdir=/etc/opt/SUNWps/cert/portal

gateway.allow.client.caching=true

gateway.userProfile.cacheSize=1024

gateway.userProfile.cacheSleepTime=60000

gateway.userProfile.cacheCleanupTime=300000

gateway.bindipaddress=10.12.147.71

gateway.sockretries=3

gateway.enable.accelerator=false

gateway.enable.customurl=false

gateway.httpurl=http://siroe.india.sun.com

gateway.httpsurl=https://siroe.india.sun.com

gateway.favicon=https://siroe.india.sun.com

gateway.logging.password=ALKJDF123SFLKJJSDFU

Table 2-1 lists and describes all the fields in the platform.conf file. The table has three columns. The first column lists the entries in the file, the second column gives the default value, if any, and the third column gives a brief description of the field.

Table 2-1  The platform.conf File Properties

Entry

Default Value

Description

gateway.user

noaccess

The Gateway runs as this user.

The Gateway must be started as root and after initialization, it loses its root privileges to become this user.

gateway.jdk.dir

 

This is the location of the JDK directory that the Gateway uses.

gateway.dsame.agent

 

This is the URL of the Identity Server that the Gateway contacts while starting up to get its profile.

portal.server.
protocol

portal.server.host

portal.server.port

 

This is the protocol, host and port that the default Portal Server installation is using.

gateway.protocol
gateway.host
gateway.port

 

This is the Gateway protocol, host and port. These values are the same as the mode and port that you specified during installation. These values are used to construct the notification URL.

gateway.trust_all_
server_certs

true

This indicates whether the Gateway has to trust all server certificates, or only those that are in the Gateway certificate database.

gateway.trust_all_
server_cert_domains

false

Whenever there is an SSL communication between the Gateway and a server, a server certificate is presented to the Gateway. By default, the Gateway checks if the server host name is the same as the server certificate CN.

If this attribute value is set to true, the Gateway disables the domain check for the server certificate that it receives.

gateway.virtualhost

 

If the Gateway machines has multiple hostnames configured, you can specify a different name and identity provider address in this field.

gateway.virtualhost.defaultOrg=org

 

This specifies the default Org to which the user will log into.

For example suppose the virtual host field entries are the following:

gateway.virtualhost=test.com employee.test.com

Managers.test.com

with the default org entries as:

test.com.defaultOrg = o=root,dc=test,dc=com

employee.test.com.defaultOrg = o=employee,dc=test,dc=com

Manager.test.com.defaultOrg = o=Manager,dc=test,dc=com

The user can use https://manager.test.com to log into the manager's org instead of https://test.com/o=Manager,dc=test,dc=com

Note: virtualhost and defaultOrg are case sensitive in the platform.conf file, but no when using it in the URL.

gateway.
notification.url

 

A combination of the Gateway host, protocol and port is used to construct the notification URL. This is used to receive session notification from the Identity Server.

Ensure that the notification URL is not the same as any organization name. If the notification URL matches an organization name, a user trying to connect to that organization will get a blank page instead of the login page.

gateway.retries

 

This is the number of times that the Gateway tries to contact the Portal Server while starting up.

gateway.debug

error

This sets the debug level of the Gateway. The debug log file is located at debug-directory/files. The debug file location is specified in the gateway.debug.dir entry.

The debug levels are:

error - Only serious errors are logged in the debug file. The Gateway usually stops functioning when such errors occur.

warning - Warning messages are logged.

message - All debug messages are logged.

on - All debug messages are displayed on the console.

The debug files are:

srapGateway.gateway-profile-name - Contains the Gateway debug messages.

Gateway_to_from_server.gateway-profile-name - In message mode, this file contains all the requests and response headers between the Gateway and internal servers.

To generate this file, change the write permission on /var/opt/SUNWps/debug directory.

Gateway_to_from_browser.gateway-profile-name - In message mode, this file contains all the requests and response headers between the Gateway and the client browser.

To generate this file, change the write permission on /var/opt/SUNWps/debug directory.

gateway.debug.dir

 

This is the directory where all the debug files are generated.

This directory should have sufficient permissions for the user mentioned in gateway.user to write to files.

gateway.
logdelimiter

 

Not used currently.

gateway.external.ip

 

In case of a multi-homed Gateway machine (one with multiple IP addresses), you need to specify the external IP address here. This IP is used for the Netlet to run FTP.

gateway.certdir

 

This specifies the location of the certificate database.

gateway.allow.
client.caching

true

Allow or disallow client caching.

If allowed, client browsers can cache static pages and images for better performance (by reduced network traffic).

If disallowed, there is higher security as nothing is cached at the client side but there will be a performance drop with the higher network load.

gateway.userProfile.cacheSize

 

This is the number of user profile entries that get cached at the Gateway. If the number of entries exceeds this value, frequent retries occur to cleanup the cache.

gateway.userProfile.cacheSleepTime

 

Sets the sleep time, in seconds, for the cache cleanup.

gateway.userProfile.cacheCleanupTime

 

The maximum time in seconds after which a profile entry can get removed.

gateway.
bindipaddress

 

On a multihomed machine, this is the IP address to which the Gateway binds its serversocket.

gateway.sockretries

3

Not used currently.

gateway.enable.accelerator

false

If set to true external accelerator support is allowed.

gateway.enable.customurl

false

If set to true the administrator is allowed to specify a custom URL for the Gateway to rewrite pages to.

gateway.httpurl

 

Enter the HTTP reverseproxy URL to set a custom URL for the Gateway to rewrite pages to.

gateway.httpsurl

 

Enter the HTTPS reverseproxy URL to set a custom URL for the Gateway to rewrite pages to.

gateway.favicon

 

This specifies the URL to which the Gateway will redirect requests for the favicon.ico file.

This is used for the "favorite icon" in Internet Explore and Netscape 7.0 and higher's preferences or favorites.

If left empty, the Gateway will send a 404 not found message back to browser.

gateway.logging.password

 

This field contains the LDAP password of the user "amService-srapGateway" that gateway uses for creating its application session.

This can be either encrypted or in plain text.

http.proxyHost

 

This proxy host is used to contact the Portal Server.

http.proxyPort

 

This is the port for the host used to contact Portal Server.

http.proxySet

 

This property is set to true if a proxy host is required. If the property is set to false,http.proxyHost and http.proxyPort are ignored.

Starting and Stopping the Gateway

By default, the Gateway starts as user noaccess.

    To Start the Gateway
  1. After installing the Gateway and creating the required profile, run the following command to start the Gateway:

    2. gateway-install-root/SUNWps/bin/gateway -n default start

    default is the default gateway profile that is created during installation. You can create your own profiles later, and restart the Gateway with the new profile. See "Creating a Gateway Profile".

    If you have multiple Gateway instances, use:

    gateway-install-root/SUNWps/bin/gateway start

This command starts all the Gateway instances configured on that particular machine.

Note

Restarting the server (the machine on which you have configured instances of the Gateway) restarts all configured instances of the Gateway.

Ensure that there are no old or backed up profiles in the /etc/opt/SUNWps directory.

  1. Run the following command to check if the Gateway is running on the specified port:

    2. netstat -a | grep port-number

    The default Gateway port is 443.

    To Stop the Gateway

Use the following command to stop the Gateway:

gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name stop

If you have multiple Gateway instances, use:

gateway-install-root/SUNWps/bin/gateway stop

This command stops all the Gateway instances that are running on that particular machine.

Restarting the Gateway

Normally, you do not need to restart the Gateway. You need to restart only if any of the following events have occured:

    To Restart the Gateway with a Different Profile

Restart the Gateway:

gateway-install-root/SUNWps/bin/gateway -n new-gateway-profile-name start

    To Restart the Gateway

In a terminal window, connect as root and do one of the following:

    To Configure the Gateway Watchdog

You can configure the time interval at which the watchdog monitors the status of the Gateway. This time interval is set to 60 seconds by default. To change this, edit the following line in the crontab:

0-59 * * * * gateway-install-root/SUNWps/bin/rwproxd/bin/checkgw /var/opt/SUNWps/.gw. 5 > /dev/null 2>&1

See the man pages for crontab to configure the crontab entries.

Specifying a Proxy to Contact the Identity Server

You can specify a hostproxy to be used by the Gateway to contact SRA support (RemoteConfigServlet) that is deployed over the Portal Server. This proxy is used by the Gateway to reach the Portal Server and Identity Server.

    To Specify a Proxy
  1. From the command-line, edit the following file:

    2. /etc/opt/bin/platform.conf.gateway-profile-name

  2. Add the following entries:

    3. http.proxyHost=proxy-host

    http.proxyPort=proxy-port

    http.proxySet=true

  3. Restart the Gateway to use the specified proxy for requests made to the server:

    4. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

Running the Gateway in the chroot Environment

To provide high security in a chroot environment, the chroot directory content must be as minimal as possible. For example, if any programs exist which allow a user to modify a file under the chrooted directory, then chroot will not protect the server against an attacker modifying files under the chroot tree. CGI programs should not be written in an interpreted language, such as bourne shell, c-shell, korn shell or perl, but should be compiled binaries so interpreters do not need to be present under the chroot directory tree.

Note

The watchdog feature is not supported in the chroot environment.

    To Install chroot
  1. As root, in a terminal window, copy the following files to an external source such as a computer on the network, a backup tape or a floppy disk.

    2. cp /etc/vfstab external-device

    cp /etc/nsswitch.conf external-device

    cp /etc/hosts external-device

  2. Run the mkchroot script from:

    3. portal-server-install-root/SUNWps/bin/chroot

    Note

    The mkchroot script cannot be terminated by pressing Ctrl-C after execution has begun.

    In the event of an error during the execution of the mkchroot script, see "Execution Failure of the mkchroot Script".

You are prompted for a different root directory (new_root_directory). The script creates the new directory.

In the following examples, /safedir/chroot is the new_root_directory.

mkchroot version 6.0

Enter the full path name of the directory which will be the chrooted tree:/safedir/chroot

Using /safedir/chroot as root.

Checking available disk space...done

/safedir/chroot is on a setuid mounted partition.

Creating filesystem structure...dev etc sbin usr var proc opt bin lib tmp etc/lib usr/platform usr/bin usr/sbin usr/lib usr/openwin/lib var/opt var/tmp dev/fd done

Creating devices...null tcp ticots ticlts ticotsord tty udp zero conslog done

Copying/creating etc files...group passwd shadow hosts resolv.conf netconfig nsswitch.conf

done

Copying binaries...................................done

Copying libraries.....................................done

Copying zoneinfo (about 1 MB)..done

Copying locale info (about 5 MB)..........done

Adding comments to /etc/nsswitch.conf ...done

Creating loopback mount for/safedir/chroot/usr/java1.2...done

Creating loopback mount for/safedir/chroot/proc...done

Creating loopback mount for/safedir/chroot/dev/random...done

Do you need /dev/fd (if you do not know what it means, press return)[n]:

Updating /etc/vfstab...done

Creating a /safedir/chroot/etc/mnttab file, based on these loopback mounts.

Copying SRAP related data ...

Using /safedir/chroot as root.

Creating filesystem structure...........done

mkchroot successfully done.

  1. Manually mount the Java directory mentioned in the platform.conf file to the chroot directory using the following command:

    2. mkdir -p /safedir/chroot/java-dir

    mount -F lofs java-dir /safedir/chroot/java-dir

    For Solaris 9, do the following:

    mkdir -p /safedir/chroot/usr/lib/32

    mount -F lofs /usr/lib/32 /safedir/chroot/usr/lib/32

    mkdir -p /safedir/chroot/usr/lib/64

    mount -F lofs /usr/lib/64 /safedir/chroot/usr/lib/64

    To mount this directory at system startup, add a corresponding entry in the /etc/vfstab file:

    java-dir - /safedir/chroot/java-dir lofs - no -

    For Solaris 9:

    /usr/lib/32 - /safedir/chroot/usr/lib/32 lofs - no -

    /usr/lib/64 - /safedir/chroot/usr/lib/64 lofs - no -

  2. Type the command below to restart the Gateway:

    3. chroot /safedir/chroot ./gateway-install-root/SUNWps/bin/gateway start

    stopping gateway ... done.

    starting gateway ...

    done.

Execution Failure of the mkchroot Script

In the event of an error during the execution of the mkchroot script, the script will restore the files to their initial state.

In the following examples, /safedir/chroot is the chroot directory.

If the following error message is encountered:

Not a Clean Exit

  1. Copy the backed up files in step 1 of the procedure To Install chroot, to their original locations, and execute the following commands:

    2. umount /safedir/chroot/usr/java1.2

    umount /safedir/chroot/proc

    umount /safedir/chroot/dev/random

  2. Remove the /safedir/chroot directory.

Restarting the Gateway in the chroot Environment

Follow these steps to start the Gateway in a chroot environment whenever the Gateway machine is rebooted.

    To Restart the Gateway in the chroot Environment
  1. Stop the Gateway running from the ’/’ directory.

    2. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name stop

  2. Start the Gateway to run from the chroot directory:

    3. chroot /safedir/chroot ./portal-server-install-root/SUNWps/bin/gateway -n gateway-profile-name start

    Note

    The /safedir/chroot/etc files (such as passwd and hosts) need to be administered, just like the /etc files, but only include host and account information required by the programs running in the chroot tree.

    For example, if you change the identity provider address of the system, also change the file /safedir/chroot/etc/hosts.

Creating Multiple Instances of a Gateway

Use the gwmultiinstance script to create a new instance of the Gateway. It’s preferable to run this script after the Gateway profile has been created.

  1. Log in as root and navigate to the following directory:

    2. gateway-install-root/SUNWps/bin/

  2. Run the multi-instance script:

    3. ./gwmultiinstance

  3. Choose one of the following installation options:

    4. 1) Create a new gateway instance

    2) Remove a gateway instance

    3) Remove all gateway instances

    4) Exit

    If you chose 1, answer the following questions:

    What is the name of the new gateway instance?

    What protocol will the new gateway instance use? [https]

    What port will the new gateway instance listen on?

    What is the fully qualified hostname of the portal server?

    What port should be used to access the portal server?

    What protocol should be used to access the portal server? [http]

    What is the portal server deploy URI?

    What is the organization DN? [dc=iportal,dc=com]

    What is the identity server URI? [/amserver]

    What is the identity server password encryption key?

    Please provide the following information needed for creating a self-signed certificate:

    What is the name of your organization?

    What is the name of your division?

    What is the name of your city or locality?

    What is the name of your state or province?

    What is the two-letter country code?

    What is the password for the Certificate Database? Again?

    What is the password for the logging user? Again?

    Have you created the new gateway profile in the admin console? [y]/n

    Start the gateway after installation? [y]/n

  4. Start the new instance of the Gateway with the new gateway profile name.

    5. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

    where gateway-profile-name is the new Gateway instance.

Using Web Proxies

You can configure the Gateway to contact HTTP resources using third party web proxies. Web proxies reside between the client and the Internet.

Web Proxy Configuration

Different proxies may be used for different domains and subdomains. These entries tell the Gateway which proxy to use to contact specific subdomains in specific domains. The proxy configuration specified in the Gateway works as follows:

To configure the Use Proxy option, see "Enable Usage of Web Proxies".

Figure 2-1 shows how the web proxy information is resolved based on the proxy configuration in the Gateway service.

Figure 2-1  Web Proxy Management

Proxy Management Figure - See explanation in text

In Figure 2-1, if Use Proxy is enabled, and the requested URL is listed in the Do Not Use Webproxy URLs list, the Gateway connects to the destination host directly.

If Use Proxy is enabled, and the requested URL is not listed in the Do Not Use Webproxy URLs list, the Gateway connects to the destination host through the specified proxy. The proxy, if specified, is looked up from the Proxies for Domains and Subdomains list.

If Use Proxy is disabled, and the requested URL is listed in the Use Webproxy URLs list, the Gateway connects to the destination host using the proxy information in the Proxies for Domains and Subdomains list.

If Use Proxy is disabled, and the requested URL is not listed in the Use Webproxy URLs list, the Gateway connects to the destination host directly.

If none of the above conditions are met, and a direct connection is not possible, the Gateway displays an error saying that connection is not possible.

Note

If you are accessing the URL through the Bookmark channel of the portal desktop, and none of the above conditions are met, the Gateway sends a redirect to the browser. The browser accesses the URL using its own proxy settings.

Syntax

domainname [web_proxy1:port1]|subdomain1 [web_proxy2:port2]|......

Example

sesta.com wp1:8080|red wp2:8080|yellow|* wp3:8080

* is a wild card that matches everything

where,

sesta.com is the domain name and wp1 is the proxy to contact on port 8080.

red is a subdomain and wp2 is the proxy to contact on port 8080.

yellow is a subdomain. Since no proxy is specified, the proxy specified for the domain is used, that is, wp1 on port 8080.

* indicates that for all other subdomains wp3 needs to be used on port 8080.

Note

Port 8080 is used by default if you do not specify a port.

Processing the Web Proxy Information

When a client tries to access a particular URL, the host name in the URL is matched with the entries in the Proxies for Domains and Subdomains list. The entry that matches the longest suffix of the requested host name is considered. For example, consider that the requested host name is host1.sesta.com

Consider the following entries in the Proxies for Domains and Subdomains list:

com p1| host1 p2 | host2 | * p3

sesta.com p4 | host5 p5 | * p6

florizon.com | host6

abc.sesta.com p8 | host7 p7 | host8 p8 | * p9

host6.florizon.com p10

host9.sesta.com p11

siroe.com | host12 p12 | host13 p13 | host14 | * p14

siroe.com | host15 p15 | host16 | * p16

* p17

The Gateway internally maps these entries into a table as shown in Table 2-2.

Table 2-2  Mapping of Entries in the Proxies for Domains and Subdomains List

Number

Entry in Proxies for Domains and Subdomains List

Proxy

Description

1

com

p1

As specified in the list.

2

host1.com

p2

As specified in the list.

3

host2.com

p1

Since there is no proxy specified against host2, the proxy for the domain is used.

4

*.com

p3

As specified in the list.

5

sesta.com

p4

As specified in the list.

6

host5.sesta.com

p5

As specified in the list.

7

*.sesta.com

p6

As specified in the list.

8

florizon.com

Direct

See the description for entry 14 for details.

9

host6.florizon.com

–

See the description for entry 14 for details.

10

abc.sesta.com

p8

As specified in the list.

11

host7.abc.sesta.com

p7

As specified in the list.

12

host8.abc.sesta.com

p8

As specified in the list.

13

*.abc.sesta.com

p9

As specified in the list. For all hosts other than host7 and host8 under the abc.sesta.com domain, p9 is used as the proxy.

14

host6.florizon.com

p10

This entry is the same as entry 9. Entry 9 indicates a direct connection, whereas this entry indicates that proxy p10 should be used. In a case where there are two entries such as this, the entry with the proxy information is considered as the valid entry. The other entry is ignored.

15

host9.sesta.com

p11

As specified in the list.

16

siroe.com

Direct

Since there is no proxy specified against siroe.com, a direct connection is attempted.

17

host12.siroe.com

p12

As specified in the list.

18

host13.siroe.com

p13

As specified in the list.

19

host14.siroe.com

Direct

Since no proxy is specified for host14, or for siroe.com, a direct connection is attempted.

20

*.siroe.com

p14

See the description for entry 23.

21

host15.siroe.com

p15

As specified in the list.

22

host16.siroe.com

Direct

Since no proxy is specified for host16, of for siroe.com, a direct connection is attempted.

23

*.siroe.com

p16

This is similar to entry 20. But the proxies specified are different. In such a case, the exact behavior of the Gateway is not known. Either of the two proxies may be used.

24

*

p17

If no other entry matches the requested URL, p17 is used as the proxy.

Note

Instead of separating the proxy entries in the Proxies for Domains and Subdomains list with the | symbol, it may be simpler to have individual entries in the list. For example, instead of an entry such as:

sesta.com p1 | red p2 | * p3

you can specify it as:

sesta.com p1

red.sesta.com p2

*.sesta.com p3

This makes it easier to trap repeated entries or any other ambiguities.

Rewriting Based on the Proxies for Domains and Subdomains List

The entries in the Proxies for Domains and Subdomains list are also used by Rewriter. Rewriter rewrites all URLs whose domains match the domains listed in the Proxies for Domains and Subdomains list.

Caution

The * entry in the Proxies for Domains and Subdomains list is not considered for rewriting. For example, in the sample provided in Table 2-2, entry 24 is not considered.

See Chapter 3, "The Rewriter" for information on Rewriter.

Default Domain and Subdomain

When the destination host in the URL is not a fully qualified host name, the default domain and subdomain are used to arrive at the fully qualified name.

Assume that the entry in the Default Domain Subdomain field of the administration console is:

red.sesta.com

Note

You need to have the corresponding entry in the Proxies for Domains and Subdomains list.

In the example above, sesta.com is the default domain and the default subdomain is red.

If the requested URL is host1, this is resolved to host1.red.sesta.com using the default domain and subdomain. The Proxies for Domains and Subdomains list is then looked up for host1.red.sesta.com.

Using Proxy Auto Configuration

To ignore the information in the Proxies for Domains and Subdomains list, enable the Proxy Auto Configuration (PAC) feature. To configure PAC, see "Enable Proxy Auto Config (PAC) Support".

Please note the following when using a PAC file:

Sample PAC File Usage

The following examples show the URLs listed in the Proxies for Domains and Subdomains list and the corresponding PAC file.

Example with Either DIRECT or NULL Return

Using these proxies for domains and subdomains:

intranet1.com

intranet2.com.proxy.intranet1.com:8080

the corresponding PAC file is:

// Start of the PAC File

function FindProxyForURL(url, host) {

if (dnsDomainIs(host, ".intranet1.com")) {

return "DIRECT";

}

if (dnsDomainIs(host, ".intranet2.com")) {

return "PROXY proxy.intranet1.com:8080";

}

return "NULL";

}

//End of the PAC File

Example with STARPROXY Return

Using these proxies for domains and subdomains:

the corresponding PAC file is:

// Start of the PAC File

function FindProxyForURL(url, host) {

if (dnsDomainIs(host, ".intranet1.com")) {

return "DIRECT";

}

if (dnsDomainIs(host, ".intranet2.com")) {

return "PROXY proxy.intranet1.com:8080;" +

"PROXY proxy1.intranet1.com:8080";

}

return "STARPROXY internetproxy.intranet1.com:80";

}

//End of the PAC File

In this case, if the request is for a host in .intranet2.com domain, the Gateway will contact proxy.intranet1.com:8080. If proxy.intranet1.com:8080 is down, the request will fail. the Gateway will not failover and contact proxy1.intranet1.com:8080.

Using a Netlet Proxy

Netlet packets are decrypted at the Gateway and sent to the destination servers. However, the Gateway needs to access all Netlet target hosts through the firewall between the demilitarized zone (DMZ) and the intranet. This requires opening a large number of ports in the firewall. The Netlet Proxy can be used to minimize the number of open ports in the proxy.

The Netlet Proxy enhances the security between the Gateway and the intranet by extending the secure tunnel from the client, through the Gateway to the Netlet Proxy that resides in the intranet. With the proxy, the Netlet packets are decrypted by the proxy and then sent to the destination.

The Netlet Proxy is useful for the following reasons:

You can:

Figure 2-2 shows three sample implementations of the Gateway and the Portal Server with and without a Netlet Proxy installed. The components include a client, two firewalls, the Gateway that resides between the two firewalls, Portal Server, and Netlet target servers.

The first scenario shows the Gateway and Portal Server without a Netlet Proxy installed. Here the data encryption extends only from the client to the Gateway. A port is opened in the second firewall for each Netlet connection request.

The second scenario shows the Gateway and the Portal Server with a Netlet Proxy installed on Portal Server. In this case, the data encryption extends from the client all the way to the Portal Server. Since all Netlet connections are routed through a Netlet Proxy, only one port needs to be opened in the second firewall for Netlet requests.

The third scenario shows the Gateway and the Portal Server with a Netlet Proxy installed on a separate node. Installing a Netlet Proxy on a separate node reduces the load on the Portal Server node. Here again, only two ports need to be opened in the second firewall. One port services requests to the Portal Server, and the other port routes Netlet requests to the Netlet Proxy server.

Figure 2-2  Implementation of Netlet Proxy

This figure illustrates possible configurations involving the Netlet Proxy, and depicts the advantage of having a Netlet Proxy. See the description preceeding the figure for details.

Creating Instances of a Netlet Proxy

Use the nlpmultiinstance script to create a new instance of a Netlet Proxy on the Portal Server node or a separate node. It’s preferable to run this script after the Gateway profile has been created:

  1. Log in as root and navigate to the following directory:

    2. netlet-install-dir/SUNWps/bin

  2. Run the multi-instance script:

    3. ./nlpmultiinstance

  3. Answer the questions asked by the nlpmultiinstance script:
    • What is the name of the new netlet proxy instance?
    • If you have a rewriter proxy instance configured on this node with the same name, you are asked if you want to use the same configuration for this netlet proxy instance.
    • If you answered yes, answer these two questions:
      • What port will the new netlet proxy instance listen on?
      • Start the netlet proxy after installation?
    • If you answered no, answer the following questions:
      • What protocol will the new netlet proxy instance use?
      • What port will the new netlet proxy instance listen on?
      • What is the name of your organization?
      • What is the name of your division?
      • What is the name of your city or locality?
      • What is the name of your state or province?
      • What is the two-letter country code?
      • What is the password for the certificate Database?
      • What is the password for the logging user?
      • Have you created the new netlet proxy profile in the admin console?
      • If you answered yes, start the netlet proxy after installation?
  4. Start the new instance of the netlet proxy with the required gateway profile name:

    5. netlet-proxy-install-root/SUNWps/bin/netletd -n gateway-profile-name start

    where gateway-profile-name is the profile name corresponding to the required Gateway instance.

Enabling a Netlet Proxy

You enable a Netlet Proxy through the Gateway service under SRA Configuration in the Identity Server administration console. See "Enable and Create a List of Netlet Proxies".

Restarting a Netlet Proxy

You can configure a Netlet Proxy to restart whenever the proxy is killed accidentally. You can schedule a watchdog process to monitor a Netlet Proxy and restart it if it goes down.

You can also restart a Netlet Proxy manually.

    To Restart a Netlet Proxy

In a terminal window, connect as root and do one of the following:

    To Configure a Netlet Proxy Watchdog

You can configure the time interval at which the watchdog monitors the status of a Netlet Proxy. This time interval is set to 60 seconds by default. To do this, edit the following line in the crontab:

0-59 * * * * netlet-install-dir/bin/checkgw /var/opt/SUNWps/.gw 5 > /dev/null 2>&1

Using a Rewriter Proxy

Rewriter Proxy is installed in the intranet. Instead of trying to retrieve the contents directly, the Gateway forwards all the requests to Rewriter Proxy which fetches and returns the contents to the Gateway.

There are two advantages to using Rewriter Proxy:

If you do not specify a Rewriter Proxy, the Gateway component makes a direct connection to intranet computers when a user tries to access one of those intranet computers.

To enable Rewriter Proxy, see "Enable and Create a List of Rewriter Proxies".

Creating Instances of a Rewriter Proxy

Use the rwpmultiinstance script to create a new instance of a Rewriter Proxy on the Portal Server node. It’s preferable to run this scrip after the Gateway profile has been created.

  1. Log in as root and navigate to the following directory:

    2. rewriter-proxy-install-root/SUNWps/bin

  2. Run the multi instance script:

    3. ./rwpmultiinstance

  3. Answer the questions asked by the script:
    • What is the name of the new rewriter proxy instance?
    • If you have a rewriter proxy instance configured on this node with the same name, you are asked if you want to use the same configuration for this rewriter proxy instance.
    • If you answered yes, answer these two questions:
      • What port will the new rewriter proxy instance listen on?
      • Start the rewriter proxy after installation?
    • If you answered no, answer the following questions:
      • What protocol will the new rewriter proxy instance use?
      • What port will the new rewriter proxy instance listen on?
      • What is the name of your organization?
      • What is the name of your division?
      • What is the name of your city or locality?
      • What is the name of your state or province?
      • What is the two-letter country code?
      • What is the password for the certificate Database?
      • What is the password for the logging user?
      • Have you created the new rewriter proxy profile in the admin console?
      • If you answered yes, start the rewriter proxy after installation?
  4. Start the new instance of the rewriter proxy with the required gateway profile name:

    5. rewriter-proxy-install-root/SUNWps/bin/rwproxyd -n gateway-profile-name start

    where gateway-profile-name is the profile name corresponding to the required Gateway instance.

Enabling a Rewriter Proxy

Enable a Rewriter Proxy through the Gateway service under SRA Configuration in the Identity Server administration console. See "Enable and Create a List of Rewriter Proxies".

Restarting a Rewriter Proxy

You can configure Rewriter Proxy to restart whenever the proxy is killed accidentally. You can schedule a watchdog process to monitor Rewriter Proxy and restart it if it goes down.

You can also restart Rewriter Proxy manually.

    To Restart a Rewriter Proxy

In a terminal window, connect as root and do one of the following:

    To Configure a Rewriter Proxy Watchdog

You can configure the time interval at which the watchdog monitors the status of Rewriter Proxy. This time interval is set to 60 seconds by default. To do this, edit the following line in the crontab:

0-59 * * * * rewriter-proxy-install-root/bin/checkgw /var/opt/SUNWps/.gw 5 > /dev/null 2>&1

Using a Reverse Proxy with the Gateway

A proxy server serves Internet content to the intranet, while a reverse proxy serves intranet content to the Internet. Certain deployments of reverse proxy are configured to serve the Internet content, to achieve load balancing and caching.

If the deployment has a third-party reverse proxy in front of the Gateway, the response has to be rewritten with the reverse proxy's URL instead of the Gateway's URL. For this, the following configurations are needed.

    To Enable a Reverse Proxy :
  1. Log in as root and edit the platform.conf file of the required Gateway instance:

    2. /etc/opt/SUNWps/platform.conf.gateway-profile-name

  2. Add the following entries:

    3. gateway.virtualhost=fully-qualified-gateway-host gateway-ip-address fully- qualified-reverse-proxyhost

    gateway.enable.customurl=true (This value is set to false by default.)

    gateway.httpurl=http reverse-proxy-URL

    gateway.httpsurl=https reverse-proxy-URL

    gateway.httpurl will be used to rewrite the response for the request received at the port which is listed as HTTP port in the gateway profile.

    gateway.httpsurl will be used to rewrite the response for the request received at the port which is listed as HTTPS port in the gateway profile.

  3. Restart the Gateway:

    4. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

If these values are not specified, then gateway will default to normal behaviour.

Obtaining Client Information

When the Gateway forwards a client request to any internal server, it adds HTTP headers to the HTTP request. You can use these headers to obtain additional client information and detect the presence of the Gateway.

To view the HTTP request headers, set the entry in the platform.conf file to gateway.error=message, then use the request.getHeader() from the servlet API.

The first column lists the header label, the second column specifies the syntax for that header and the third column is the description of the header label.

Table 2-3  Information in HTTP Headers

Header

Syntax

Description

PS-GW-PDC

PS-GW-PDC: true/false

Indicates whether PDC is enabled at the Gateway.

PS-Netlet

PS-Netlet:enabled=true/false

Indicates whether the Netlet has been enabled or disabled at the Gateway.

If it is enabled, then the encryption option is populated, indicating whether the Gateway is running in HTTPS (encryption=ssl) or in HTTP mode (encryption=plain)

For example:

PS-Netlet: enabled=false

Netlet is disabled.

PS-Netlet: enabled=true; encryption=ssl

Netlet is enabled with the Gateway running in SSL mode.

The encryption=ssl/plain is not populated when the Netlet is not enabled.

PS-GW-URL

PS-GW-URL: http(s)://gatewayURL(:port)

Indicates the URL that the client is connected to.

If it is non-standard port (that is the Gateway is in HTTP/HTTPS mode with port not being 80/443), then the ":port" is also populated.

PS-GW-Rewriting-URL

PS-GW-URL: http(s)://gatewayURL(:port)/[SessionInfo]

 

Indicates the URL that the Gateway rewrites all the pages to.

1.  When the browser supports cookies, the value of this header would is the same as the PS-GW-URL header.

2.  When the browser does not support cookies:

  • and if the destination host is in the "Forward Cookie URLs" list, the value is the actual URL to which the Gateway rewrites the page to (which includes the encoded SessionID info).
  • or if the destination host is not in the Forward Cookie URLs list, then the SessionInfo string will be "$SessionID"

Note: As part of response, if the user's Identity Server sessionId changes (like response from authentication page) then the pages are rewritten with that value (and not the value that was previously indicated in the header).

For example:

  • If the browser supports cookies:

PS-GW-Rewriting-URL: https://siroe.india.sun.com:10443/

  • If the browser does not support cookies, but the endserver is in "Forward Cookie URLs" list.

PS-GW-Rewriting-URL: https://siroe.india.sun.com:10443/SessIDValCustomEncodedValue/

  • If the browser does not support cookies and endserver is not in "Forward Cookie URLs" list.

PS-GW-Rewriting-URL: https://siroe.india.sun.com:10443/$SessionID

PS-GW-CLientIP

 

PS-GW-CLientIP: IP

This is the IP that the Gateway obtained from recievedSocket.getInetAddress().getHostAddress()

This gives the client's IP if directly connected to the Gateway.

Note: Due to a JSS/NSS bug, this is currently not present.

Using Authentication Chaining

Authentication chaining provides a higher level of security over the regular mechanism of authentication. You can enable users to be authenticated against more than one authentication mechanism.

The procedure described here is only for enabling authentication chaining along with PDC authentication at the Gateway. For authentication chaining without PDC authentication at the Gateway please refer to Sun ONE Identity Server Administration Guide.

For example, if you chain the PDC, Unix, and Radius authentication modules, the user will have to authenticate against all the three modules to access the portal desktop.

Note

PDC is always the first authentication module to be presented to the user if it is enabled.

    To Add Authentication Modules to an Existing PDC Instance
  1. Log in to the Identity Server administration console as administrator.
  2. Choose the required organization.
  3. Select Services from the View drop-down menu.

    4. The services are displayed in the left pane.

  4. Click the arrow next to Authentication Configuration.

    5. The Service Instance List displays.

  5. Click gatewaypdc.

    6. The Gatewaypdc properties page displays.

  6. Click Edit in front of Authentication Configuration.

    7. Add Module displays.

  7. Select Module Name and set Flag to Required. Option can be blank.
  8. Click OK.
  9. Click Save after adding one or more modules.
  10. Click Save in the gatewaypdc properties page.
  11. For the changes to take effect, restart the Gateway:

    12. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

Using Wild Card Certificates

A wild card certificate accepts a single certificate with a wild card character in the fully-qualified DNS name of the host.

This allows the certificate to secure multiple hosts within the same domain. For example, a certificate for *.domain.com can be used for abc.domain.com, and abc1.domain.com. In fact, this certificate is valid for any host in the domain.com domain.

You need to specify a * in the fully-qualified host name. For example, if the fully-qualified host name is abc.florizon.com, specify it as *.florizon.com. The certificate that is generated is now valid for all host names in the florizon.com domain.

Disabling Browser Caching

As the Gateway component provides secure access to backend corporate data from any location using just a web browser, it may be necessary that the information not be cached locally by the client.

You can disable caching of pages redirected through the Gateway by modifying the attribute in the platform.conf file of the specific Gateway.

Disabling this option can have an impact on the Gateway performance. Every time the portal desktop is refreshed, the Gateway has to retrieve everything referenced by the page, such as images which may have been previously cached by the browser. However, by enabling this feature, remotely accessing secure content will not leave a cached footprint on the client site. This could outweigh performance implications if the corporate network is being accessed from an Internet cafe or similar remote location that is not under corporate IT control.

    To Disable Browser Caching
  1. Log in as root and edit the platform.conf file of the required Gateway instance:

    2. /etc/opt/SUNWps/platform.conf.gateway-profile-name

  2. Edit the following line:

    3. gateway.allow.client.caching=true

    This value is set to true by default. Change the value to false to disable browser caching at the client side.

  3. Restart the Gateway:

    4. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

Customizing the Gateway Service User Interface

This section discusses the various property files that can be edited. You can edit labels for the Gateway service on the administration console, error messages, or the order of log information. This is useful if you are trying to customize the product for different locales.

You can customize the following files:

portal-server-install-root/SUNWam/locale/srapGatewayAdminConsole.properties

portal-server-installl-dir/SUNWps/locale/srapGateway.properties

portal-server-install-root/SUNWps/web-src/WEB-INF/classes/srapgwadminmsg.properties

Note

You need to store a copy of each of these files in the respective locale directories if you have different locale settings.

srapGatewayAdminConsole.properties File

Edit this file to change the field names that appear for the Gateway service on the administration console.

srapGateway.properties File

Edit this file to:

srapgwadminmsg.properties File

Edit this file to:

Using Federation Management

Federation Management allows users to aggregate their local identities so that they have one network identity. Federation Management uses the network identity to allow users to login at one service provider’s site and access other service provider’s sites without having to re-authenticate their identity. This is referred to as single sign-on.

Federation management can be configured in open mode and secure mode on the Portal Server. The Sun ONE Portal Server Administrator’s Guide describes how to configure federation management in open mode. Before configuring Federation management in secure mode, using Secure Remote Access, ensure that it works in open mode. If you want your users to use Federation Management from the same browser in both open and secure mode, they must clear the cookies and cache from the browser.

Refer to the Sun ONE Identity Server Customization and API Guide for detailed information on Federation Management.

Federation Management Scenario

A user authenticates to an initial service provider. Service providers are commercial or not-for-profit organizations that offer web-based services. This broad category can include internet portals, retailers, transportation providers, financial institutions, entertainment companies, libraries, universities, and governmental agencies.

The service provider uses a cookie to store the user’s session information in the client browser. The cookie also includes the user’s identity provider.

Identity providers are service providers that specialize in providing authentication services. As the administrating service for authentication, they also maintain and manage identity information. Authentication accomplished by an identity provider is honored by all service providers with whom it is affiliated.

When the user attempts to access a service that is not affiliated with the identity provider, the identity provider forwards the cookie to the unaffiliated service provider. This service provider can then access the identity provider called out in the cookie.

However, cookies cannot be read across different DNS domains. Therefore a Common Domain Cookie Service is used to redirect the service provider to the correct identity provider thus enabling single sign-on for the user.

Configuring Federation Management Resources

The Federation resources, the service providers, identity providers, and the Common Domain Cookie Service (CDCS), are configured in the Gateway profile based on where they reside. This section describes how to configure three scenarios:

  1. when all resources are inside the corporate intranet
  2. when all resources are not inside the corporate intranet or the identity provider resides in the Internet
  3. when all resources are not inside the corporate intranet or the service provider is a third party residing in the Internet while the identity provider is protected by the Gateway.

Configuration 1

In this configuration the service providers, identity providers and the Common Domain Cookie Service are deployed in the same corporate intranet and the identity providers are not published in the Internet Domain Name Server (DNS). The CDCS is optional.

In this configuration the Gateway points to the service provider, which is the Portal Server. This configuration is valid for multiple instances of the Portal Server.

  1. Log in to the Identity Server administration console as administrator.
  2. Select the Service Configuration tab from the administration console.
  3. Click the arrow next to Gateway under SRA Configuration.

    4. The Gateway page displays.

  4. Click Edit... next to the Gateway profile for which you want to set the attribute.

    5. The Edit Gateway Profile page displays.

  5. Click the Core tab.
  6. Select the Enable Cookie Management checkbox to enable cookie management.
  7. Scroll to the Portal Server List field and enter Portal Server names so that you can use relative URLs like /amserver or /portal/dt listed in the Non-authenticated URLs list. For example:

    8. http://idp-host:port/amserver/js

    http://idp-host:port/amserver/UI/Login

    http://idp-host:port/amserver/css

    http://idp-host:port/amserver/SingleSignOnService

    http://idp-host:port/amserver/UI/blank

    http://idp-host:port/amserver/postLogin

    http://idp-host:port/amserver/login_images

  8. Scroll to the Portal Server List field and enter the Portal Server name. For example /amserver.
  9. Click Save.
  10. Click the Security tab.
  11. Scroll to the Non-authenticated URLs list and add the Federation resources. For example:

    12. /amserver/config/federation

    /amserver/IntersiteTransferService

    /amserver/AssertionConsumerservice

    /amserver/fed_images

    /amserver/preLogin

    /portal/dt

  12. Click Add.
  13. Click Save.
  14. If web proxies are needed to reach the URLs listed in the Non-authenticated URLs list, click the Proxies tab.
  15. Scroll to the Proxies for Domains and Subdomains field and enter the necessary web proxies.
  16. Click Add.
  17. Click Save.
  18. From a terminal window, restart the Gateway:

    19. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

Configuration 2

In this configuration the identity providers, identity providers and the Common Domain Cookie Provider (CDCP) are not deployed in the corporate intranet or the identity provider is a third party provider residing the in Internet.

In this configuration the Gateway points to the service provider, which is the Portal Server. This configuration is valid for multiple instances of the Portal Server.

  1. Log in to the Identity Server administration console as administrator.
  2. Select the Service Configuration tab from the administration console.
  3. Click the arrow next to Gateway under SRA Configuration.

    4. The Gateway page displays.

  4. Click Edit... next to the Gateway profile for which you want to set the attribute.

    5. The Edit Gateway Profile page displays.

  5. Click the Core tab.
  6. Select the Enable Cookie Management checkbox to enable cookie management.
  7. Scroll to the Portal Server List field and enter service provider portal server names so that you can use relative URLs like /amserver or /portal/dt listed in the Non-authenticated URLs list.

    8. http://idp-host:port/amserver/js

    http://idp-host:port/amserver/UI/Login

    http://idp-host:port/amserver/css

    http://idp-host:port/amserver/SingleSignOnService

    http://idp-host:port/amserver/UI/blank

    http://idp-host:port/amserver/postLogin

    http://idp-host:port/amserver/login_images

  8. Click Save.
  9. Click the Security tab.
  10. Scroll to the Non-authenticated URLs list and add the Federation resources. For example:

    11. /amserver/config/federation

    /amserver/IntersiteTransferService

    /amserver/AssertionConsumerservice

    /amserver/fed_images

    /amserver/preLogin

    /portal/dt

  11. Click Add.
  12. Click Save.
  13. If web proxies are needed to reach the URLs listed in the Non-authenticated URLs list, click the Proxies tab.
  14. Scroll to the Proxies for Domains and Subdomains field and enter the necessary web proxies.
  15. Click Add.
  16. Click Save.
  17. From a terminal window, restart the Gateway:

    18. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start

Configuration 3

In this configuration the identity providers, identity providers and the Common Domain Cookie Provider (CDCP) are not deployed in the corporate intranet or the service provider is a third party provider residing the in Internet and the identity provider is protected by the Gateway.

In this configuration the Gateway points to the identity provider, which is the Portal Server.

This configuration is valid for multiple instances of the Portal Server. This configuration is very unlikely on the Internet, however, some corporate networks may have such a configuration within their intranet, that is the identity provider may reside in a subnet this is protected by a firewall and the service providers are directly accessible from within the corporate network.

  1. Log in to the Identity Server administration console as administrator.
  2. Select the Service Configuration tab from the administration console.
  3. Click the arrow next to Gateway under SRA Configuration.

    4. The Gateway page displays.

  4. Click Edit... next to the Gateway profile for which you want to set the attribute.

    5. The Edit Gateway Profile page displays.

  5. Click the Core tab.
  6. Select the Enable Cookie Management checkbox to enable cookie management.
  7. Scroll to the Portal Server List field and enter identity provider portal server so that you can use relative URLs like /amserver or /portal/dt listed in the Non-authenticated URLs list.

    8. http://idp-host:port/amserver/js

    http://idp-host:port/amserver/UI/Login

    http://idp-host:port/amserver/css

    http://idp-host:port/amserver/SingleSignOnService

    http://idp-host:port/amserver/UI/blank

    http://idp-host:port/amserver/postLogin

    http://idp-host:port/amserver/login_images

  8. Click Save.
  9. Click the Security tab.
  10. Scroll to the Non-authenticated URLs list and add the Federation resources. For example:

    11. /amserver/config/federation

    /amserver/IntersiteTransferService

    /amserver/AssertionConsumerservice

    /amserver/fed_images

    /amserver/preLogin

    /portal/dt

  11. Click Add.
  12. Click Save.
  13. If web proxies are needed to reach the URLs listed in the Non-authenticated URLs list, click the Proxies tab.
  14. Scroll to the Proxies for Domains and Subdomains field and enter the necessary web proxies.
  15. Click Add.
  16. Click Save.
  17. From a terminal window, restart the Gateway:

    18. gateway-install-root/SUNWps/bin/gateway -n gateway-profile-name start



Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.