Refresh Authentication
Page 4 of 7

Refresh Authentication Models for Beyond-the-Firewall Systems

For systems in which targets can be deployed outside the corporate firewall, there are two models for refresh authentication:

NOTE: Even when you are using one of the other models described in this section, if user authentication is turned on at the source, refresh requests still need to present a valid user ID and password to get in the system. See Configuring Your System for Successful JDBC Authentication at Refresh Time.

Two-Way SSL Authentication

Cloudscape supports two-way authentication using SSL for refresh authentication. The requirements are:

  • The source database must run in a server framework that supports SSL and https.
  • The source must use the servlet API for refresh requests (described in Configuring Cloudsync for the Servlet API). The server framework must be configured to require two-way authentication for the address at which the Cloudsync servlet (COM.cloudscape.core.ServletHandler) is registered. The documentation for your server framework should describe how to do this if it supports it.

    This solution most likely requires the services of a Public Key Infrastructure (PKI) to manage the storage and verification of certificates from the target. The documentation for your server framework should describe this if it is required.

  • The target database must use its certificate when connecting to the source at refresh time.

    When running in a browser this is handled by using the browser's certificate management.

    If the target database is not running in a browser, it must run in the JVM that uses the JavaSoft JSSE https support. See the JSSE documentation for information on how to do this.

With SSL authentication the source server framework and PKI contain the logic to accept or decline a connection from a target database (or client in SSL terms). Thus a connection to the server framework is successful only if the target's certificate identifies a valid user. By the time a connection is made to the database on behalf of the refresh request, authentication has already taken place.

NOTE: Remember that if user authentication is turned on at the source, refresh requests need to present valid user IDs and passwords. See Configuring Your System for Successful JDBC Authentication at Refresh Time.

Application-Defined Refresh Authentication with Refresh Authentication Callback

Cloudscape allows you to provide your own logic for refresh authentication. To do this, you implement what is called refresh authentication callback by:

This interface requires two methods, preConnect and postConnect.

  • preConnect is called before the refresh request makes its behind-the-scenes JDBC connection request. Typically, you would set user and password properties and add them to the target's connection attributes so that the JDBC connection request will be successful (if user authentication is turned on).

    This method does not have access to the source database, but it does have access to a target's connection attributes as well as all the information available from the target description (see Getting Information About the Target at the Source).

    You can implement the authentication logic in this method if access to the source database is not required. If the target is not valid, the method should throw an SQLException. Throwing an exception aborts the refresh attempt.

  • postConnect is called immediately after the refresh makes its behind-the-scenes JDBC connection. In this method, you implement the logic that determines whether the the target is valid.

    This method has access to the source database and to a target's connection attributes as well as all the information available from the target description (see Getting Information About the Target at the Source).

    If the target is not valid, the method should throw an SQLException. Throwing an exception aborts the refresh attempt.

NOTE: Typically you would use these methods only for refresh authentication. However, it is possible to use these methods for other purposes such as refresh logging or "refresh triggers".

Configuring Your System for Successful JDBC Authentication at Refresh Time

Even when you are using one of the alternate authentication schemes for refresh authentication, if standard database authentication is turned on, the source database requires that targets present a valid source user ID and password for the behind-the-scenes JDBC connection request. In such cases, you do not want to expose these user names and passwords to the targets. Instead, you want to create a single guest-style user ID (creating user IDs is described in the Cloudscape Developer's Guide) and assign it to targets as described below.

Assigning a Single User ID to Targets

Cloudscape allows you to configure your system so that targets succeed in the JDBC authentication by providing you a way to assign a single guest-style user name to targets at the source or server framework (and bypassing the targets). You do this by indirectly setting a property called user that will be part of the target's connection attributes (see Target Connection Attributes). You can set the property user in one of the following ways:

  • You can set the property user in the preConnect method of the refresh authentication callback class (see The Refresh Authentication Callback Class). This property is added to the target's connection attributes, which are checked by the source when the refresh attempts the connection.
  • You can set the property user as a startup parameter to the servlet COM.cloudscape.core.ServletHandler when your system is configured to use the servlet API for refreshes. This property is added to the target's connection attributes, which are checked by the source when the refresh attempts the connection.
  • You can set the property cloudscape.database.sourceUser property at the source. When conditions are met (see The user Property: Reference), the value of this property indirectly sets the property user for targets' connection attributes.

Setting a Password

  • You can set the property password in the preConnect method of the refresh authentication callback class (see The Refresh Authentication Callback Class). This property is added to the target's connection attributes, which are checked by the source when the refresh attempts the connection.
  • You can set the property password as a startup parameter to the servlet COM.cloudscape.core.ServletHandler when your system is configured to use the servlet API for refreshes. This property is added to the target's connection attributes, which are checked by the source when the refresh attempts the connection.
  • In the target's REFRESH properties (it may be okay to expose only a password to the target if you do not expose the user ID).