IBM Support

XPages DatabaseName URL Parameter Whitelist

Troubleshooting


Problem


In IBM Notes/Domino 9.0.1 FixPack 4 and in releases containing the fix for SPR#MKEE9TKDEM, you may see an error page with the following error message:

CLFAD0382E: The databaseName URL parameter value is not one of the allowed database names. The parameter is &databaseName=otherserver!!app.nsf. The allowed names are configured in the option xsp.data.domino.param.databaseName.whitelist.

This would occur when you open an XPage with a URL containing a remote databaseName, like the following examples:

http ://servername.example.com/discussion.nsf/topicThread.xsp?databaseName=otherserver!!discussion_data.nsf&documentId=2924D3C6A80C523280257DFD005C35A0&action=openDocument

http ://servername.example.com/discussion.nsf/topicThread.xsp?databaseName=CN=otherserver/O=acme!!discussion_data.nsf&documentId=2924D3C6A80C523280257DFD005C35A0&action=editDocument

http ://servername.example.com/discussion.nsf/allDocuments.xsp?search=agenda&databaseName=otherserver!!discussion_data.nsf

There has been a change in the XPages default behavior, that now requires that the allowable databaseNames be configured in a whitelist. The white list is an option that lists allowed databaseNames. Where the whitelist has not been configured, the error above will occur for remote applications (i.e., applications that are not on the current server). There is an option to revert to the previous behavior but there are security implications associated with that decision.

The reason for this change is because of security concerns around malicious users causing the server to run slowly in a Denial Of Service attack. A malicious browser user can use a URL to point the XPages application to read and write the data from any application on the internet or network. The read will be successful if the user currently logged in has access to the application, or especially if the application allows anonymous access.

These type of malicious browser requests that cause the application to read from remote servers would be slow-running. That could cause a degradation in the performance of the server running the XPages application. A malicious user can then cause the server to behave slowly for other users of the server. That can be used as a Denial Of Service (DOS) attack where the server becomes unavailable or less available to the normal users.

Only applications that use the databaseName URL parameter will be effected by these changes, but the parameter is used by default, unless explicitly set to ignore. In XPages, the Domino Document (xp:dominoDocument) and Domino View (xp:dominoView) data sources read certain parameters from the URL and apply those parameters to the data source. For example, the Domino Document data source will read a URL parameter named "documentId" and then use that as the document that should be displayed. Both of the data sources support reading the parameter "databaseName". When this is absent, the document or view entries are read from the current application or from the application configured in the XPage source. When the "databaseName" URL parameter is present, the documents are instead read from the application specified in the parameter. The data sources can be configured in the XPage source with the property ignoreRequestParams="true", which means that the parameters are not read from the URL, but that is not the default behavior.


Overview of the new options

With this SPR fix, there are 3 new options that can be configured in the application xsp.properties file (the Xsp Properties editor in Domino Designer) or in the server-wide xsp.properties file (<domino-data>/properties/xsp.properties). These options are the following:

xsp.data.domino.ignoreRequestParams = false
xsp.data.domino.param.databaseName.usage= whitelist | apply | ignore | error
xsp.data.domino.param.databaseName.whitelist=<currentServer>!!<anyApplication>, otherServer!!app.nsf, otherServer!!app2.nsf,

Also with this fix, the default behavior has changed. Previously the default behavior that occurred was like when the xsp.properties file contained the following:

xsp.data.domino.param.databaseName.usage= apply

With the old behavior, any databaseName parameter in the URL was applied to the data source.

The new default behavior that occurs is as if the xsp.properties file contained the following:

xsp.data.domino.param.databaseName.usage= whitelist
xsp.data.domino.param.databaseName.whitelist=<currentServer>!!<anyApplication>

What this means is that the new behavior applies only databaseNames that match a whitelist entry, with the default whitelist allowing any application on the current server. Hence, it gives an error when referencing applications that are on other servers.


New ignore option

The new ignore option is the following:

xsp.data.domino.ignoreRequestParams = false

The option defaults to false. There is no change to the default behavior for this option. When set to true, it will cause every xp:dominoDocument and xp:dominoView data source in the application to ignore all request parameters in the URL. As a result, none of the parameters are automatically applied. It is not recommended that this option be set on existing application, as it would require thorough re-testing of the application to find any functionality that is broken by the changed behavior. In particular, many pages depend on the documentId parameter in the URL and would no longer function if the documentId parameter were ignored.

For new applications, it may be useful to set this option so that the URL parameters are never automatically applied. Instead, you could use the XPage source to programmatically apply only those parameters that the XPage is explicitly supporting.


New usage option

The new usage option is:

xsp.data.domino.param.databaseName.usage= whitelist | apply | ignore | error

where you would set the option to one of these available values:

xsp.data.domino.param.databaseName.usage= whitelist
xsp.data.domino.param.databaseName.usage= apply
xsp.data.domino.param.databaseName.usage= ignore
xsp.data.domino.param.databaseName.usage= error

When the option is absent, the default behavior is to act as if it were set to "whitelist".

When the option is set to "apply", then the databaseName from the URL is applied to the data sources, without any whitelist validation of the databaseName. This was the old default behavior before this SPR fix was applied.

When the option is set to "ignore", then the databaseName parameter from the URL is not applied to the data sources. The other URL parameters will still be applied. You would use this option if the XPages application is not intended to be used to access data in other applications.

When the option is set to "error", then the presence of databaseName parameter on the URL will cause an error page when the XPage contains some data source. The error page text is like so:

CLFAD0383E: The databaseName URL parameter cannot be used in this application. The parameter is &databaseName=otherserver!!app.nsf. It is disallowed by the application option xsp.data.domino.param.databaseName.usage=error.

You would use that option if the application was previously designed to use the databaseName parameter from the URL but is being redesigned to configure the databaseName in the XPage or programmatically. You can customize the error page by overriding the default error page with custom error page like that provided in footnote [1].

When the option is set to "whitelist" or when the option is absent, then there is a whitelist of allowed databaseNames; either as configured in the whitelist option or the default whitelist. When the URL parameter databaseName matches one of the whitelist entries, then that databaseName is applied, and the document is read from that application.

When the URL parameter databaseName does not match any of the whitelist entries, then an error occurs like the following:

CLFAD0382E: The databaseName URL parameter value is not one of the allowed database names. The parameter is &databaseName=otherserver!!app.nsf. The allowed names are configured in the option xsp.data.domino.param.databaseName.whitelist.

Again, you can customize the error page as described in footnote [1].

You can set the option to "whitelist" when the application is expected to read data from some other application. If the application should only read data from within the current application, you use the value "ignore" or "error", rather than using "whitelist". If the application should only read data from certain other applications, then you list each of those applications in the whitelist option. If the application should only read data from certain servers, then you list those servers in the whitelist using the syntax discussed below.


New whitelist option

The new whitelist option looks like the following:

xsp.data.domino.param.databaseName.whitelist=<currentServer>!!dataApp.nsf, otherDataApp.nsf, otherServer!!app.nsf, otherServer!!app2.nsf, anotherServer!!<anyApplication>

The default value when the option is absent is the following:

xsp.data.domino.param.databaseName.whitelist=<currentServer>!!<anyApplication>

This option applies when the ignore option above is absent or set to false, and when the usage option is absent or set to "whitelist". The whitelist option is not used when the usage option is set to "apply" "ignore" or "error".

The whitelist value is a comma-separated list of possible databaseName values, with added support for the aliases "<currentServer>" and "<anyApplication>". The individual entries are in the format "serverName!!applicationName". If the "!!" separator is absent then the value is treated as an application name, and the server is the current server. For server names other than the current server, the server name comparison is an exact string comparison to the databaseName URL parameter.

For example, for you to allow all of the following URL parameters:

&databaseName=CN=dominoServer2/O=acme!!app.nsf
&databaseName=dominoServer2!!app.nsf
&databaseName=dominoServer2/acme!!app.nsf

you would need 3 separate entries in the whitelist, like so:

xsp.data.domino.param.databaseName.whitelist=CN=dominoServer2/O=acme!!app.nsf,dominoServer2!!app.nsf,dominoServer2/acme!!app.nsf

That means that you may need to list each of the server name formats separately. Note that the XPages xp:viewPanel control will generate URLs in the canonical format (&databaseName=CN=dominoServer2/O=acme!!app.nsf), while the xe:dataView control will generate URLs in the common name format (&databaseName=dominoServer2!!app.nsf). Applications may also contain computed URLs with the databaseName in any format.

For the current server, the "<currentServer>" alias may be used in the whitelist. It will match a URL server name that is empty (&databaseName=app.nsf or &databaseName=!!app.nsf), or will match the server name in one of the 3 supported name formats. The supported formats are the canonical server name (&databaseName=CN=dominoServer2/O=acme!!app.nsf), the common name (&databaseName=dominoServer2!!app.nsf) and the abbreviated name (&databaseName=dominoServer2/acme!!app.nsf).

It will not match other name formats; for example there's no support for the server IP address (&databaseName=127.0.0.1!!app.nsf) even though that databaseName would be successfully accessed if added to the whitelist.

If the <currentServer>!!<anyApplication> entry is absent from the whitelist, then databaseName URL parameters that point to an application on the current server will be rejected, unless explicitly enabled by other entries in the whitelist.

When the whitelist entry application name contains the value <anyApplication> then there is no validation of the application name found in the URL parameter - only the server name part will be validated.

When the whitelist entry application name is any value other than "<anyApplication>", then the entry application name will be compared to the application name part of the databaseName URL parameter. The comparison is an exact string comparison, that is, it does not use case-insensitive comparison. So if you have URLs containing values like:

&databaseName=SomeApp.nsf
&databaseName=someapp.nsf

On case-insensitive Windows servers they would resolve to the same application, but you would need 2 separate entries in the whitelist to allow both URL formats. For example:

xsp.data.domino.param.databaseName.whitelist=SomeApp.nsf, someapp.nsf

If a whitelist entry has an empty application name (...whitelist=servername!!,), then that whitelist entry will be treated as if it were not present in the whitelist. To allow references to any application on the server, use the "<anyApplication>" alias rather than using an empty application name.
Empty whitelist entries (...whitelist=,,,,app.nsf) are treated as if they were not present in the whitelist.
If no value is provided for the whitelist, or if all the entries are empty, then the default whitelist value is used (...whitelist=<currentServer>!!<anyApplication>). If you had intended to disallow all databaseNames, then set the usage option to "error" instead.

The validation of the URL parameter databaseName against the whitelist occurs when copying the databaseName from the URL into the data source. So if the data source is configured in the XPage source to have ignoreRequestParams="true", then the whitelist validation does not occur. Likewise, if the databaseName is configured in the XPage source instead of in a URL parameter, then there is no validation of the databaseName from the XPage source against the whitelist.

If the whitelist validation is not suitable for your particular use-case (for example, if you need to read the allowed databaseNames from a document rather than hard-coding them in the application xsp.properties file) then you would set the usage option to "ignore", so that the databaseName URL parameter is not automatically applied, and you would instead programmatically compute the databaseName in the XPage source. Your computation can refer to the URL parameter as param.databaseName, and you would use server-side JavaScript to validate that the databaseName is one of the expected applications.


Custom error page for CLFAD0382E and CLFAD0383E errors

Footnote[1]: You can customize the error page for the various use cases just described by using the error information in the new FacesExceptionEx2 class. Configure the custom error page for the application, as described in the following topic: http://www-10.lotus.com/ldd/ddwiki.nsf/dx/error-management-in-xpages.htm#XPages+error+pages

To get the information about the error, see this example error page:
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"&gt;
    <xp:label id="label1">
        <xp:this.value><![CDATA[#{javascript://
var ex = requestScope.error;
if( ex.getClass().getName().equals('com.ibm.xsp.FacesExceptionEx2') ){
    var errorPrefix = ex.getErrorCodePrefix();
    var errorNumber = ex.getErrorCodeNumber();
    var errorParamsArr = ex.getErrorParams();
    if( 'CLFAD'.equals(errorPrefix) && 382 == errorNumber ){
        // ex.getMessage() is like so:
        // CLFAD0382E: The databaseName URL parameter value is not one of the allowed database names. The parameter is &databaseName=servername!!app.nsf. The allowed names are configured in the option xsp.data.domino.param.databaseName.whitelist.
        // CLFAD0382E: The databaseName URL parameter value is not one of the allowed database names. The parameter is {0}. The allowed names are configured in the option {1}.
        // In the getErrorParams() array the values are:
        // [0] is like "&databaseName=servername!!app.nsf",
        // [1] is "xsp.data.domino.param.databaseName.whitelist",
        // [2] is like "servername!!app.nsf"
        return 'Please update your bookmarks. The URL parameter '+errorParamsArr[0]+' is not allowed. Only the value &databaseName=server2!!myapp.nsf is allowed.';
    }
    if( 'CLFAD'.equals(errorPrefix) && 383 == errorNumber ){
        // ex.getMessage() is like so:
        // CLFAD0383E: The databaseName URL parameter cannot be used in this application. The parameter is &databaseName=servername!!app.nsf. It is disallowed by the application option xsp.data.domino.param.databaseName.usage=error.
        // CLFAD0383E: The databaseName URL parameter cannot be used in this application. The parameter is {0}. It is disallowed by the application option {1}.
        // In the getErrorParams() array the values are:
        // [0] is like "&databaseName=servername!!app.nsf",
        // [1] is "xsp.data.domino.param.databaseName.usage=error",
        // [2] is like "servername!!app.nsf"
        return 'Please update your bookmarks. The URL should no longer contain the URL parameter: '+errorParamsArr[0];
    }
}
return 'A problem occurred.';
//}]]></xp:this.value>
    </xp:label>
</xp:view>

Internal Use Only

The XPages &databaseName URL parameter is now validated against a whitelist, giving an error if the specified databaseName is not allowed. This change is to address a security concern.

[{"Product":{"code":"SSVRGU","label":"IBM Domino Designer"},"Business Unit":{"code":"BU003","label":"Collaboration Solutions"},"Component":"XPages","Platform":[{"code":"PF033","label":"Windows"}],"Version":"9.0.1","Edition":""}]

Document Information

Modified date:
21 June 2018

UID

swg21960372