4.2 Access Gateway Server Advance Configuration

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 Section 3.8.2, 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 Section 4.2.5, Setting Up a Tunnel.

    Date & Time: Allows you to configure the server’s time source. For more information, see Section 4.2.6, 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 Section 22.2.3, 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 Section 15.3, 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.

    Service Provider Certificates: Displays information about the certificates assigned to the Embedded Service Provider component of the Access Gateway. For more information, see Section 12.3.1, Managing Embedded Service Provider Certificates.

    Purge List: Allows you to prevent Web objects from being cached. For more information, see Section 4.3.5, 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 Section 4.3.4, 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 Section 4.4.1, Configuring the Global Advanced Options.

  3. For information about using the OK, Cancel, and Revert buttons, see Section 4.2.2, 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:

    New Cluster: To create a new cluster of Access Gateways, click New Cluster. A cluster can be one or more Access Gateways.

    To create a new cluster of Access Gateways, click New Cluster. A cluster can be one or more Access Gateways. For configuration information, see Creating a New Cluster.

    Stop: To stop an Access Gateway Appliance, select the appliance, then click Stop. You must have physical access to the Access Gateway Appliance machine to start it again. To stop an Access Gateway Service, select the service, then click Stop. You can use the Restart option to start the Access Gateway Service.

    Restart: To reboot an Access Gateway Appliance, select the appliance, then click Restart. The Access Gateway Appliance is stopped, the operating system is rebooted, then the appliance is started. To stop and start an Access Gateway Service, select it, then click Restart. If the Access Gateway Service 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:

    Assign to Cluster: To add the selected Access Gateway to a cluster, select Assign to Cluster, then select the cluster. This Access Gateway is reconfigured with the configuration of the primary cluster server. A Gateway Appliance can only be added to a cluster that already contains a Gateway Appliance. A Gateway Service can be added to any cluster.An Access Gateway Appliance can only be added to a cluster of Access Gateway Appliances. An Access Gateway Service can only be added to a cluster of Access Gateway Services.

    Remove from Cluster: To remove the selected Access Gateway from a cluster, select Remove from Cluster. The Access Gateway retains its configuration from the cluster, but no traffic is sent to it until it is reconfigured. You can assign it to a different cluster and have it updated with this cluster’s configuration, or you can delete all of its reverse proxies and start a new configuration.

    Delete: To remove the selected Access Gateway server from the list of servers that can be managed from this Administration Console, select Delete. If the Access Gateway is a member of a cluster, you must first remove it from the cluster before you can delete it.

    IMPORTANT:When an Access Gateway is deleted from the Administration Console, you can no longer manage it. To access it again, you must manually trigger an auto-import, which causes it to import into an Administration Console.

    Schedule Restart: To schedule when the selected Access Gateway should be stopped and then started, select Schedule Restart. On an Access Gateway Appliance, a restart stops the operating system, then starts the operating system and the Access Gateway. 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 should be stopped, select Schedule Stop.

    • When you stop an Access Gateway Appliance, you shut down the Access Gateway Appliance and the operating system. You must have physical access to the machine to start it again.

    • When you stop an Access Gateway Service, you stop just the Access Gateway Service. 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 should 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 should 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 should 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 should 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 Section 21.2, 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 Section 4.2.1, 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.

Impact of Configuration Changes

This section covers the impact of some of the common Access Gateway configuration settings on users.

NOTE:Do not push the configuration from the Administration Console to devices during peak system usage times.

Devices > Access Gateways

  • Purge List Now/ Purge Cache: Causes a process level restart and terminates all the existing connections and downloads. The users do not need to reauthenticate, but issuing a purge list or cache command might result in a higher load on the service provider. If there is a single gateway, issuing a purge list or cache command can cause temporary service disruption for users.

  • Stop: Stops the proxy component in the Access Gateway Appliance, makes it unavailable for user requests and terminates all the existing connections and downloads. The users do not need to reauthenticate, but stopping the proxy component can result in a higher load on the identity provider and other gateway cluster members.

  • Restart: Triggers a restart of the operating system of the Access Gateway Appliance, where all existing connections and downloads are terminated. The users do not need to reauthenticate, but restarting the operating system can result in a higher load on the identity provider and other gateway cluster members.

  • Service Provider > Restart: Causes the ESP and proxy to clear the user session information and refresh the policy information. Access might be denied to protected resources and resources that need policy evaluation during the restart process.

  • Service Provider > Stop: Causes the ESP and proxy to clear the user session information. You cannot access the protected resources and resources that need policy evaluation.

Devices > Access Gateways > < your gateway/cluster> Services

  • Rewriter Profile Change: Changing the rewriter profile causes the Administration Console to issue a purge cache command to the Access Gateway. Issuing a purge cache command causes a process level restart and terminates all the existing connections and downloads.

  • Accelerated Web Service Change: Changing the accelerated Web server details causes the Administration Console to issue a purge cache command to the Access Gateway. Issuing a purge cache command causes a process level restart and terminates all the existing connections and downloads

  • Service Creation: If your gateway cluster is behind an L4 switch, ensure that you review or modify the L4 configuration to reflect any new service that you can create.

  • TCP Connect Options: Increasing the Data Read Timeout values or the Idle Timeout values impacts the user experience if the Web servers are unreachable. Disabling the persistent connections also impacts the user experience.

System Settings

  • Date and Time: Changing date and time or the NTP server configuration impacts the existing user session timeout values. It is critical to keep the time settings in Access Gateways and Identity Servers synchronized in order to prevent authentication failures and unexpected session times out. There is no other impact than authentication failures and unexpected session times out.

Monitoring

  • Audit Configuration Changes or Audit Server Health: If the audit server is busy or unreachable, it causes a delay in browsing, including Administration Console access. There is no other impact than delay in browsing and accessing the Administration Console.

Network Settings

  • Network Related Changes: Be cautious in making changes to the network parameters like Adapter, IP address, Netmask, Gateways, DNS, Hosts, and Route. The users can be impacted by these changes because the connections are reset; however, user reauthentication might not be required. Incorrect configuration leads to system inaccessibility on the network and you cannot access the Access Gateway service.

Security Settings

You should not change security setting options during the peak system usage hours.

  • Signing: Before changing it, ensure that the Identity Server trust store contains the root CA certificate and possible intermediate CA certificates to complete the trust chain.

  • Trust Store: Before changing it, ensure that you have all the root CA certificates and possible intermediate CA certificates to complete the trust chain to trust any certificates used by the Identity Server.

Content Settings

  • Cache Options: Be cautious in making changes to the cache options. Changing cache options can impact the performance of your Access Manager system. You might see an increase or decline in the Access Gateway performance, depending on the changes made to the cache options.

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 4.

  3. (Conditional) To schedule an upgrade for the Access Gateway Appliance, click [Name of Server] > Upgrade > Schedule Upgrade.

  4. 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 should 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.

  5. 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 NIC: (Only for 3.1 SP4 Access Gateway Appliance) Click this action to trigger a scan to detect a new network interface card that you have added to the machine after installing the Access Gateway Appliance. This might take some time. For more information, see Adding New Network Interfaces to the Access Gateway Appliance.

    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. For information about changing the Management IP Address, Section 2.4.3, Changing the IP Address of an Access Gateway Appliance.

    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 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 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.

The following sections explain this process:

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. (Conditional) If you want to change the names of the proxy services and their DNS names from a staging name to a production name, complete the following:

    1. Open the configuration file in a text editor.

    2. Search and remove the staging suffix.

      If you have specified DNS names with a staging suffix (for example, innerwebstaging.provo.novell.com), you can search for staging.provo.novell.com and remove staging from the name.

      In particular, you need to change the following:

      • Any fully qualified DNS names from the staging name to the production name (DNSName elements in the file)

      • The cookie domains associated with each proxy service (AuthenticationCookieDomain elements in the file)

      • The URL masks in pin lists that contain fully qualified names (URLMask elements in the file)

      Depending upon your naming standards, you might want to change the names of the following:

      • UserInterfaceID elements (proxy service, pin list, and protected resource user interface ID's)

      • Description elements (proxy service, pin list, and protected resource descriptions)

      • Name (proxy service, pin list, and protected resource names)

      • SubServiceID elements

      • MultiHomeMasterSubserviceIDRef elements

      • LogDirectoryName elements

      • ProfileIDRef elements

      • ProtectedResourceID elements

      • ProfileID elements (TCP Listen options name)

    3. (Conditional) If your Web servers in the staging area have different IP addresses and hostnames than the Web Servers in the production area, you can search and replace them in the configuration file or wait until after the import and modify them in the Administration Console.

  6. 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.

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

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

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

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

  10. (Conditional) If your policies redirect users to staging URLs when they are denied access, search and replace these URLs with the production URLs. Open the policy file with a text editor and search for your staging name.

  11. Copy the Access Gateway and policy configuration files to a place accessible by the new Access Gateway.

  12. Continue with Importing the Configuration.

Importing the Configuration

  1. Verify that the Access Gateway meets the conditions for an import:

    • The Access Gateway should not be a member of a cluster. If it is a member of a cluster, remove it from the cluster before continuing.

      In the Administration Console, click Devices > Access Gateways, select the Access Gateway, then click Actions > Remove from Cluster.

      You can create a cluster and add this machine to the cluster as the primary server after you have completed the import.

    • The Access Gateway should be an unconfigured machine. If it contains reverse proxies, delete them before continuing.

      In the Administration Console, click Devices > Access Gateways > Edit > Reverse Proxies / Authentication. In the Reverse Proxy List, select Name, then click Delete. Update the Access Gateway and the Identity Server.

  2. In the Administration Console, click Policies > Policies.

    The policies that the Access Gateway is dependent upon must be imported first.

  3. (Conditional) If you have exported policies from more than one container, create the policy containers. Click the Containers tab; in the Container List, click New, specify the name for the container, then click OK.

  4. (Conditional) If your system already contains policies, delete them if they are not being used.

    If they are in use and you have policies with the same names as the policies you are going to import, you need to manually reconcile the duplicate policies. See step 5 in Cleaning Up and Verifying the Configuration.

  5. In the Policy List, click Import.

  6. Browse to the location of the policy configuration file, select the file, then click OK.

  7. (Conditional) If you exported multiple policy configuration files, repeat Step 5 and Step 6.

  8. Enable all new Role policies. Click Identity Servers > Edit > Roles.

  9. Either select Name to enable all policies or individually select the policies, then click Enable.

  10. Click OK, then click Update.

  11. To import the Access Gateway configuration, click Access Gateways > [Name of Access Gateway] > Configuration > Import.

  12. Browse to the location of the configuration file, select the file, enter a password if you specified one on export, then click OK.

  13. Continue with Cleaning Up and Verifying the Configuration.

Cleaning Up and Verifying the Configuration

  1. When the configuration import has finished, verify the configuration for your reverse proxies.

    1. Click Access Gateways > Edit > [Name of Reverse Proxy].

    2. Verify the listening address.

      This is especially important if your Access Gateway has multiple network adapters. By default, the IP address of eth0 is always selected as the listening address.

    3. Verify the certificates assigned to the reverse proxy.

      The Subject Name of the certificate should match the published DNS name of the primary proxy service in the Proxy Service List.

    4. Verify the Web Server configuration. In the Proxy Service List, click the Web Server Addresses link. Check the following values:

      • Web Server Host Name: If this name has a staging prefix or suffix, remove it.

      • IP addresses in the Web Server List: If the IP addresses in the production area are different from the IP addresses in the staging area, modify the IP addresses to match the production area.

      • Certificates: If you have configured SSL or mutual SSL between the proxy service and the Web servers, configure the Web Server Trusted Root and SSL Mutual Certificate options. The export and import configuration option does not export and import certificates.

    5. Click OK twice.

  2. (Conditional) If you have multiple reverse proxies, repeat Step 1 for each proxy service.

  3. On the Configuration page, click Reverse Proxy / Authentication, then select the Identity Server Cluster configuration.

  4. If you have multiple reverse proxies, verify that the Reverse Proxy value in the Embedded Service Provider section is the reverse proxy you want to use for authentication, then click OK twice.

  5. (Conditional) If the Administration Console already contained some policies, verify that you do not have policies with duplicate names. Click Policies > Policies.

    Policies with duplicate names have Copy-n appended to the end of the name, with n representing a number. If you have duplicates, reconcile them:

    • If they contain the same rules, you need to reconfigure the resources that use one policy to use the other policy before you can delete the duplicate policy.

    • If they contain different rules, rename the duplicate policies.

  6. (Conditional) Apply any policy configuration changes.

  7. Click Access Gateways > Update.

  8. Click Identity Servers > Update.

    If your Identity Server does not prompt you for an update, complete the following steps to trigger the update:

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

    2. Set the Identity Server Cluster field to None, then click OK.

    3. Click Reverse Proxy / Authentication.

    4. Set the Identity Server Cluster field to the correct value, then click OK.

    5. Update the Access Gateway.

    6. Update the Identity Server.

  9. Configure the keystores for the Access Gateway.

    If you have configured the Access Gateway for SSL between the Identity Server and the Access Gateway and between the Access Gateway and the browsers, verify that the trust stores and the keystores contain the correct certificates.

    1. In the Administration Console, click Security > Certificates.

    2. Find the certificate for the Access Gateway.

      The subject name of this certificate should match the DNS name of the Access Gateway. If this certificate is not in the list, you need to create it or import it.

      This certificate should be in use by the ESP Mutual SSL and Proxy Key Store of the Access Gateway.

    3. If the certificate is not in use by the required keystores, select the certificate, then click Actions > Add Certificate to Keystores.

    4. Click the Select Keystore icon, select ESP Mutual SSL and Proxy Key Store of the Access Gateway, then click OK twice.

  10. Configure the trust stores for the Access Gateway.

    1. In the Administration Console, click Security > Certificates > Trusted Roots.

      The trusted root certificate of the CA that signed the Access Gateway certificate needs to be in the NIDP-truststore.

      The trusted root certificate of the CA that signed the Identity Server certificate, needs to be in the ESP Trust Store of the Access Gateway.

    2. If you need to add a trusted root to a trust store, select the trusted root, click Add Trusted Roots to Trust Stores.

    3. Click the Trust Store icon, select the required trust store, then click OK twice.

  11. If you made any keystore or trust store modifications, update the Access Gateway and the Identity Server.

  12. (Optional) Create a cluster configuration and add this server as the primary server.

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 should 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 should 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. To set the date and time for the Linux or Windows Access Gateway Service, use the utilities supplied by the operating system.

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. (Access Gateway Appliance) 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.

  • If you have added an adapter to the machine after installing the Access Gateway, you need to use the New NIC option before it can appear in the adapter list.

    If you have added an adapter to the machine after installing the Access Gateway, you need to use the New NIC option before it can appear in the adapter list.

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.

  5. Click OK.

  6. Configure the Adapter List Options.

    These options let you change settings for the network adapters on the Access Gateway to ensure compatibility with an existing LAN. Modify the default settings only if your LAN requires specialized adapter card changes.

    • Speed: Select Default, 10 MB, 100 MB, or 1000 MB.

    • Duplex: Select Default, Half, or Full.

      IMPORTANT:Some network adapter drivers do not correctly detect duplex settings. This is a general industry problem with Fast Ethernet technology.

      If your Access Gateway isn't performing as expected, check to ensure that the duplex settings for its network adapters match your network configuration. It might be necessary to manually configure the duplex settings on both your Access Gateway and your Ethernet switch or hub.

    • NAT: Select Dynamic or Disabled.

      If the Access Gateway is serving as a router, and your network employs non-unique private IP addresses, you can configure the Access Gateway to provide Network Address Translation (NAT) services.

      For example, if you have a 10.0.0.0 private network on eth0 and a registered public network such as 130.0.0.0 on eth1, the clients on the private network can access the Internet through the Access Gateway, provided that the Dynamic option is selected in the NAT drop-down list for the eth1 adapter.

      The Access Gateway then functions as a network address translator and dynamically maps the private, non-routable 10-net addresses to the registered public address assigned to eth1.

      IMPORTANT:You cannot configure a reverse proxy on an IP address assigned to an adapter that has the Dynamic option set for NAT. NAT and a reverse proxy cannot coexist on the same adapter.

  7. Click OK.

  8. 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. (Access Gateway Appliance) In the Administration Console, click Devices > Access Gateways > Edit > Gateways.

  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. Fill in the following fields:

    Act as Router: Select this option if the Access Gateway functions as the default gateway for clients on the network. If you select this option, you can specify additional gateways.

    Enable Gateway Statistics Monitoring: Select this option if you want to gather statistics and monitor the traffic on the gateways.

  4. 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.

  5. 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.

  6. 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 should 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.

  7. Click OK.

  8. 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. (Access Gateway Appliance) 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. Configure the DNS Cache Settings. These options allow you to control the refresh of DNS information. These are all standard DNS options.

    Negative Lookup: Specifies how long a failed DNS lookup domain name remains in cache. If the Access Gateway cannot resolve a domain name, it stores that information in its cache for the specified amount of time. If the Access Gateway receives requests for that domain name within this period, it sends a “Bad Gateway” error message to the browser and does not resolve the domain name again. Valid field values include 0–3600 seconds. The default is120 seconds.

    Minimum Time To Live per Entry: Specifies the minimum amount of time that DNS entries remain in cache before they expire. This is the minimum value the Access Gateway uses regardless of the value the DNS server returns. Valid field values include 0–3600 seconds. The default is 120 seconds.

    Maximum Time To Live per Entry: Specifies the maximum amount of time that DNS entries remain in cache before they expire. This is the maximum value the Access Gateway uses regardless of the value the DNS server returns. Valid field values include 0–744 hours. The default is 168 hours.

    Maximum Entries: Specifies the maximum number of DNS cache entries. When this number is reached, the Access Gateway deletes old entries to make room for newer ones. Valid field values include 2000–100000. The default is 5000.

    DNS Transport Protocol: Specifies the transport protocol that DNS uses on the network where the Access Gateway is installed. Valid values are UDP and TCP. The default is UDP.

  5. Click OK.

  6. 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 you can configure Access Gateway to use a new IP address, you must first use an operating system utility to add the IP address.

Linux: Start YaST, click Network Devices > Network Card, then select the Traditional Method.

Windows: Access the Control Panel, click Network Connections > Local Area Connection > Properties, then select Internet Protocol (TCP/IP). Click Properties > Advanced.

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, then click OK.

    Access Gateway scans the operating system for its configured IP addresses and adds any new addresses. Any 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.

Adding New Network Interfaces to the Access Gateway Appliance

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

If you add new network interface cards to the Access Gateway Appliance after installation, perform the following steps:

  1. Start YaST, click Network Devices > Network Card, then select the Traditional Method to configure the IP address.

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

  3. On the Server Details page, click New IP, then click OK.

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

  4. Click Access Gateways and then click Edit for the cluster or server that has the new card.

  5. Click Adapter List.

    The newly added network interface is displayed here. Use this page to change the IP address related configuration. Now on, you should not use YaST.

4.2.8 Configuring X-Forwarded-For Headers

X-Forwarded-For headers are used to pass browser ID information along with browser request packets. If the headers are included, Web servers can determine the origin of browser requests they receive. If the headers are not included, browser requests have anonymity.

Deciding whether to enable X-Forwarded-For headers requires that you weigh the desires of browser users to remain anonymous against the desires of Web server owners (e-commerce sites, for example) to collect data about who is accessing their sites.

Access Gateway Appliance: This option is disabled by default.

Access Gateway Service: Apache is configured to always send the X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Server headers. There are no options in the Administration Console to change this behavior.

To enable the X-Forwarded-For header on the Access Gateway Appliance:

  1. In the Administration Console, click Devices > Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service] > HTTP Options > Header Options.

  2. Select the Enable X-Forwarded-For option.

    With this option selected, the proxy service either adds information to an existing X-Forwarded-For or Forwarded-For header, or creates a header if one doesn’t already exist. Leaving the option deselected causes the proxy service to remove X-Forwarded-For headers from any Web requests passing through the proxy service.

  3. Click OK.

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

4.2.9 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. Open /opt/novell/nam/mag/webapps/nesp/WEB-INF/classes/nidpconfig.properties.

  2. Set the IS_DISPLAY_AUTH_DONE_PAGE parameter 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.10 Customizing The Access Gateway

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:

      Linux: /etc/opt/novell/apache2/conf/extra

      Windows: \Program Files\Novell\apache\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:

      Linux: /opt/novell/apache2/share/apache2/error

      Windows: \Program Files\Novell\apache\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:

      Linux: /opt/novell/apache2/share/apache2/error/include

      Windows: \Program Files\Novell\apache\error\include

    2. Open thetop.html page.

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

      <title>Access Manager 4.0<\title>
      
    4. Replace the Access Manager 4.0 string with the content you require.

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

      <img src="NAGErrors/images/Odyssey_LoginHead.gif" alt="" height="80" width="550" border="0">
      
    6. Replace Odyssey_LoginHead.gif 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:

      Linux: /opt/novell/apache2/share/apache2/error/images

      Windows: \Program Files\Novell\apache\error\images

  3. To change the footer of the error page:

    1. Change to the Apache error include directory:

      Linux: /opt/novell/apache2/share/apache2/error/include

      Windows: \Program Files\Novell\apache\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:

      Linux: /opt/novell/apache2/share/apache2/error/images

      Windows: \Program Files\Novell\apache\error\images

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

The err.jsp file will also log the ESP error messages. For more information on customizing the err.jsp page, see Customizing Identity Server Messages. The procedure for customizing is the same but the paths referred to will change for the Access Gateway. Following are the path changes:

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

    • Step 3, path on Linux will be /opt/novell/nam/mag/webapps/nesp/WEB-INF/lib and on Windows /Program Files/Novell/Tomcat/webapps/nesp/WEB-INF/lib/.
    • Step 10, path on Linux will be /opt/novell/nam/mag/webapps/nesp/WEB-INF/classes and on Windows /Program Files/Novell/Tomcat/webapps/nesp/WEB-INF/classes.
    • Step 12, restart Access Gateway /etc/init.d/novell-mag restart.
  • In Customizing Identity Server Messagesthe path for err.jsp in the ESP on Linux will be /opt/novell/nam/mag/webapps/nesp/jsp and on Windows /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. For more information about how to change the authentication proxy, see Changing the Authentication Proxy Service.

  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.jsp file on the Access Gateway. It is located in the following directory:

Linux: /opt/novell/nesp/lib/webapp/jsp

Windows: \Program Files\Novell\Tomcat\webapp\nesp\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.jsp file is called in a frame from the nidp.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.jsp for logos, titles, and colors, see Rebranding the Header.

IMPORTANT:Take a backup of nidp.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.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.

Redirecting to Your Custom Page

One way to provide redirection is to replace the information in the <body> element of the logoutSuccess.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.

IMPORTANT:Take a backup of logoutSuccess.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.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 need to modify the logout button of the applications to use the plogout URL rather that the AGLogout URL (see Customizing Applications to Use the Access Gateway Logout Page). The AGLogout page redirects to the plogout page, which calls the logoutSuccess.jsp. Any parameter added to the AGLogout or plogout URL is saved and passed to the logoutSuccess.jsp file. However, any parameter added to the plogout URL is saved and passed to the logoutSuccess.jsp file.

The parameter passed to the logoutSuccess.jsp file 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, you need to 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 your AGLogout value is the following:

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

You would 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

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.jsp page is not executed with the customizations you have made to the logout page. You will be able to log out of the Access Gateway but the customizations you made are lost.

If the logutSuccess.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.jsp file. Add the below line after the <body> tag in the logoutSuccess.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 the web.xml.

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

    Windows: /Program Files/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 Section 4.2.3, Managing Access Gateways.