4.2 Access Gateway Server Advance Configuration

This section describes the configuration settings that affect the Access Gateway as a server, such as changing its name or setting the time.

For logging and audit options, see the following:

4.2.1 Configuration Overview

The Configuration page allows you to view the configuration status and to configure the features of the cluster or the Access Gateway. After an Access Gateway has been made a member of a cluster, you can only configure it from the cluster configuration. Some options are specific to an Access Gateway. For these options, you must select the Access Gateway and then configure the options.

  1. In the Administration Console, Devices > Access Gateways > Edit.

    To edit an Access Gateway that is not a member of a cluster, click the Edit button on the Access Gateway row.

    To edit an Access Gateway cluster, click the Edit button on the Access Gateway cluster row.

  2. Select one of the following options:

    Reverse Proxy / Authentication: Allows you to configure a reverse proxy so that it hides the IP address of a Web server and accelerates access by caching the most frequently used pages. This option displays the list of configured proxies and allows you to add new proxies and modify existing proxies. To add a new reverse proxy or manage the existing proxies, click Reverse Proxy / Authentication (see Managing Reverse Proxies and Authentication). To manage a specific reverse proxy, click its name (see Creating a Proxy Service).

    Tunneling: Allows you to tunnel non-HTTP traffic through the Access Gateway to a Web server. For more information, see Setting Up a Tunnel.

    Date & Time: Allows you to configure the server’s time source. For more information, see Setting the Date and Time.

    Alerts: Allows you to select the alerts and then configure whether they are sent to a server, a log file, or to selected individuals via e-mail. For more information, see Managing Access Gateway Alert Profiles.

    Auditing: Allows you to select the events to send to a NetIQ Sentinel or Audit server. For more information, see Enabling Access Gateway Audit Events.

    Adapter List: Displays the list of configured network cards and allows you to edit an existing configuration or to add a new one. For more information, see Viewing and Modifying Adapter Settings. To manage a specific adapter, click the name of the adapter.

    Gateways: Displays the list of configured gateways and allows you to edit an existing configuration or to add a new one. For more information, see Viewing and Modifying Gateway Settings.

    DNS: Displays the current DNS configuration that the Access Gateway is using to resolve names and allows you to modify it. For more information, see Viewing and Modifying DNS Settings.

    Hosts: Allows you to create a static mapping between the host IP addresses and host names. For more information, see Configuring Hosts.

    Purge List: Allows you to prevent Web objects from being cached. For more information, see Configuring a Purge List.

    Pin List: Allows you to prepopulate the cache with the Web objects that you want cached, before a user has requested the object. For more information, see Configuring a Pin List.

    Cache Options: Allows you to globally disable caching or configure which objects are cached and how frequently they are refreshed. For more information, see Configuring Caching Options.

    Advanced Options: Allows you to configure how all reverse proxies handle specific items in cache. For more information, see Configuring the Global Advanced Options.

  3. For information about using the OK, Cancel, and Revert buttons, see Saving, Applying, or Canceling Configuration Changes.

4.2.2 Saving, Applying, or Canceling Configuration Changes

When you make configuration changes on a page accessed from Devices > Access Gateways > Edit and click OK on that page, the changes are saved to the browser cache. If your session expires or you close the browser session before you update the Access Gateway with the changes, the changes are lost.

The Configuration page allows you to control how your changes are saved so they can be applied with the update options (see Configuration Options).

If you have any configuration changes saved to the browser cache, use the following options to control what happens to the changes:

OK: To save the configuration changes to the configuration store, click OK. This allows you to return at a later time to review or modify the changes before they are applied. If your Access Gateways are clustered and you prefer to update them one at a time, you need to save the configuration change. This ensures that the changes aren’t lost before the last cluster member is updated. When your session times out or you log out, the configuration changes are flushed from the browser cache. If this happens before the changes have been applied to some servers in the cluster, the changes cannot be applied to those servers.

If you decide to cancel the saved changes, click the Revert button and the saved configuration is overwritten by the last successfully applied configuration.

Cancel: To cancel changes that are pending in the browser cache, click the Cancel button. To cancel modifications to specific services, click the Cancel link by the service. The Cancel button does not affect the changes that have been saved to the configuration store.

Revert: To cancel any saved changes, click Revert, then confirm the cancellation. The saved configuration is overwritten by the last successfully applied configuration.

If you have applied the changes to one member of the cluster, you cannot use the Revert button to revert to the configuration you had before applying the changes. If you decide you do not want to apply these changes to other members of the cluster, remove the server that you updated with the changes from the cluster. Then click Revert to cancel the saved changes. The members of the cluster return to the last successfully applied configuration. To apply this configuration to the removed server, add this server to the cluster.

The Revert button and the Cancel button cannot cancel the following configuration changes:

  • Identity Server Cluster: If you change the Identity Server Cluster option on the Reverse Proxy/Authentication page, then click OK, the Revert button cannot cancel this change. It is saved, and the next time you apply a configuration change, the Identity Server cluster configuration is applied. To cancel the change, you need to return to the Reverse Proxy/Authentication page, set the Identity Server Cluster option to the original selection, then click OK on the Configuration page.

  • Reverse Proxy for the Embedded Service Provider: If you change the Reverse Proxy option on the Reverse Proxy/Authentication page, then click OK, the Revert button cannot cancel this change. It is saved, and the next time you apply a configuration change, the Reverse Proxy option change is applied. To cancel the change, return to the Reverse Proxy/Authentication page, set the Reverse Proxy option to the original selection, then click OK on the Configuration page.

  • Port of the Reverse Proxy for the Embedded Service Provider: If you change the port of the reverse proxy that is used by the Embedded Service Provider (click Edit > [Name of Reverse Proxy]), then click OK, the Revert button cannot cancel this change. It is saved, and the next time you apply a configuration change, the port change is applied. To cancel the change, return to the Reverse Proxy page, set the port to the original value, then click OK on the Configuration page.

  • Published DNS Name of the Proxy Service for the Embedded Service Provider: If you change the Published DNS Name of the proxy service that is used by the Embedded Service Provider (click Edit > [Name of Reverse Proxy] > [Name of Proxy Service]), then click OK, the Revert button cannot cancel this change. It is saved, and the next time you apply a configuration change, the Published DNS Name is changed. To undo the change, return to the Proxy Service page, set the Published DNS Name to its original value, then click OK on the Configuration page.

  • Certificates: Certificates are pushed as soon as they are selected. If you change the server certificate for the reverse proxy (click Edit > [Name of Reverse Proxy]) or change the Web server certificates (click Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > Web Servers), the Revert button cannot cancel these changes. To undo the change, return to the page, select the original certificate, then click OK.

  • Renaming a Reverse Proxy: If you change the name of a reverse proxy (click Edit > Reverse Proxies / Authentication), then click OK, you cannot cancel this change. To undo the change, return to the Reverse Proxies / Authentication page, rename the reverse proxy to its original name, then click OK and update the Access Gateway.

4.2.3 Managing Access Gateways

The following sections contain information about settings available with Access Gateways, changing the settings, and their impact on users:

Viewing and Modifying Gateway Settings

Use the Servers page to view the status of Access Gateways, to modify their configuration, and to perform other actions such as creating a new cluster or stopping and starting an Access Gateway or its Embedded Service Provider.

  1. In the Administration Console, click Devices > Access Gateways.

  2. Select one of the following:

    Stop: To stop an Access Gateway, select the service, then click Stop. You can use the Restart option to start the Access Gateway.

    Restart: To stop and start an Access Gateway, select it, then click Restart. If the Access Gateway is already stopped, use Restart to start it.

    Refresh: To update the list of Access Gateways and the status columns (Status, Health, Alerts, Commands), click Refresh.

  3. To perform an action available in the Actions drop-down menu, select an Access Gateway, then select one of the following:

    Schedule Restart: To schedule when the selected Access Gateway must be stopped and then started, select Schedule Restart. On an Access Gateway Service, a restart stops the Access Gateway Service, then starts it. For information about how to schedule this command, see Scheduling a Command.

    Schedule Stop: To schedule when the selected Access Gateway or cluster must be stopped, select Schedule Stop.

    You can use the Restart option to start it again.

    For more information about how to schedule this command, see Scheduling a Command

    Purge List Now: Click Purge List Now to cause all objects in the current purge list to be purged from the cache of the selected server or cluster.

    Purge All Cache: Click Purge All Cache to purge the server cache for the selected server or cluster. All cached content is lost.

    When you make certain configuration changes such as updating or changing certificates, changing the IP addresses of Web servers, or modifying the rewriter configuration, you are prompted to purge the cache. The cached objects must be updated for users to see the effects of such configuration changes. If your Access Gateways are in a cluster, you need to manage the purge process so your site remains accessible to your users. You must apply the configuration changes to one member of a cluster. When its status returns to healthy and current, issue the command to purge its cache. Then apply the changes to the next cluster member.

    IMPORTANT:Do not issue a purge cache command when an Access Gateway has a pending configuration change. Wait until the configuration change is complete.

    Update Health from Server: Click this action to send a request to the server for updated health information. If you have selected multiple servers, a request is sent to each one. The health status changes to an animated circle until the reply returns.

    Service Provider: Select one of the following actions:

    • Start Service Provider: To start the Embedded Service Provider associated with the selected Access Gateway, click Start Service Provider. The Embedded Service Provider is the module within the Access Gateway that communicates with the Identity Server.

      The service provider must be restarted whenever you enable or modify logging on the Identity Server.

    • Stop Service Provider: To stop the Embedded Service Provider associated with the selected Access Gateway, click Stop Service Provider. The Embedded Service Provider is the module within the Access Gateway that communicates with the Identity Server.

      When an Access Gateway is not functioning correctly, you must always try stopping and starting the service provider before stopping and starting the Access Gateway.

    • Restart Service Provider: To restart the Embedded Service Provider associated with the selected Access Gateway, click Restart Service Provider. This command stops the Embedded Service Provider and then starts it. The Embedded Service Provider is the module within the Access Gateway that communicates with the Identity Server.

      When an Access Gateway is not functioning correctly, you must always try restarting the service provider before stopping and starting the Access Gateway.

  4. Use the following links to manage a cluster or an Access Gateway.

    Name: Displays a list of the Access Gateway servers and the clusters that can be managed from this Administration Console.

    • To view or modify the general details of a particular server, click the name of the server.

    • To view or modify general details of a cluster, click the name of the cluster.

    Status: Indicates the configuration status of the clusters and the Access Gateways. Possible states are pending, update, current, and update all. For more information, see Configuration Options.

    Health: Indicates whether a cluster or an Access Gateway is functional. Click the icon to view additional information about the operational status of an Access Gateway.

    Alerts: Indicates whether any alerts have been sent. If the alert count is non-zero, click the count to view more information.

    Commands: Indicates the status of the last executed command and whether any commands are pending. Click the link to view more information. For more information, see Viewing the Command Status of the Access Gateway.

    Statistics: Provides a link to the statistic pages.

    Edit: Provides a link to the configuration page. If the server belongs to a cluster, the Edit link appears on the cluster row. Otherwise, the link is on the server row. See Configuration Overview.

Configuration Options

Use the information in this section to modify the Status options described in Step 4.

  1. In the Administration Console, click Devices > Access Gateways.

  2. View the Status column and make changes as necessary.

    Status

    Description

    Current

    Indicates that all configuration changes have been applied.

    Update

    Indicates that a configuration change has been made, but not applied. To apply the changes, click the Update link, then select one of the following:.

    • All Configuration: The All Configuration option causes the Access Gateway to read its complete configuration file and restarts the Embedded Service Provider.

      The configuration update causes logged-in users to lose their connections unless the server is a member of a cluster. When the server is a member of a cluster, the users are sent to another Access Gateway and they experience no interruption of service.

    • Logging Settings: When the ESP logging settings have been modified on the Identity Server, the update option for Logging Settings is available. The Logging Settings option causes no interruption in services. When you modify Access Gateway logging settings, this option is not available because they are considered configuration settings.

    • Policy Settings: If a policy is modified for a protected resource of the Access Gateway and the policy change is the only modification that has occurred, the update option for Policy Settings is available. This option causes no interruption in services.

    • Rewriter Profile Changes: When the administrator changes the rewriter profile, a purge cache command is issued to a Gateway from the administration console, the connection is lost and the service is interrupted for a few seconds. Similar experience is observed during the rewriter profile configuration change, as this internally triggers the purge cache command.

    • Changing Certificates: When a certificate configuration is changed from the administration console, the service is interrupted due to the Tomcat restart.

    Update All

    This link is available when a server belongs to a cluster. You can select to update all the servers at the same time, or you can select to update them one at a time. If the modification is a policy or a logging change, then use Update All. If the modification is a configuration change, we recommend that you update the servers one at a time.

    • When you select Update All for a configuration change, users experience an interruption of service.

    • When you update servers one at a time for a configuration change, users experience no interruption of service.

    When you make the following configuration changes, the Update All option is the only option available and your site will be unavailable while the update occurs:

    • The Identity Server configuration that is used for authentication is changed (Access Gateways > Edit > Reverse Proxy/Authentication, then select a different value for the Identity Server Cluster option).

    • A different reverse proxy is selected to be used for authentication (Access Gateways > Edit > Reverse Proxy/Authentication, then select a different value for the Reverse Proxy option).

    • The protocol or port of the authenticating reverse proxy is modified (Access Gateways > Edit > Reverse Proxy/Authentication > [Name of Reverse Proxy], then change the SSL options or the port options).

    • The published DNS name of the authentication proxy service is modified (Access Gateways > Edit > Reverse Proxy/Authentication > [Name of Reverse Proxy] > [Name of First Proxy Service], then modify the Published DNS Name option).

    For more information, see Applying Changes to the Access Gateway Cluster Members.

    Update

    If the configuration update contains a configuration error, the Update link is disabled and the Configuration Error icon is displayed. Click the icon to discover which objects have been misconfigured. You need to fix the error by either canceling or modifying the changes before you can perform an update.

    Update All

    If the configuration update contains a configuration error, the Update All and the member Update links are disabled and the Configuration Error icon is displayed. Click the icon to discover which objects have been misconfigured. You need to fix the error by either canceling or modifying the changes before you can perform an update.

    Pending

    Indicates that the server is processing a configuration change, but has not completed the process.

    Locked

    Indicates that another administrator is making configuration changes. Before you proceed with any configuration changes, you need to coordinate with this administrator and wait until the Access Gateway has been updated with the other administrator’s changes.

Scheduling a Command

Use the Schedule New Command page to schedule a command, such as a shutdown, restart, or upgrade.

  1. In the Administration Console, click Devices > Access Gateways.

  2. (Conditional) To schedule a shutdown or restart, select a server, then click Actions > Schedule Restart or Schedule Stop. Continue with Step 3.

  3. Fill in the following fields:

    Name Scheduled Command: (Required) Specify a name for this scheduled command. This name is used in log files.

    Description: (Optional) Specify a reason for the command.

    Date & Time: Select the day, month, year, hour, and minute when the command must execute.

    The following fields display information about the command you are scheduling:

    Type: Displays the type of command that is being scheduled, such as Access Gateway Shutdown, Access Gateway Restart, or Access Gateway Upgrade.

    Server: Displays the name of the server that the command is being scheduled for.

  4. Click OK to schedule the command.

4.2.4 Managing General Details of the Access Gateway

The Server Details page allows you to perform general maintenance actions on the selected Access Gateway.

  1. In the Administration Console, click Devices > Access Gateways > [Name of Access Gateway].

  2. Select one of the following options:

    Edit: Click this option to edit the general details of the Access Gateway. See Changing the Name of an Access Gateway and Modifying Other Server Details.

    New IP: Click this action to trigger a scan to detect new IP addresses. This might take some time. If you have used a system utility to add an IP address after you have installed the Access Gateway Service, use this option to update the Access Gateway Service to display the new IP address as a configuration option. For more information about this option, see Adding a New IP Address to the Access Gateway.

    Configuration: Click this option to export the configuration of this Access Gateway or to import the configuration of a saved configuration file. See Exporting and Importing an Access Gateway Configuration.

  3. Click Close.

Changing the Name of an Access Gateway and Modifying Other Server Details

The default name of an Access Gateway is its IP address. You can change this to a more descriptive name as well as modifying other details that can help you identify one Access Gateway from another.

  1. In the Administration Console, click Devices > Access Gateways > [Name of Access Gateway] > Edit.

  2. Modify the values in the following fields:

    Name: Specify the Administration Console display name for the Access Gateway. This is a required field. The default name is the IP address of the Access Gateway. If you modify the name, the name must use alphanumeric characters and can include spaces, hyphens, and underscores.

    Management IP Address: Specify the IP address used to manage the Access Gateway. Select an IP address from the list.

    Port: Specify the port to use for communication with the Administration Console.

    Location: Specify the location of the Access Gateway server. This is optional, but useful if your network has multiple Access Gateway servers.

    Description: Describe the purpose of this Access Gateway. This is optional, but useful if your network has multiple Access Gateways.

  3. Click OK twice, then click Close.

    When you click OK, any changes are immediately applied to the Access Gateway.

Exporting and Importing an Access Gateway Configuration

You can export an existing Access Gateway configuration and its dependent policies, and then import this configuration to a new server. This feature is especially useful for deployments that set up configurations in a staging environment, test and validate the configuration, then want to deploy the configuration on new hardware that exists in the production environment.

IMPORTANT:The export feature is not a backup tool. The export feature is designed to handle configuration information applicable to all members of a cluster, and network IP addresses and DNS names are filtered out during the import. (The server-specific information that is filtered out is the information you set specifically for each member in a cluster.) If you want a copy of all configuration information, including server-specific information, you need to perform a backup. See Section 24.0, Back Up and Restore.

The export feature is not an upgrade tool. You cannot export a configuration from one version of Access Manager and import it into a newer version of Access Manager.

If your Access Gateway is not a member of a cluster and you have configured it to use multiple IP addresses, be aware that the export feature filters out multiple IP addresses and uses only eth0. You need to use the backup utility to save this type of information. If you need to reinstall the machine, leave the Access Gateway configuration in the Administration Console and reinstall the Access Gateway. If you use the same IP address for the Access Gateway, it imports into the Administration Console and inherits the configuration.

When exporting the file, you can select to password-protect the file, which encrypts the file. If you are using the exported file to move an Access Gateway from a staging area to a production area and you need to change the names of the proxy services and DNS names from a staging name to a production area and you need to change the names of the proxy services and DNS names from a staging name to a production name, do not select to encrypt the file. You need a simple text file so you can search and replace these names. If you select not to encrypt the file, remember that the file contains sensitive information and protect it accordingly.

Exporting the Configuration

  1. In the Administration Console, click Devices > Access Gateway > [Name of Access Gateway].

  2. Click Configuration > Export.

  3. (Conditional) If you want to encrypt the file, fill in the following fields:

    Password protect: Select this option to encrypt the file.

    Password: Specify a password to use for encrypting the file. When you import the configuration onto another device, you are prompted for this password.

  4. Click OK, then select to save the configuration to a file.

    The filename is the name of the Access Gateway with an xml extension.

  5. Export the policies used by the Access Gateway. In the Administration Console, click Policies > Policies, then either select Name to include all policies or individually select the policies to export.

    You need to export all Access Gateway policies and any Role policies used by the Access Gateway policies.

  6. Click Export and modify the proposed filename if needed.

  7. Click OK, then select to save the policy configurations to a file.

  8. (Conditional) If you have created multiple policy containers, select the next policy container in the list, and repeat Step 5 through Step 7.

    The policies for each container must be saved to a separate export file.

4.2.5 Setting Up a Tunnel

The tunnel option lets you create one or more services for the specific purpose of tunneling non-HTTP traffic through the Access Gateway to a Web server. To do this, the non-HTTP traffic must use a different IP address and port combination than the HTTP traffic.

An Access Gateway usually processes HTTP requests in order to fill them. However, it is not unusual that some of the traffic coming through the gateway is not HTTP-based. Web servers sometimes handle Telnet, FTP, chat, or other kinds of traffic without attempting to process it. If your Web servers are handling this type of traffic, you must set up a tunnel for it.

Reverse proxies and tunnels cannot share the same IP address and port combination. You can either configure a reverse proxy for an IP address and port or a tunnel for that IP address and port.

To set up a tunnel:

  1. In the Administration Console, click Devices > Access Gateways > Edit > Tunneling.

  2. Click New, enter a display name for the tunnel, then click OK.

  3. Specify the following details:

    Enable Tunnel: Specifies that the Access Gateway must set up a tunnel for all incoming traffic. This option must be enabled to configure a tunnel.

    Tunnel SSL Traffic Only: Allows you to configure the Access Gateway to tunnel only SSL traffic. If this option is selected, the Access Gateway verifies that the address and port being accessed are actually an SSL Web site. If verification fails, the service tears down the connection. The SSL port number for the SSL tunnel is specified via the Listening Port and the Connect Port.

    Published DNS Name: Specify the DNS name you want the public to use to access your tunnel or the virtual IP address assigned to the Access Gateway cluster by the L4 switch. If you specify a DNS name, the DNS name must resolve to the IP address you set up as the listening address for the tunnel.

  4. Configure the communication options between the browsers and the tunnel by configuring the following fields:

    Cluster Member: (Available only if the Access Gateway is a member of a cluster.) Select the server you want to configure from the list of servers. The Listening Address(es) modifications apply to the selected server. Any other modifications apply to all servers in the cluster.

    Listening Address(es): Displays a list of available IP addresses. If the Access Gateway has only one IP address, only one is displayed. If it has multiple addresses, you can select one or more addresses to enable. You must enable at least one address by selecting its check box.

    TCP Listen Options: Provides additional options for configuring how requests are handled. See Configuring TCP Listen Options for Clients. At least one Web server must be configured before you can modify these options.

    Listening Port: Specifies the port on which to listen for requests from browsers. The listening address and port combination must not match any combination you have configured for a reverse proxy.

  5. Configure the communication options between the tunnel and the Web servers by configuring the following fields:

    Connect Port: Specifies the port that the Access Gateway uses to communicate with the Web server.

    TCP Connect Options: Allows you to control how idle and unresponsive Web server connections are handled and to optimize these processes for your network. See Configuring TCP Connect Options for Web Servers.

  6. Specify a Web server to receive the traffic. In the Web Server List section, click New, specify the IP address or DNS name of the Web server, then click OK.

    At least one Web server must be specified in the list before you can save a tunnel configuration.

  7. To save your changes to browser cache, click OK.

  8. To apply your changes, click the Access Gateways link, then click Update > OK.

4.2.6 Setting the Date and Time

The Date & Time option lets you set the system time for the Access Gateway.

The time between the Identity Server and the Access Gateway must be either synchronized or set to be within 1 minute of each other for trusted authentication to work.

To configure the date and time options:

  1. In the Administration Console, click Devices > Access Gateways > Edit > Date & Time.

  2. (Conditional) If the Access Gateway belongs to a cluster of Access Gateways, select the Access Gateway from the list displayed in the Cluster Member field. The modifications you make on this page apply only to the selected Access Gateway.

    If the Access Gateway does not belong to a cluster, this option is not available.

  3. Specify the following details:

    Server Date and Time: Displays the current time and allows you to set the current time. Click Set Date & Time Manually, then select the current year, month, day, hour, and minute.

    IMPORTANT:If the date is set to a time before the Access Gateway certificates are valid, communication to the Access Gateway is lost. This error cannot be corrected from the Administration Console. You need to correct it at the console of the Access Gateway machine.

    Use the yast command and select System > Date and Time.

    Set Up NTP: Click this option to specify the DNS name or IP address of a Network Time Protocol server. The installation program enters the name of pool.ntp.org, the DNS name of a public NTP server. To disable this feature, you must remove all servers from the NTP Server List. This is not recommended.

    Time Zone: Select your time zone, then click OK. Regardless of the method you used to set the time, you must select a time zone.

  4. Click OK.

  5. On the Server Configuration page, click OK.

  6. To apply your changes, click Update > OK.

4.2.7 Configuring Network Settings

After initial setup, you seldom need to change the network settings unless something in your network changes, such as adding a new gateway or DNS server. These options are for the Access Gateway Appliance. For the Linux or Windows Access Gateway Service, use the utilities supplied by the operating system. However, if you add an new network interface card to the Access Gateway Service machine and use system utilities to configure it and assign it an IP address, you need to update the Access Gateway Service with this information. See Adding a New IP Address to the Access Gateway.

This section describes the following tasks:

Viewing and Modifying Adapter Settings

The adapter settings allow you to view the current configuration for the network adapters installed in the Access Gateway Appliance and manage the IP addresses that are assigned to them.

  • If you want to configure an adapter to use more than one IP address, you can use these settings to add them.

  • If you have multiple adapters installed on an Access Gateway Appliance machine, you can only configure eth0 during installation. Use the procedure described in this section to configure the others.

To view or modify your current adapter settings:

  1. In the Administration Console, click Devices > Access Gateways > Edit > Adapter List.

  2. (Conditional) If the Access Gateway is a member of a cluster, select the server you want to configure from the list of servers in the Cluster Member field. All changes made to this page apply to the selected server.

  3. Select the adapter you want to modify, then select one of the following actions:

    • To add a new subnet to an existing adapter, click New.

    • To delete a subnet, select a subnet, then click Delete. More than one subnet must be configured for you to delete one.

    • To modify an existing subnet, click the IP address of the subnet.

  4. To configure a new subnet or a new IP address for a subnet, configure the following fields:

    Subnet: Displays the address of the subnet that you are modifying. This is empty if you are creating a new subnet.

    Subnet Mask: (Required) Specifies the subnet mask address for this subnet. The address can be specified in standard dotted format or in CIDR format.

    IP Addresses: Allows you to manage the IP addresses assigned to the subnet.

    • To add an address, click New, specify the address, then click OK.

    • To delete an address, select the address, then click Delete.

    • To change the IP address, select the address, then click Change IP Address, specify the new IP address, then click OK.

  5. Click OK.

  6. Click OK.

  7. On the Server Configuration page, click OK, then click Update > OK.

Viewing and Modifying Gateway Settings

The gateway settings display the current gateway configuration that the Access Gateway Appliance is using to route packets. On this page, you can also configure additional gateways. During installation, you could specify only a default gateway. You must have at least one gateway defined for the Access Gateway to function.

The Access Gateway routes requests to specific destinations through these gateways. If a request could be routed through multiple gateways, the Access Gateway chooses the gateway associated with the most restrictive mask (the smallest range of destination addresses). The default gateway is used only when no other routes apply.

Gateways fall within the following three basic groups:

  • Host gateways for specific destination addresses.

  • Network gateways for destination addresses that fall within specific subnets.

  • The default gateway for destination addresses that aren’t covered by host or network gateways.

The Access Gateway uses additional gateways only when the Act As Router option is selected. When this option is selected, you can add Host Gateways and Network Gateways. When configuring a Host Gateway or Network Gateway, you specify the IP address of the host or network gateway in the Next Hop field. This address must be on the same subnetwork as the IP address for the Access Gateway.

IMPORTANT:If you enter an IP address that is on a different subnetwork, the Access Gateway reports this error on the Health page, after the configuration has been applied.

To modify your current gateway configuration:

  1. In the Administration Console, click Devices > Access Gateways > Edit > Gateways.

  2. Configure your default gateway, which specifies the gateway to use when no other routes apply. Configure the following:

    Next Hop: The IP address of the gateway.

    Metric: A relative number indicating the bias you can add to the normal flow of gateway logic. Specifying a number higher than 1 makes this resource more expensive and alters the gateway logic used. Valid numbers include 1 through 16.

    Type: Gateways are active if they publish their presence, or passive if they do not.

  3. Configure your host gateways, which are the gateways to be used for packets being sent to specific hosts. When you select New from the Host Gateway list, you are asked for the following information:

    Next Hop: The address of the host gateway that is to be used.

    Host: The IP address of the destination host. Valid addresses cannot be the first or last address of a class and must be unique.

    Metric: A relative number indicating the bias you can add to the normal flow of gateway logic. Specifying a number higher than 1 makes this resource more expensive and alters the gateway logic used. Valid numbers include 1 through 16.

    Type: Gateways are active if they publish their presence, or passive if they do not.

    Click OK when the fields are configured.

  4. Configure your network gateways, which are the gateways to be used for packets being sent to specific subnets. When you select New from the Network Gateway list, you are asked for the following information:

    Next Hop: The address of the gateway that is to be used.

    Network Address: The subnet address for the destination IP address range. You must enter the valid subnet address.

    Mask: The subnet mask for the subnet or IP address above. A valid entry must be at least as large as a class mask where a Class A mask is 255.0.0.0, a Class B mask is 255.255.0.0, and Class C, D, and E masks are 255.255.255.0.

    Metric: A relative number indicating the bias you can add to the normal flow of gateway logic. Specifying a number higher than 1 makes this resource more expensive and alters the gateway logic used. Valid numbers include 1 through 16.

    Type: Gateways are active if they publish their presence, or passive if they do not.

    Click OK when the fields are configured.

  5. Click OK.

  6. On the Server Configuration page, click OK, then click Update > OK.

Viewing and Modifying DNS Settings

The DNS page displays the current configuration for domain name services for the Access Gateway Appliance and allows you to modify it.

  1. In the Administration Console, click Devices > Access Gateways > Edit > DNS.

  2. (Conditional) If the Access Gateway is a member of a cluster, select the server you want to configure from the list of servers in the Cluster Member field. All changes made to this page apply to the selected server.

  3. Specify the following details:

    Server Hostname: Displays the unique host or computer name that you have assigned to the Access Gateway machine. If you modify this name, you need to modify the entry for the Access Gateway in your DNS server to resolve this new name.

    Domain: Specifies the domain name for your network. Your DNS server must be configured to resolve the combination of the server hostname and the domain name to the Access Gateway machine. This field assumes you are using dotted names for your machines, such as sales.mytest.com, where sales is the Server Hostname and mytest.com is the Domain.

    DNS Server IP Addresses: Displays the IP addresses of the servers on your network that resolve DNS names to IP addresses. You can have up to three servers in the list. If you specified any addresses during installation, they appear in this list. To manage the servers in this list, select one of the following options:

    • New: To add a server to the list, click this option and specify the IP address of a DNS server.

    • Delete: To delete a server from the list, select the address of a server, then click this option.

    • Order: To modify the order in which the DNS servers are listed, select the server, then click either the up-arrow or the down-arrow buttons. The first server in the list is the first server contacted when a DNS name needs to be resolved.

  4. Click OK.

  5. On the Server Configuration page, click OK, then click Update > OK.

Configuring Hosts

You can configure the Access Gateway Appliance to have multiple hostnames or to resolve DNS names to IP addresses. If you manually edit the /etc/hosts file, your modifications are lost when the Access Gateway Appliance is updated. However, if you use the Hosts page to specify the entries, the entries are written to the /etc/hosts file whenever the configuration of the Access Gateway Appliance is updated.

  1. (Access Gateway Appliance) In the Administration Console, click Devices > Access Gateways > Edit > Hosts.

  2. (Conditional) If the Access Gateway is a member of a cluster, select the server you want to configure from the list of servers in the Cluster Member field. All changes made to this page apply to the selected server.

  3. To add a new hostname to an existing IP address, click the name of a Host IP Address.

  4. In the Host Name(s) text box, specify a name for the host. Place each hostname on a separate line, then click OK.

  5. To add a new IP address and hostname, click New in the Host IP Address List section, then specify the IP address. In the Host Name(s) text box, specify a hostname, then click OK.

  6. To delete a host, select the check box next to the host you want to delete, then click Delete.

  7. Click OK.

  8. On the Server Configuration page, click OK, then update the Access Gateway.

Adding a New IP Address to the Access Gateway

Before configuring the Access Gateway to use a new IP address, you must first use an operating system utility to add the IP address.

After you have used a system utility to add an IP address, you need to update the Access Gateway Service to display the new IP address as a configuration option.

  1. In the Administration Console, click Devices > Access Gateways > [Name of Gateway Service].

  2. On the Server Details page, click New IP > OK.

    The Access Gateway scans the operating system for its configured IP addresses and adds any new addresses. The new address is then available for assignment on the Access Gateway configuration pages.

  3. (Optional) To verify that the scan has completed, click the Command Status tab.

4.2.8 Enabling the Access Gateway to Display Post-Authentication Message

When the Identity Server authentication process is completed, the user-agents are redirected to their originally requested URL. The originally requested URL is then retrieved by the proxy. This process requires SSO and authentication process of its own. As a result, retrieving the requested URL may take a long time. It is not clear how much time the authentication process takes and how much time the origin server request and authentication processes take.

To remove this ambiguity, you can enable the Access Gateway to display a message before redirecting the user-agent to the originally requested URL.

To enable this enhancement, complete the following steps:

  1. Go to Devices > Access Gateways > Edit > Reverse Proxy /Authentication > ESP Global Options.

  2. Set IS_DISPLAY_AUTH_DONE_PAGE to true.

When this option is enabled, the following message is displayed before the final redirect to the requested URL: 

Authentication successful, please wait while your requested page loads.

The web page that display this message is a JSP page. Location of this page is /opt/novell/nam/mag/webapps/nesp/jsp/waitredir.jsp. You can perform further customization on this page.

4.2.9 Customizing The Access Gateway

Maintaining a Customized Access Gateway

If you have customized the .jsp files for the Access Gateway, you must perform the following steps to maintain the customized files before upgrading Access Manager. If you do not, Access Manager overwrites the customized .jsp files. For more information, see Maintaining Customized JSP Files for Access Gateway in the NetIQ Access Manager Appliance 4.2 Installation and Upgrade Guide.

Customizing Error Messages and Error Pages on Access Gateway

Access Gateway uses the custom error page template to rebrand and localize the language of error pages that are published to the browser.

By default, Access Gateway contains the following files to help customize and localize the error messages:

  • The error page configuration file, ErrorPagesConfig.xml

  • The error messages file, ErrorMessages.xml.en

NOTE:If you are modifying any of the above files, ensure that you retain the original filenames.

Access Gateway maintains /opt/novell/nam/mag/webapps/agm/WEB-INF/config/current/ directory to save files that are used for error page configuration.

You can customize and localize the error template and the error messages:

Customizing and Localizing Error Messages

When Access Gateway serves an error message to the browser by using the Accept-Language header value received from the browser, it selects a suitable error template and an error message file. To localize the error messages, you must to do the following:

Localize or customize the error messages in the ErrorPagesConfig.xml file and save it with the language extension.

The error messages contained in the ErrorMessages.xml.en file can be localized in various languages and stored as ErrorMessages.xml.<lang>, where <lang> is the fileXn attribute value. You can also customize the English error messages present in the ErrorMessages.xml.en file.

NOTE:You cannot customize an error message that is not present in the ErrorMessages.xml.en file.

To localize the error messages, perform the following steps:

  1. Log in as root.

  2. Open the ErrorMessages.xml.<lang> file.

  3. Copy the error messages that you have localized or customized to within the <TranslatedMessage></TranslatedMessage> tags. For example:

    </Message>
  <Message id="<ID No>" name="<ERROR_MESSAGE_NAME>" enable="yes">
    <EnglishMessage>English Message goes here</EnglishMessage>
<TranslatedMessage>
Localized message goes here
</TranslatedMessage>
</Message>

    Do not delete the contents within the <TranslatedMessage></TranslatedMessage> tags from an English file because, the ErrorPagesConfig.xml file selects the error message within these tags for display.

  4. Save the file.

  5. If the Access Gateway belongs to a cluster, copy the modified file to each member of the cluster, then restart that member.

  6. Edit the configuration and make dummy changes and push the configuration.

Customizing the Error Pages

Access Gateway uses the Apache method for localizing error messages. You can modify these messages or customize the page they are displayed on.

  1. To change a message:

    1. Change to the Apache message configuration directory:

      /etc/opt/novell/apache2/conf/extra

    2. Open the http-multilang-errordoc.conf file.

      The first few lines of this file contains comments on how Apache recommends modifying the error messages. You can select to use their method or continue with the following steps.

    3. Locate the ErrorDocument section and determine the error code message you want to modify. Make note of the *.var filename.

    4. Change to the Apache error directory:

      /opt/novell/apache2/share/apache2/error

    5. Open the *.var file that you want to modify.

      The message is listed alphabetically by language code.

    6. Save the changes.

  2. To change the header of the error page:

    1. Change to the Apache error include directory:

      /opt/novell/apache2/share/apache2/error/include

    2. Open the top.html page.

    3. To change the title of the page, locate the following line:

      <title>Access Manager<\title>

    4. Replace the Access Managerstring with the content you require.

    5. To replace the image in the header, locate the following line:

      <img src="/NAGErrors/images/header_550.png" alt="" height="50px" width="550px" border="0">

    6. Replace header_550.png with the filename of the image you want to display.

    7. Adjust the height and width values to match your image.

    8. Save the file.

    9. Copy your image to the images directory:

      /opt/novell/apache2/share/apache2/error/images

  3. To change the footer of the error page:

    1. Change to the Apache error include directory:

      /opt/novell/apache2/share/apache2/error/include

    2. Open the bottom.html page.

    3. To change the image, find the following line:

      <td style="background-color: #E6D88C; padding-left: 10px"><img style="padding-right: 200px" src="/NAGErrors/images/LAP_interoperable_logo_100.gif" align="absmiddle" border="0">

    4. Change LAP_interoperable_logo_100.gif to the filename of the image you want to display.

    5. Save the file.

    6. Copy your image to the images directory:

      /opt/novell/apache2/share/apache2/error/images

  4. Copy all modified files and image files to all Access Gateways in the cluster.

The err_legacy.jsp file will also log the ESP error messages. For more information on customizing the err_legacy.jsp page, see Customizing Identity Server Messages. The procedure for customizing is the same except the paths for the Access Gateway. The following are the path changes:

  • In Customizing Identity Server Messages, the paths for Access Gateway are as follows:

    • Step 3, path on Linux is /opt/novell/nam/mag/webapps/nesp/WEB-INF/lib and on Windows is /Program Files/Novell/Tomcat/webapps/nesp/WEB-INF/lib/.
    • Step 10, path on Linux is /opt/novell/nam/mag/webapps/nesp/WEB-INF/classes and on Windows is /Program Files/Novell/Tomcat/webapps/nesp/WEB-INF/classes.
    • Step 12, restart the Access Gateway by running /etc/init.d/novell-mag restart.

  • In Customizing the Branding of the Error Page, the path for err_legacy.jsp in the ESP on Linux is /opt/novell/nam/mag/webapps/nesp/jsp and on Windows is /Program Files/Novell/Tomcat/webapps/nesp/jsp/.

Customizing Logout Requests

Customizing Applications to Use the Access Gateway Logout Page

If any of your protected resources have a logout page or button, you need to redirect the user’s logout request to the Access Gateway logout page. The Access Gateway can then clear the user’s session and log the user out of any other resources that have been enabled for single sign-on. If you do not redirect the user’s logout request, the user is logged out of one resource, but the user’s session remains active until inactivity closes the session. If the user accesses the resource again before the session is closed, single sign-on reauthenticates the user to the resource, and it appears that the logout did nothing.

  1. In the Administration Console, click Devices > Access Gateways > Edit > Reverse Proxy / Authentication.

  2. In the Embedded Service Provider section, view the path to the AGLogout page in the Logout URL option.

    The Logout URL displays the URL that you need to use for logging users out of protected resources. This option is not displayed until you have created at least one reverse proxy with a proxy service. If you create two or more reverse proxies, you can select which one is used for authentication, and the logout URL changes to match the assigned reverse proxy.

  3. Redirect application logout requests to the AGLogout page.

  4. Click OK.

The Access Gateway does not support the following logout pages that were used in previous version of Access Manager and iChain:

  • /cmd/BM-Logout

  • /cmd/ICSLogout

Customizing the Access Gateway Logout Page

You can create your own logout page and configure the Access Gateway to use it. To do this, you need to modify the logoutSuccess_legacy.jsp file on the Access Gateway. It is located in the following directory:

/opt/novell/nesp/lib/webapp/jsp

You can modify the file to display what you want or you can modify it to redirect the user to your custom page. The following sections provide some tips for accomplishing this task:

Modifying the Header

The logoutSuccess_legacy.jsp file is called in a frame from the nidp_legacy.jsp file. The branding in the header of the logout page is controlled by the branding of the nidp.jsp file. For information about how to modify nidp_legacy.jsp for logos, titles, and colors, see Logging Out of Sessions to the Access Gateway and SAML Connectors when Branding Exists in the Customized Logout Page.

IMPORTANT:Take a backup of nidp_legacy.jsp file before modifications. Every time you upgrade your Access Gateway, upgrade process overrides any custom changes made to JSP files that use the same filename as those included with the product. If you want the modified file, you need to restore the nidp_legacy.jsp file. During an upgrade, you can select to restore custom login pages, but NetIQ still recommends that you have your own backup of any customized files.

Calling Different Logout Pages

If you need to use a different logout page for specific protected resources, you can modify the logout button of the applications to use the AGLogout URL or the plogout URL. The AGLogout page calls the plogout page, which in turn calls logoutSuccess_legacy.jsp. Any parameter added to the AGLogout or plogout URL is saved and passed to the logoutSuccess_legacy.jsp file.

The parameter passed to logoutSuccess_legacy.jsp can be used with if/else logic in the body of the page to load different custom logout pages based on the parameter value.

To use the plogout URL, modify the application’s logout button to call the following URL:

<ESP Domain>/nesp/app/plogout

Replace <ESP Domain> with the same value as the AGLogout value. For example, suppose the following is your AGLogout value:

https://jwilson1.provo.novell.com:443/AGLogout

Replace it with the following value:

https://jwilson1.provo.novell.com:443/nesp/app/plogout

If you add a parameter to the URL, it would look similar to the following:

https://jwilson1.provo.novell.com:443/nesp/app/plogout?app=email

Redirecting to Your Custom Page

Server side redirection: You can replace the information in the <body> element of the logoutSuccess_legacy.jsp file with something similar to the following: 

<body> 
      <script language="JavaScript"> 
        top.location.href='http://<hostname/path>'; 
      </script>     
</body>

Replace the <hostname/path> string with the location of your customized logout page.

Client side redirection by using JavaScript: You can customize logoutSuccess_legacy.jsp to redirect the logout request to the page that is specified in the query parameter.

For example, add the following logic in logoutSuccess_legacy.jsp:

<%
    String sImpDomain = request.getParameter("impDomain");
    out.println ("sImpDomain from Request: " + sImpDomain + "<BR>" );

    if (null == sImpDomain)
    {
        sImpDomain = uh.getLogoutQueryStringParam("impDomain");
        out.println ("sImpDomain from Handler: " + sImpDomain + "<BR>" );
    }
    String strDestinationUrl = null;
    if (null != sImpDomain)
    {
            if(sImpDomain.equals("digitalairlines")){
                    strDestinationUrl  = "https://www.DigitalAirlines.com";
            }else if(sImpDomain.equals("example")){
                    strDestinationUrl  = "https://www.example.com";
            }
        if (null != strDestinationUrl)
        {
%>
                <script>
                        alert("Client browser is getting redirected to <%=strDestinationUrl%>");
                        window.location = "<%=strDestinationUrl%>";
                </script>
<%
        }
    }
%>

To test this example, make an AGLogout request from a logged in session in the browser as follows:

https://<base-url>/AGLogout?impDomain=digitalairlines

The client browser displays the following message: 

Client browser is getting redirected to https://www.digitalairlines.com

After clicking OK, the browser gets redirected to https://www.digitalairlines.com. Similarly if the AGLogout request is made with impDomain=example, then client browser will be redirected to https://www.example.com.

IMPORTANT:Take a backup of logoutSuccess_legacy.jsp file before modifications. Every time you upgrade your Access Gateway, upgrade process overrides any custom changes made to JSP files that use the same filename as those included with the product. If you want the modified file, you need to restore the nidp_legacy.jsp file. During an upgrade, you can select to restore custom login pages, but NetIQ still recommends that you have your own backup of any customized files

Logging Out of Sessions to the Access Gateway and SAML Connectors when Branding Exists in the Customized Logout Page

When you have both Liberty and SAML 2.0 sessions running on the Identity Server and you log out of the Access Gateway, the logoutSuccess_legacy.jsp page is not executed with the customization you have made to the logout page. You will be able to log out of the Access Gateway but the customization you made are lost.

If the logutSuccess_legacy.jsp file is not loaded in a frame, the banner will not be displayed, and the Access Gateway will comment out the content in the logoutSuccess_legacy.jsp file. Add the below line after the <body> tag in the logoutSuccess_legacy.jsp file.

<!-- BANNER LOADS IF THIS PAGE IS NOT LOADED IN REGULAR FRAME -->
<%@include file="logoutHeader.jsp"%>

Configuring the Logout Disconnect Interval

When a user clicks the logout button and the user is logging out of an Access Gateway that is a member of a cluster, the user is not immediately disconnected from the resource. The logout message must be sent to each member of the cluster. The default interval for checking the pending logout message queue is 30 seconds. If this interval is too long, you can configure a shorter interval in the web.xml file of the Embedded Service Provider. This must be set on each Access Gateway in the cluster.

  1. Log in to the Access Gateway as the root or administrator user.

  2. Open web.xml.

    /opt/novell/nesp/lib/webapps/WEB-INF/web.xml

  3. Find the <context-param> section in the file.

  4. Add the following parameter to the <context-param> section.

    <context-param>
    <param-name>logoutRetirementFrequency</param-name>
    <param-value>15000</param-value>
</context-param>

  5. Set the <param-value> element to a value between 5000 and 30000 milliseconds (5 seconds and 30 seconds).

  6. Restart the Embedded Service Provider.

    For information about how to restart the Embedded Service Provider from the Administration Console, see Managing Access Gateways.