Establishing a Connection
Creating a JDBC Data Source
You can create a JDBC data source to connect from your Java application. Creating a JDBC data source based on the CData JDBC Driver for Domino consists of three basic steps:
- Add the driver JAR file to the classpath. The JAR file is located in the lib subfolder of the installation directory. Note that the .lic file must be located in the same folder as the JAR file.
- Provide the driver class. For example:
cdata.jdbc.domino.DominoDriver
- Provide the JDBC URL. For example:
jdbc:domino:Server=https://domino.corp.com;Database=names.nsf;Port=3002;SSLClientCertType=PEMKEY_FILE;SSLClientCert=full_path_of_certificate.pem;SSLServerCert=* or jdbc:cdata:domino:Server=https://domino.corp.com;Database=names.nsf;Port=3002;SSLClientCertType=PEMKEY_FILE;SSLClientCert=full_path_of_certificate.pem;SSLServerCert=*
The second format above can be used whenever there is a conflict in your application between drivers using the same URL format to ensure you are using the CData driver. The URL must start with either "jdbc:domino:" or "jdbc:cdata:domino:" and can include any of the connection properties in name-value pairs separated with semicolons.
Before You Connect
The driver requires the Proton component to be installed. Normally, Proton is distributed as part of the AppDev pack. See the HCL documentation for instructions on acquiring and installing Proton or the AppDev pack.
The driver can authenticate to Proton using either anonymous access, or by providing a client certificate. Both of these options require specific configuration within Domino.
The following two sections describe the preliminary configuration necessary to make a connection. Refer to the section that corresponds to your intended authentication method.
Configuring Client Certificate Authentication
In client certificate authentication, the driver connects as a dedicated user account. This user must be granted designer or greater access to any database you connect to.
In addition, the user must have an Internet Certificate in order for the driver to use it. You can have Proton create this certificate by running the following command at the server console. APPUSER is the name of the user account you are configuring for access with the driver, while ADMINISTRATOR is the name of the user that will receive the certificate.
load proton --setupclient "APPUSER" --sendto "ADMINISTRATOR"
The new certificate is avialable from the ADMINISTRATOR mail inbox in Notes. Note that the certificate may be sent as two separate files, a client certificate (clientcert) and a key (clientkey). The two files must be combined by copying and pasting the text from the key file onto the end of the certificate file.
Configuring Anonymous Authentication
In anonymous access, the driver connects using a generic user account called Anonymous. Every database you connect to must have these two permissions configured:
- The Anonymous user must be granted designer or greater access to the database.
- The database must have the Maximum Internet name and password option set to designer or greater access. This setting is found under the Advanced tab of the database Access Control List options.
Connecting to Domino
Set the following to connect:
- Server: The name or IP address of the server running Domino with the Proton service.
- Port: The port number that the Proton service is listening on.
- Database: The name of the database file, including the .nsf extension.
- SSLServerCert: Set this to the TLS/SSL certificate to be accepted from the server. Any other certificate that is not trusted by the machine is rejected. Alternatively, set "*" to accept all certificates.
Authenticating to Domino
The driver can authenticate to Proton using a client certificate, or via anonymous access.
Client Certificate Authentication
Set the following to authenticate with an certificate authentication:- AuthScheme: Set this to SSLCertificate.
- SSLClientCertType: This must match the format of the certificate file. Typically this will be either PEMKEY_FILE for .pem certificates or PFXFILE for .pfx certificates.
- SSLClientCert: The path to the certificate file.