4.4 Advanced Access Gateway Options

4.4.1 Configuring the Global Advanced Options

The following settings apply to all reverse proxies, unless the option is overwritten by an advance proxy service setting (see Section 4.4.2, Configuring the Advanced Options for a Domain-Based and Path-Based Multi-Homing Proxy Service). The advanced options are disabled by default and will be enabled when they are added.

Advanced Access Gateway Options

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

  2. To activate these options, configure the value, save your changes, then update the Access Gateway. To deactivate these options, add the pound (#) symbol.

The following table lists the advanced options along with their descriptions, default values, and examples. Most of the global advanced options are prefixed with NAGGlobalOptions and the domain-based and path-based multi-homing proxy service options have been identified and mentioned below the option name.

Table 4-1 Advanced Access Gateway Options

Advanced Option

Description

NAGGlobalOptions FlushUserCache=on

This is a global advanced option.

Specifies whether cached credential data of the user is updated when the session expires or the user changes an expiring password. This option is equivalent to PasswordMgmt in the 3.1 SP4 Access Gateway Appliance.

  • When this option is on, which is the default setting, the credentials and the Identity Injection data are refreshed.

  • When this option is turned off, the cached user data can become stale.

    For example, if your password management service is a protected resource of the Access Gateway and this option is turned off, every time a user changes an expiring password, the user’s data is not flushed and the Access Gateway continues to use stale data for that user.

NAGGlobalOptions DebugHeaders=on

When this option is enabled, an X-Mag header is added with debug information. The information can be seen in sniffer traces and with plug-ins such as ieHTTPHeaders, Live HTTP Headers, and FireBug. This option should only be enabled when you are working with NetIQ Support and they instruct you to enable the option.

NAGGlobalOptions DebugFormFill=on

This is a global advanced option.

When this option is enabled, additional debug information related to the processing of a Form Fill policy is added to the Apache error log files (error_log file under /var/log/novell-apache2 for Linux and error.log file under \Program Files\Novell\Apache\logs for Windows) and to the X-Mag header in the response to browser. The Form Fill entries generated by this option begin with a FF: marker. For example, Oct 23 12:38:29 mag326 httpd[29345]: [warn] AMEVENTID#36: FF:fillSilent: kfh5ummigbq6uGeneral_SS_non_SS_autosumit_Page_13310, referer: https://www.idp.com:8443/nidp/idff/sso?sid=0 Oct 23 12:38:29 mag326 httpd[29345]: [warn] AMEVENTID#36: FF:fillInplaceSilent: kfh5ummigbq6uGeneral_SS_non_SS_autosumit_Page_13310, referer: https://www.idp.com:8443/nidp/idff/sso?sid=0

NAGGlobalOptions ESP_Busy_Threshold=<value>

This is a global advanced option.

Proxy starts sending errors to the browser if ESP's average response time in the last one minute is more than the specified value (time in milliseconds).

NAGGlobalOptions noTOPR

This is a global advanced option.

Disables the activity based time-out in proxy. The proxy redirects browser requests after soft timeout of configured timeout value.

This option is equivalent to disabletoppr in the 3.1 SP4 Access Gateway Appliance.

NAGGlobalOptions InPlaceSilent=on

This is a global advanced option.

This enables single sign on to certain Web sites that require the login page to remain as is without any modifications to its structure.

If you are using this advanced option for a Form Fill on a page with multiple forms, by default, the first form is posted. If you want to post forms other than the first form, use NAGGlobalOptions InPlaceSilentPolicyDoesSubmit=on. For more information, refer to TID 7011817.

This option is equivalent to .enableInPlaceSilentFill in the 3.1 SP4 Access Gateway Appliance.

NAGGlobalOptions ForceUTF8

This is a global advanced option.

When this file is enabled, the Access Gateway uses the UTF-8 character set to serve the Form Fill page to the browser.

This option is equivalent to forceUTF8Charset in the 3.1 SP4 Access Gateway Appliance.

NAGGlobalOptions AllowMSWebDavMiniRedir

This is a global advanced option.

This file helps the user to disable the following functionality, which is enabled by default. If a Microsoft Network Places client sends an OPTIONS request with MS-WebDAV-MiniRedir useragent to the Access Gateway, then it receives 409 conflict response. The client uses this response to change the user agent to MS Data Access Internet Publishing Provider DAV.

For example, to access Vibe WebDav folders from My Network Places or Map Network Drive on Windows 7, perform the following steps:

  1. Set the advanced option NAGGlobalOptions AllowMSWebDavMiniRedir to on.

  2. On the client server, perform the following steps:

    1. Add the Vibe and Access Manager URLs to the browser’s trusted site and add the certificates to the Trusted Root Certification Authorities.

    2. Restart the client and access Vibe Webdav URLs either by using Add a network location option or Map network drive option.

This option is equivalent to AllowMSWebDavRedir in the 3.1 SP4 Access Gateway Appliance.

NAGGlobalOptions noURLNormalize=on

This is a global advanced option.

When this option is enabled, it disables the URL normalization protection for back-end Web servers. This option resolves issues in serving Web content from Web servers that have double-byte characters such as Japanese language characters.

By default, this option is set to off and URL is normalized before sending it to back end Web server.

NAGAdditionalRewriterScheme webcal://

This is a global advanced option.

When this option is enabled, the rewriter rewrites URLs that have a scheme of webcal://. The default rewriter configuration only rewrites URLs with a scheme of http:// or https://.

NAGGlobalOptions AppendProviderID=on

This is a global advanced option.

When this option is enabled, it displays the ESP Provider ID in the Access Gateway authorization audit logs. This option helps to know the issues related to ESP provider ID in the audit log file.

NAGGlobalOptions InPlaceSilentPolicyDoesSubmit=on

This is a global advanced option.

This option should be used to fill forms with complex JavaScript or VBScripts.

This option is equivalent to .enableInPlaceSilentFillNew in the 3.1 SP4 Access Gateway Appliance.

NAGGlobalOptions NAGErrorOnIPMismatch=off

This is a global advanced option.

If the value for this option is set to off, the Access Gateway does not perform the IP address check on incoming session cookies. Use this in a setup where two L4 switches are configured in parallel and the browser requests are bounced between these L4 switches.

This option is equivalent to .lagdisableAuthIPCheck in the 3.1 SP4 Access Gateway Appliance.

For example, if multiple back-end Web servers are accelerated by the Access Gateway, some users complain that they are not able to complete logging in. When they access the protected resources, they are redirected to the Identity Server for authentication, but they are not redirected to the original URL.

If multiple paths (at the network level) exist between a browser and the Access Gateway and proxies or NAT devices exist on these paths, it is possible that the source IP address of the incoming requests into the Access Gateway might change. For example, assume that user A connects to an ISP. This ISP has multiple transparent proxies in parallel for performance reasons.

User A accesses the Access Gateway for the first time. The request from User A goes through a local transparent proxy TP1, so the incoming IP address of the initial request has that transparent proxy's (TP1) IP address. The Access Gateway session cookie is set and the user is redirected back to the page the user was going to originally.

User A then sends the next request for this original page, but it goes through a different proxy, TP2. The incoming IP address of the request into the Access Gateway is now different than the one that the user used for authentication (TP1 IP address) and the validation fails. The Access Gateway loops as it continues to request the user to send a valid session cookie.

NOTE:On receiving IPC cookie from browser, the Access Gateway checks for the client IP address in the cookie. If the IP address in the cookie and the client IP address from which the request came do not match, Access Gateway displays an error page.

NAGGlobalOptions NAGDisableExternalRewrite=on

This is a global advanced option.

Access Gateway does not insert the path for the links with external published DNS when you enable this option.

This option is equivalent to .disableExternalDNSRewrite in the 3.1 SP4 Access Gateway Appliance.

DisableGWSHealth on

This is a global advanced option.

When this option is enabled, Access Gateway does not check health of the Web server with the back-end server.

This option is equivalent to .disableWSHealth in the 3.1 SP4 Access Gateway Appliance.

NAGIchainCookieVersion on

This is a global advanced option.

When this option is enabled, Access Gateway sends the proxy session cookie to the back-end server as IPCZQX01<clusterid>.

IgnoreDNSServerHealth on

This is a global advanced option.

When this option is used, the Access Gateway does not send the DNS server health status when the Access Gateway health is reported to the Administration Console.

When you set the option to IgnoreDNSServerHealth off <lookupname>, the Access Gateway sends a DNS query with the specified <lookupname>. The Access Gateway sends a successful message to the Administration Console if it connects to the DNS server, else it will send an unable to connect message. By default if you have not specified any option, the Access Gateway sets the option as IgnoreDNSServerHealth off www.novell.com.

This option is equivalent to ignoreDnsServerHealth in the 3.1 SP4 Access Gateway Appliance.

NAGHostOptions primaryWebdav=<path of pbmh service>

This is a global advanced option.

This option enables users who use the Microsoft Network Places client to connect to the WebDAV folders of a SharePoint server when the SharePoint server has been configured as a path-based multi-homing service on the Access Gateway. This should be added to master proxy service Advanced Options whose path based child services accelerates webdav resources with remove path on fill option enabled.

This option is equivalent to .modifyRequestURI in the 3.1 SP4 Access Gateway Appliance.

NAGGlobalOptions NAGRenameCookie=on

This is a global advanced option.

Set this option to off to prevent the session ID from getting changed automatically.By default, this option is set to on

NAGHostOptions mangleCookies=on

This is a proxy option.

This option invalidates the cookies set by the Web server when the user logs out of Access Manager. By default, the Access Gateway does not mangle the cookies that are sent by the Web server.

Proxy mangles the cookies that are sent by the Web server using the user information and sets these mangled cookies at the browser. When a browser sends the mangled cookies to proxy, it de-mangles them using the user information and sends the de-mangled cookies to the Web server. For more information about this option, see Enabling Cookie Mangling.

AGWSMangleCookiePrefix

This is a proxy option.

Use the NAGWSMangleCookiePrefix <AnyString> option to specify the string added to the application cookie after manipulation. For more information about this option, see Enabling Cookie Mangling.

NAGHostOptions webdavPath=/_vti_bin

This is a global advanced option.

This can be added to master proxy service Advanced Options which path based child services with remove path on fill option enabled accelerating webdav resources.

NAGChildOptions WebDav=<path of pbmh service>

This is a global advanced option.

This option can be added to any path based service that accelerates webdav resources with remove path on fill enabled.

This option is equivalent to .modifyRequestURI in the 3.1 SP4 Access Gateway Appliance.

EnableWSHandshake on

This is a global advanced option.

Setup a firewall between the Access Gateway and the back-end Web server. When the Access Gateway performs heartbeat check with a simple TCP connect to the Web server, the Web server may throw a TLS handshake error. This may cause the firewall, after a certain threshold, to block the connection.This option enables the Access Gateway to perform a SSL handshake while performing a heartbeat check on the back-end SSL-enabled Web server so that the Web server does not respond with a TLS handshake error. By default, the Access Gateway performs a simple TCP connect while performing a heartbeat check on the back-end Web server.

NAGGlobalOptions IIRemoveEmptyHeaderValue

This is a global advanced option.

This option enables the Identity Injection policy not to send an empty header with null value when a value is not available. By default, the Access Gateway sends an empty header with a null value if a value is not available.

For example, applications may have a public and a protected resource configured. Both resources may use an identity injection policy such as to inject an USERID. The public resource uses the user name if authenticated. If the user accesses the public resource (before authentication), the Access Gateway sends an empty header variable USERID. Web servers may not handle an empty header and may respond with an error. In such a scenario use the advanced option to stop the Access Gateway from sending an empty header with null value.

DumpHeaders on

DumpHeadersFacility user

This is a global advanced option.

These options ensure that the proxy, logs the user headers to /var/opt/novell/nam/logs/mag/apache2/error_log file for Linux and \ProgramFiles\Novell\Apache\logs\error.log for Windows.

NAGFilteroutUrlForAudit

This option is available for both domain-based and path-based multi-homing proxy services.

You can add this option to proxy service that filters out specific URLs from auditing (URL Accessed). For example, NAGFilteroutUrlForAudit ".*.jpg", and NAGFilteroutUrlForAudit ".*.gif".

FlushUserCache=on

This is a global advanced option.

Specifies whether cached credential data of the user is updated when the session expires or the user changes an expiring password.

  • When this option is on, which is the default setting, the credentials and the Identity Injection data are refreshed.

  • When this option is turned off, the cached user data can become stale.

    For example, if your password management service is a protected resource of the Access Gateway and this option is turned off, every time a user changes an expiring password, the user’s data is not flushed and the Access Gateway continues to use stale data for that user.

SSLProxyVerifyDepth=3

This is a global advanced option.

Specifies how many certificates are in a Web server certificate chain. When you activate the verification of the Web server certificate with the Any in Reverse Proxy Trust Store and the public certificate is part of a chain, you need to specify the number of certificates that are in the certificate chain. For more information about configuring Web servers for SSL, see Section 14.6, Configuring SSL between the Proxy Service and the Web Servers.

  • The default search level that is when the attribute SSLProxyVerifyDepth is commented to1, if the number of certificates in the Web server certificate chain is greater than 1, then the SSLProxyVerifyDepth option should be enabled and should be assigned to the respective value (equal to the number of certificates in the chain).

ProxyErrorOverride

This is a global advanced option.

Allows you to specify which errors you want returned to the browser unchanged by the Gateway Service. The default behavior of the Gateway Service is to replace Web server errors with Gateway Service errors.

However, some applications put more information, such as keys and JavaScript in the message. If this information is critical, specify an override and allow the error message to be returned to the browser without any modifications.

For example, NetStorage requires an override for the 401 error because it includes a key in the 401 error. The portal page for the Novell Open Enterprise Server requires an override for error 403 because it includes JavaScript.

You can use the following syntax to set this option:

  • ProxyErrorOverride on -401 -403:Allows all errors to be changed to Gateway Service errors except errors 401 and 403, which are sent unchanged.

    This syntax allows you to list the few errors you want to forward without change while allowing all the others to be changed to Gateway Service errors.

  • ProxyErrorOverride off +401 +403:Disables the changing of Web server errors to Gateway Service errors except for errors 401 and 403, which are changed to Gateway Service errors.

    Use this option when you have only a few errors that you want changed to Gateway Service errors.

NOTE:Enable the error codes 401 and 403 for override if you are using Identity Manager 4.0 with Role Mapping Administrator.

CacheIgnoreHeaders

This option is available only for domain-based proxy service.

Prevents the Access Gateway from writing any Authorization headers to disk. This option is enabled by default, because writing Authorization headers to disk is a potential security risk. You can allow Authorization headers to be written to disk by placing a pound (#) symbol in front of the option or by setting it to None. For more information about this Apache option, see “CacheIgnoreHeaders Directive”.

NOTE:All the path-based services under the domain-based service will inherit the new value.

CacheMaxFileSize

This option is available only for domain-based proxy service.

Configuring this value in the Advanced Options of a proxy service allows you to set the size of the file that can be stored in the cache. By default the size is set to 5 MB. Add the line CacheMaxFileSize <bytes>, for example, CacheMaxFileSize 99900000.

NOTE:All the path-based services under the domain-based service will inherit the new value.

NAGErrorOnDNSMismatch

This is a global advanced option.

If SSL is not enabled in reverse proxy, an error message stating Host Name Does Not Match is displayed.

NAGChildOptions WebDav=/Path

This option is valid only for path-based multi-homing proxy service.

Allows the proxy service to handle the specified path. Remove the pound (#) symbol and replace /Path with the path you want the proxy service to handle.

SSLHonorCipherOrder

This is a global advanced option.

This option enables you to customize the SSLCipherSuite used by the Access Gateway. This helps you in taking preventive measures when new vulnerabilities are published.

To avoid Browser Exploit Against SSL/TLS (BEAST) attacks, use the advanced option as follows:

SSLHonorCipherOrder on

SSLCipherSuite !aNULL:!eNULL:!EXPORT:!DSS:!DES:RC4-SHA:RC4-MD5:ALL

For more information about the format and set of options you can specify in the value, see OpenSSL documentation.

NAGGlobalOptions onFormFillPolicyRedirUseHttp=on

This is a global advanced option.

This option enables Access Gateway to redirect based on HTTP status code 302 along with the location header when Form Fill policy requires redirect.

By default, Access Gateway uses JavaScript to trigger redirect in Form Fill policy. You can use this advanced option when there are issues with JavaScript redirects.

NAGLAGCompatiability on

This option enables sharing of session information between the 3.1 SP4 Access Gateway Appliance and the 4.0 Access Gateway Appliance during the process of migration.

This option is added by default during the process of migration to ensure communication between the two appliances. You can disable or remove this option after the migration is complete.

ProxyPassIgnorePathCase on

Use this option to make the path-based multi-homing path URL case-insensitive. For example, if you have set up a path based proxy /profile in Administration Console and the end user wants to access the URL https://www.lagssl.com/Profile/Security/login.aspx and not https://www.lagssl.com/profile/Security/login.aspx. By default url path is case sensitive.

NAGPostParkingSizeInKiloBytes

This option allows you to change the post data parking size limit if an error occurs after you post large data (more than 56 KiloBytes in size) after a session timeout.

NAGSendURLinErrorResponses on

This option will not include a href when you access a protected resource and a 302 redirect occurs.

SSLProtocol

This option is supported by the Access Gateway when listening as a server to clients (typically browsers). This directive specifies SSL protocols for mod_ssl to use when establishing the server environment. Clients can only connect with one of the specified protocols. The accepted values are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and all of these.

The syntax for this is SSLProtocol [+-]protocol. For example, SSLProtocol +SSLv3. For more information about configuring the SSL versions, see Apache documentation.

SSLProxyProtocol

This option is supported by the Access Gateway when listening as a server to clients (typically browsers). This directive specifies SSL protocols for mod_ssl to use when establishing a proxy connection in the server environment. Proxies can only connect with one of the specified protocols. The accepted values are SSLv3, TLSv1, TLSv1.1, TLSv1.2 and all of these.

The syntax for this is SSLProxyProtocol [+-]protocol. For example, SSLProxyProtocol +SSLv3. For more information about configuring the SSL versions, see Apache documentation.

NAGSessionKey Default

This is a global advanced option.

For additional security in case of cross-domain authentication, the Access Gateway session Cookie is encrypted before sending it as a URL query parameter.

For example:

In earlier releases of Access Manager, the URL is: https://novell.blr.com:9443/ -CIPCZQX03218a425f=01000300a463892f582b51722510f334a4223149

In Access Manager 4.1, the URL is: https://novell.blr.com:9443/%20-CECCjdOOBPIqZZNtF+dRlAyDfTFvOPwnO0xzOQTcnrubNzJ6GFe6FF8dWRzzg7RY9iZJYxNLaU80KnJOoqtqf6u2g==

This advanced option NAGSessionKey can be used to specify the password as per the administrator's needs. Passwords with more characters increase the strength of the password and therefore leads to better security.

For example: NAGSessionKey NAM-CROSS-DOMAIN-SESSION-KEY-ENCRYPTION-PASSWORD.

By default, the password is set to "default".

For Windows: SSLProxyCACertificateFile "C:\ProgramFiles\Novell\apache\cacerts\myserver.pem"

For Linux: SSLProxyCACertificateFile /opt/novell/apache2/cacerts/myserver.pem.

This is a service level advanced option.

This option prevents failure in SSL connection between Access Gateway and webserver, when a self-signed certificate is used. To prevent this, import the webserver certificates to the proxy trust store. After importing, the webserver certificates, use this advanced option.

NAGAddProxyHeader on

This is a service level advanced option.

When this option is set to off, Access Gateway will not send the X-Forwarded Headers to the back-end web server.

By default, this option is set to on.

Options to Clean Up Thick Client State At Browser

Currently, when the idle timeout is detected by the Access Gateway, the user is redirected to the Identity server for authentication. If the content type and url pattern used by the client (as defined in the advanced options NAGUrlPattern and NAGContentType), the user should be redirected to a pre-defined timeout as defined in the NAGAuthFrontChannel advanced option.The redirected URL will also have additional information like the ESP login URL, the contract name as well as the landing page URL as defined in the advanced options. The following advanced options must be used together to clean up the thick client.

Advanced Option

Description

NAGLauncher

URL that launches the client.

NAGUrlPattern /messagebroker/*

URL pattern that identifies if a specific request came from a client.

NAGContentType application/x-amf

Content type in the Request header that is used to identify if the request is a client.

NAGAuthBackChannel /namtimeout/timeoutamf

Timeout handler on the server.

NAGAuthFrontChannel

Timeout handler on the server which includes the published DNS name of the server.

Enabling Cookie Mangling

When you log out of Access Manager, the Access Manager session cookies will be invalidated on all Identity and Access Gateway Servers. However, the application session cookie is left unchanged on both the browser and the origin Web server. If a different user authenticates to Access Manager again on the same browser and accesses the proxied Web server, the browser may resume the previously established HTTP session with the Web server so that the new user inherits the old logged out users session. The Cookie Mangling feature in Access Gateway prevents this scenario from occurring by manipulating the application cookies set by the Web servers, and invalidating these cookies when the user logs out of Access Manager.

The two advanced Access Gateway options required to enable this functionality are the NAGHostOptions mangleCookies and NAGWSMangleCookiePrefix. By default, the option NAGHostOptions mangleCookies is set to Off.

To enable this feature, add the options, NAGHostOptions mangleCookies=on and NAGWSMangleCookiePrefix <AnyString> in the Global Advanced Option.

Use the NAGWSMangleCookiePrefix <AnyString> option to specify the string added to the application cookie after manipulation. You can replace <AnyString> with a string of your choice. For example, adding the NAGWSMangleCookiePrefix AGMANGLE results in the Set-Cookie: AGMANGLEa50b_DzkN=5a8G0 application level cookie set in the browser.

URL Attribute Filter

This feature lets you define filtering options for each proxy service. It helps in filtering out specified URLs from the ones audited as part of the URL Accessed audit event. These filtered out URLs will not be displayed in the Audit Server. This is helpful where auditing every URL is not required and may increase the load on the Audit Server. Unnecessary URLs for example, public images, public javascripts, css and favicons can be safely ignored from auditing. The option to set this feature is NAGFilteroutUrlForAudit <regular expression>. This option should be added to the Advanced options section of each service. The regular expression is standard perl based regular expressions. For more information, see Regular Expressions.

Each URL (path?querystring) is matched against this expression. If the match is successful, the URL will not be audited for URL access. For example, NAGFilteroutUrlForAudit ".*.jpg" and NAGFilteroutUrlForAudit ".*.gif". If these options are added to a service, all the *.jpg and *.gif files accessed will not be audited under the 'URL Accessed' audit event.

NOTE:If you enable 'URL Accessed' audit events in the Access Gateway, it can overload the Audit subsystem if the requests sent to the Gateway per second is high. There maybe a delay in Web pages getting loaded. NetIQ recommends to use the http common/extended logging option for this purpose.

4.4.2 Configuring the Advanced Options for a Domain-Based and Path-Based Multi-Homing Proxy Service

The following procedure helps you configure the advanced options for domain-based and path-based multi-homing proxy service of an Access Gateway.

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

  2. Configure the advanced option by removing the pound(#) symbol. To disable an option, add the # symbol in front of the option, save your changes, then update the Access Gateway.