2.7.3 Managing Reverse Proxies and Authentication

A reverse proxy acts as the front end to your web servers on your Internet or intranet and off-loads frequent requests, thereby freeing up bandwidth. The proxy also increases security because the IP addresses of your web servers are hidden from the Internet.

To create a reverse proxy, you must create at least one proxy service with a protected resource. You must supply a name for each of these components. Reverse proxy names and proxy service names must be unique to Access Gateway because they are configured for global services such as IP addresses and TCP ports. For example, if you have a reverse proxy named products and another reverse proxy named library, only one of these reverse proxies can have a proxy service named corporate.

Protected resource names need to be unique to the proxy service, but they don’t need to be unique to Access Gateway because they are always accessed through their proxy service. For example, if you have a proxy service named account and a proxy service named sales, they both can have a protected resource named public.

The first reverse proxy and proxy service you create are automatically assigned to be the authenticating proxy.

  1. Click Devices > Access Gateways > Edit.

    The Edit link is either for a single Access Gateway or for a cluster of Access Gateways.

  2. Click Reverse Proxy / Authentication.

  3. Configure the authentication settings:

    Identity Server Cluster: Specifies Identity Server you want Access Gateway to trust for authentication. Select the configuration you have assigned to Identity Server.

    Whenever an Identity Server is assigned to a new trust relationship, Identity Server needs to be updated. This process is explained following the step that saves this configuration setting (see Step 5 and Step 6).

  4. (Conditional) If you have already created at least one reverse proxy, you can view the Embedded Service Provider options and configure some of them:

    Reverse Proxy: Specifies which proxy service is used for authentication. If you have configured only one proxy service, only one appears in the list and it is selected. If you change the reverse proxy that is used for authentication, certificates must be updated to match this new configuration.

    Metadata URL: Displays the location of the metadata.

    Health-Check URL: Displays the location of the health check.

    Logout URL: Displays the URL that you need to use for logging users out of protected resources. This value is empty until you have created at least one reverse proxy and it has been assigned to be used for authentication. 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.

    If any of your protected resources have a logout page or button, you need to redirect the user’s logout request to the page specified by this URL. 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.

    ESP Global Options: Allows you to configure global options for ESP. For more information, see Configuring ESP Global Options.

    Auto-Import Identity Server Configuration Trusted Root: Allows you to import the public key from Identity Server cluster into the trust store of the Embedded Service Provider. This sets up a trusted SSL relationship between the Embedded Service Provider and Identity Server. This option is not available until you have selected an Identity Server Cluster and have configured the use of SSL on the Embedded Service Provider of the reverse proxy that is performing authentication (see the Enable SSL with Embedded Service Provider option on the Reverse Proxy page).

    If Identity Server cluster is using a certificate created by the Access Manager certificate authority (CA), the public key is automatically added to this trust store, so you do not need to use this option. If Identity Server cluster is using a certificate created by an external CA, you need to use this option to import the public key into the trust store.

  5. (Optional) Configure the proxy settings:

    Behind Third Party SSL Terminator: Enable this option if you have installed an SSL terminator between the users and Access Gateway. This allows the terminator to handle the SSL traffic between the browsers and the terminator. The terminator and Access Gateway can use HTTP for their communication. For configuration tips, see Using an SSL Terminator.

    Enable Via Header: Enables the sending of the Via header to the web server. The Via header contains the DNS name of Access Gateway and a device ID. It has the following format:

    Via: 1.1 www.mymag.com (Access Gateway-ag-BFBA9849520DB63B-5)

    Deselect this option when your web server does not need this information or does not know what to do with it.

  6. (Optional) Configure the cookie settings:

    For more information, see Section 13.6, Enabling Secure Cookies.

    Enable Secure Cookies: Enabling this option sets secure keyword on HTTPS request. If you have enabled the Behind Third Party SSL Terminator option and also enabled the Enable Secure Cookies option, the secure keyword on HTTP and HTTPS requests are set.

    WARNING:Do not enable the Enable Secure Cookies option if you have both HTTP and HTTPS reverse proxies. The HTTP services become unavailable because authentication requests to the non-HTTP services fail.

    Force HTTP-Only Cookie: Forces Access Gateway to set the HttpOnly keyword, which prevent scripts from accessing the cookie. This helps protect browsers from cross-site scripting vulnerabilities that allow malicious sites to grab cookies from a vulnerable site. The goal of such attacks might be to perform session fixation or to impersonate the valid user.

    IMPORTANT:The HttpOnly keyword can prevent applets from loading and can interfere with JavaScript. Do not enable this option if you have Access Gateway protecting applications that download applets or use JavaScript.

  7. To create a proxy service, continue with Creating a Proxy Service.

Creating a Proxy Service

  1. Click Devices > Access Gateways > Edit > Reverse Proxy / Authentication.

  2. In the Reverse Proxy List, click New, specify a display name for the reverse proxy, then click OK.

  3. Enable a listening address.

    Cluster Member: (Available only if Access Gateway is a member of a cluster.) Select the server you want to configure from the list of servers. The Listening Address(es) and TCP Listen Options modifications apply to the selected server. Modifications made to any other options on the page apply to all servers in the cluster.

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

    If Access Gateway is in a cluster, you must select a listening address for each cluster member.

    TCP Listen Options: Provides options for configuring how requests are handled between the reverse proxy and the client browsers. You cannot set up the listening options until you create and configure a proxy service. For information about these options, see Configuring TCP Listen Options for Clients.

  4. Configure the listening ports:

    Non-Secure Port: Specifies the port on which to listen for HTTP requests; the default port for HTTP is 80. Depending upon your configuration, this port might also handle other tasks. These tasks are listed to the right of the text box.

    Secure Port: Specifies the port on which to listen for HTTPS requests; the default port for HTTPS is 443. For information about the SSL options, see Enabling SSL Communication.

  5. In the Proxy Service List section, click New.

    The first proxy service of a reverse proxy is considered the master (or parent) proxy. Subsequent proxy services can use domain-based, path-based, or virtual multi-homing, relative to the published DNS name of the master proxy service. If you are creating a second proxy service for a reverse proxy, see Using Multi-Homing to Access Multiple Resources.

  6. Specify the following details:

    Proxy Service Name: Specify a display name for the proxy service, which Administration Console uses for its interfaces.

    Published DNS Name: Specify the DNS name you want the public to use to access your site. This DNS name must resolve to the IP address you set up as the listening address.

    Web Server IP Address: Specify the IP address of the web server you want this proxy service to manage. You can specify additional web server IP addresses by clicking the Web Server Addresses link when you have finished creating the proxy service.

    Host Header: Specify whether the HTTP header must contain the name of the back-end web server (Web Server Host Name option) or whether the HTTP header must contain the published DNS name (the Forward Received Host Name option).

    Web Server Host Name: Specify the DNS name of the web server that Access Gateway must forward to the web server. If you have set up a DNS name for the web server and it requires its DNS name in the HTTP header, specify that name in this field. If the web server has absolute links referencing its DNS name, include this name in this field. If you selected Forward Received Host Name, this option is not available.

    NOTE:For iChain administrators, the Web Server Host Name is the alternate hostname when configuring a web server accelerator.

  7. Click OK.

  8. Continue with Configuring a Proxy Service or select one of the following tasks:

Configuring a Proxy Service

A reverse proxy can have multiple proxy services, and each proxy service can protect multiple resources. You can modify the following features of the proxy service:

  • Web servers

  • HTML rewriting

  • Logging

  • Protected resources

  • Caching

  1. To configure a proxy service, click Access Gateways > Edit > [Name of Reverse Proxy] > [Name of Proxy Service].

  2. Specify the following details:

    Published DNS Name: Displays the value that users are currently using to access this proxy service. This DNS name must resolve to the IP address you set up as a listening address on Access Gateway. You must modify this field only if you have modified the DNS name you want users to use to access this resource.

    This name determines the possible values of the Cookie Domain.

    Description: (Optional). Provides a field where you can describe the purpose of this proxy service or specify any other pertinent information.

    Cookie Domain: Specifies the domain for which the cookie is valid.

    If one proxy service has a DNS name of www.support.novell.com and the second proxy service has a DNS name of www.developernet.novell.com, the cookie domains are support.novell.com for the first proxy service and developernet.novell.com for the second proxy service. You can configure them to share the same cookie domain by selecting novell.com for each proxy service. Single sign-on between the proxy services is simplified when the proxy services share the same cookie domain.

    Enable Advanced Session Assurance: Select this option to enable Advanced Session Assurance at the proxy service level. This configuration works only when the cluster-level Session Assurance is enabled. For more information, see Enabling Advanced Session Assurance at the Proxy Service Resource Level.

    HTTP Options: Allows you to set up custom caching options for this proxy service. See Section 3.5.2, Controlling Browser Caching.

    Advanced Options: Specifies how the proxy service handles specific conditions, such as web server error pages. If similar options are configured globally, the proxy service configuration overwrites the global setting. For information about the proxy service options, see Configuring Advanced Options for a Domain-Based and Path-Based Multi-Homing Proxy Service.

  3. Click OK to save your changes to browser cache.

  4. Click Devices > Access Gateways.

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

    Until this step, nothing has been permanently saved or applied. The Update status pushes the configuration to the server and writes the configuration to the configuration data store. When the update has completed successfully, the server returns the status of Current.

    To save the changes to the configuration store without applying them, do not click Update. Instead, click Edit. On the Configuration page, click OK. The OK button on this pages saves the cached changes to the configuration store. The changes are not applied until you click Update on Access Gateways page.

  6. Update Identity Server to accept the new trusted relationship. Click Identity Servers > Update.

  7. Continue with one of the following.

Modifying the DNS Setting for a Proxy Service

  1. Get the SSL certificate for the new DNS name.

    For more information, see Section 16.0, Creating Certificates.

  2. Click Devices > Access Gateways.

  3. Edit AG-Cluster and click on any reverse proxy listed under Reverse Proxy/Authentication.

  4. Change the Server Certificate to the new one for your new DNS name.

    Ignore any warning displayed about CN name mismatch because the proxy service is not yet updated.

  5. Under the Proxy Service List tab, click the proxy which DNS name you want to modify.

  6. Change the Published DNS Name for the proxy service.

    NOTE:Changing the published DNS name of the master proxy changes Identity Server’s base URL also.

  7. Click OK > OK.

  8. Click Network Settings > Hosts > IP address of your system.

  9. Add the new DNS name in the list of host names.

  10. Click OK.

  11. Go to Access Gateway and click Update All.

  12. When Access Gateway Health turns green, check Identity Server Health and ensure that it is green as well.

Configuring ESP Global Options

When you configure an ESP global option, it gets applied to all Access Gateway ESPs in an Access Gateway cluster.

By default, these options are disabled. To enable these options, you need to remove the pound (#) symbol before it and set a value. After you configure an option, you cannot delete it. However, you can disable it again by adding the pound (#) symbol before it. If you have set a value for an option and want to disable the option, you need to add # before the configured option. After saving the changes, the value for the option is set to the default value. For example, if you have set the value for CLUSTER_COOKIE_DOMAIN as CLUSTER_COOKIE_DOMAIN .example.com, add # before CLUSTER_COOKIE_DOMAIN .example.com. After the changes are applied, the option is set to the default value as #CLUSTER_COOKIE_DOMAIN.

Perform the following steps to configure ESP global options:

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

  2. To activate an ESP global option, remove the # symbol before it, configure the value, save it, and then update Access Gateway. By default, Access Manager displays seven options. You can configure any other options also, if required.

The following table lists the default ESP global options:

ESP Global Option

Description

forceESPSLOHTTP

Set true to enable the front channel logout for Access Gateway initiated logout.

The default value is false.

For more information enabling front channel logout for Access Gateway, see Defining Options for Liberty Identity Provider.

httponlyClusterCookie

Set false to disable the HTTPOnly flags for ESP cluster cookies.

The default value is true.

For example, see Enabling Secure or HTTPOnly Flags for Cluster Cookies.

CACHE_CONTROL_RESPONSE_HEADER_VALUE no-cache,no-store

To enable this option, you need to remove the pound (#) symbol before it and set a value and the server requires you to Update All. If you have set a value for an option and want to disable the option, you need to add # before the configured option and this does not require any update to the server.

Access Manager by default sets Cache-Control header on some URLs. In this scenario, this configuration will not override the default behavior.

CLUSTER_COOKIE_DOMAIN

Set this property to change the Domain attribute for the ESP custer cookie in this format: CLUSTER_COOKIE_DOMAIN .example.com

CLUSTER_COOKIE_PATH

Set this property to change the Path attribute for the ESP custer cookie.

The default value is /nesp.

notifysessionTimetoIDP

Set false to disable sending session timeout message to the remote identity provider.

The default value is true.

For example, see Configuring Liberty or SAML 2.0 Session Timeout.

RENAME_SESSIONID

Set false to prevent changing Access Gateway session ID automatically.

The default value is true.

For example, see Preventing Automatically Changing Session ID in the Securing the ESP Session Cookie on Access Gateway.

IS_DISPLAY_AUTH_DONE_PAGE

Set true to enable Access Gateway to display post-authentication message.

The default value is false.

For example, see Enabling Access Gateway to Display Post-Authentication Message.

SESSION_ASSURANCE_USER AGENT_EXCLUDE_LIST

Specify the user-agent string for that you want to disable the session validation.

For example, see Disabling Advanced Session Assurance for Access Gateway ESP.

SESSION_ASSURANCE_USER_AGENT_REGEX_EXCLUDE_LIST

Specify the user-agent REGEX for that you want to disable the session validation.

For example, see Disabling Advanced Session Assurance for Access Gateway ESP.

SESSION_ASSURANCE_URL_EXCLUDE_LIST

Specify the URL for that you want to disable the session validation.

For example, see Disabling Advanced Session Assurance for Access Gateway ESP.

SESSION_ASSURANCE_URL_REGEX_EXCLUDE_LIST

Specify the URL REGEX for that you want to disable the session validation.

For example, see Disabling Advanced Session Assurance for Access Gateway ESP.

SESSION_ASSURANCE_IDC_COOKIE_GRACEPERIOD

Specify the time in second till which Identity Server accepts the old IDC cookie, after issuing a new cookie. The default value is 15 second.

USE_DEVICE_ID_IN_URN_COOKIE

(Access Manager 5.0 Service Pack 1 and later)

In an Access Manager environment with multiple Identity Servers and Access Gateways, a cluster cookie (UrnNovellNidpClusterMemberId) is automatically set for the serving node of the cluster. When requests come to Identity Server or Embedded Service Provider (ESP), this cookie is used by all nodes of the cluster to perform the proxying, if necessary.

For higher security, enable this property to use hashing for the cookie value.

  • false: The default setting.

  • true: Enables this property for both Identity Server and ESP.

  • ESP: Enables this property for ESP.

To set up this property only for Identity Server, see USE DEVICE ID IN URN COOKIE in Configuring Identity Server Global Options.

NOTE:After configuring an ESP option, you cannot revert it to the previous configuration by clicking Revert in the Cluster Configuration page (Access Gateway > Edit > Revert).