Launching the Schema Tool with Kerberos Authentication

Using the driver : Creating and Customizing Schemas Using the DataDirect Schema Tool : Starting the Schema Tool : Launching the Schema Tool with Kerberos Authentication

Try DataDirect Drivers Now

Your Kerberos environment should be fully configured before you launch the Schema Tool. You should refer to your MongoDB and Java documentation for instructions on configuring Kerberos. For a Windows Active Directory implementation, you should also consult your Windows documentation. For a non-Active Directory implementation (on a Windows or non-Windows operating system), you should consult MIT Kerberos documentation.

Important: A properly configured Kerberos environment must include a means of obtaining a Kerberos Ticket Granting Ticket (TGT). For a Windows Active Directory implementation, Active Directory automatically obtains the TGT. However, for a non-Active Directory implementation, the means of obtaining the TGT must be automated or handled manually.

Once your Kerberos environment has been configured, take the following steps to launch the Schema Tool.

1. Ensure your JAAS login configuration file includes an entry with authentication technology that the driver can use to establish a Kerberos connection. (See "The JAAS Login Configuration File" for details.)

Note: The JAAS login configuration file installed with the driver (install_dir/lib/JDBCDriverLogin.conf) includes a default entry with the name JDBC_DRIVER_01. This entry specifies the Kerberos authentication technology used with an Oracle JVM.

The following examples show that the authentication technology used in a Kerberos environment depends on your JVM.

Oracle JVM

JDBC_DRIVER_01 {
com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true;
};

IBM JVM

JDBC_DRIVER_01 {
com.ibm.security.auth.module.Krb5LoginModule required useDefaultCcache=true;
};

2. Use one of the following methods to integrate the JAAS configuration file into your Kerberos environment, and then start the Schema Tool. (See "The JAAS Login Configuration File" for details.)

Note: The install_dir/lib/JDBCDriverLogin.conf file is the JAAS login configuration file installed with the driver. You can use this file or another file as your JAAS login configuration file.

Note: Regardless of operating system, forward slashes must be used when designating the path of the JAAS login configuration file.

Option 1. Set up a default configuration, and then start the Schema Tool. Modify the Java security properties file to indicate the URL of the login configuration file with the login.config.url.n property where n is an integer connoting separate, consecutive login configuration files. When more than one login configuration file is specified, then the files are read and concatenated into a single configuration.

a. Open the Java security properties file. The security properties file is the java.security file in the /jre/lib/security directory of your Java installation.

b. Find the line # Default login configuration file in the security properties file.

c. Below the # Default login configuration file line, add the URL of the login configuration file as the value for a login.config.url.n property. For example:

# Default login configuration file
login.config.url.1=file:${user.home}/.java.login.config
login.config.url.2=file:install_dir/lib/JDBCDriverLogin.conf

d. Start the Schema Tool jar file. The jar file is installed in the following default locations.

Windows systems: Program Files\Progress\DataDirect\JDBC_60\Tools\schematool.jar

UNIX and Linux systems: /opt/Progress/DataDirect/JDBC_60/Tools/schematool.jar

Option 2. If your Kerberos environment does not include a default configuration as described in Option 1, you must use a JVM argument to specify the JAAS login configuration file and start the Schema Tool. As the following example shows, the JVM argument must specify the location of the JAAS login configuration file with the java.security.auth.login.config system property as well as the location of the Schema Tool jar file.

java -Djava.security.auth.login.config=/home/users/test/driver.conf
install_dir/Tools/schematool.jar

The Open Schema Map window appears.

Note: If you are opening an existing schema map, you can reopen it either by choosing Recent Schema Map and selecting the configuration file of the schema map you want to open, or by choosing Browse to Schema Map and navigating to the configuration file of the schema map that you want to open. When an existing schema is opened, the Schema Tool automatically compares the content of the schema configuration file to a snapshot of the data on the wire. When new native objects are discovered, the Schema Tool displays them in a specialized, hierarchical view of the data and allows you to update your schema accordingly. See Mapping Newly Detected Objects for more information.

3. Select an existing schema map or create a new one (refer to the "SchemaMap" connection property topic in your driver documentation for details):

Selecting an existing map: Select a schema map from the Recent Schema Map field or click Browse to navigate to your schema map.

Creating a map: Click Create. Specify the schema map path by navigating to the directory where you want to store the configuration file. Type the name for the configuration file (for example, MySchema.config) in the File Name field. Click Create New Schema Map. You are returned to the Open Schema Map window where the Schema Map Location field has been populated with the path and file name of the schema map's configuration file.

4. In the fields provided, enter values for each of the connection properties described in the following table.

Table 12. Connection Properties
Property	Characteristic
Host Name	Specifies the name or the IP address of the server to which you want to connect. Important: In a Kerberos configuration, the value of the HostName property must match the fully qualified domain name (FQDN) registered with the KDC. In addition, an IP address cannot be used for the HostName connection property.
Port Number	Specifies the port number of the server listener. The default is 27017.

5. From the Authentication Method drop-down menu, select Kerberos to enable Kerberos authentication.

6. Complete the following two part process.

Note: It is recommended that privileges for generating the schema map be equivalent to the access privileges for an application using the driver. Your authentication settings determine for which databases the Schema Tool retrieves metadata. If authentication is not used, the Schema Tool retrieves metadata for all databases on the server. If authentication is used, the Schema Tool returns only the metadata for the database specified in the DatabaseName property. However, if you are assigned the clusterAdmin role, the Schema Tool returns metadata for all the databases on the server for which you have read privileges.

Part 1. Enter values for the authentication connection properties in the fields provided. These properties are described in the following table.

Table 13. Kerberos Authentication Properties (Part 1)
Property	Characteristic
Database Name	Specifies the name of the database to which you want to connect.
User Name	Optional. Specifies the Kerberos user principal name. When this field is left blank, the Schema Tool uses the user principal name in the Kerberos Ticket Granting Ticket (TGT).

Part 2. As appropriate, specify values for the AuthenticationDatabase, LoginConfigName, and ServicePrincipalName connection properties in the Connection Options field in accordance with the following guide lines. (Only connection properties related to Kerberos and SSL can be specified in the Connection Options field.)

Note: Values for these properties must be entered as semicolon-separated key value pairs. For example, AuthenticationDatabase=kerbuserpals;LoginConfigName=IBM_ENTRY; ServicePrincipalName=mydb/myserver.test.com@EXAMPLE.COM

Set the ServicePrincipalName connection property if the default value built by the driver does not match the service principal name registered with the KDC.

By default, the driver builds the ServicePrincipalName by concatenating the service name mongodb, the fully qualified domain name (FQDN) as specified in the Host Name field, and the default realm name as specified in the Kerberos configuration file. If this value does not match the service principal name registered with the KDC, then the value of the service principal name registered with the KDC should be specified for the ServicePrincipalName property.

The ServicePrincipalName takes the following form.

Service_Name/Fully_Qualified_Domain_Name@REALM_NAME

See "ServicePrincipalName" for details on the composition of the service principal name.

Set the AuthenticationDatabase connection property if user principal names stored by MongoDB are stored in a database other than the default $external database. (See "AuthenticationDatabase" for details.)

Set the LoginConfigName connection property if the name of the JAAS login configuration file entry is different from the driver default JDBC_DRIVER_01. (See "The JAAS Login Configuration File" and "LoginConfigName" for details.)

JDBC_DRIVER_01 is the default entry name for the JAAS login configuration file (JDBCDriverLogin.conf) installed with the driver. When configuring your Kerberos environment, your network or system administrator may have used a different entry name. Check with your administrator to verify the correct entry name.

Table 14. Kerberos Authentication Properties (Part 2)
Property	Characteristic
AuthenticationDatabase	Specifies the database on the MongoDB server where user principal names are stored for Kerberos authentication. The default is $external.
LoginConfigName	Specifies the name of the entry in the JAAS login configuration file that contains the authentication technology used by the driver or Schema Tool to establish a Kerberos connection.
ServicePrincipalName	Specifies the three-part service principal name registered with the key distribution center (KDC) in a Kerberos configuration.

7. Optionally, specify configuration options to determine how native data is mapped to the relational schema. In the Configuration Options field, enter a semicolon-separated list of configuration options and their values. For example, columnDiscoverySampleSize=1000;UppercaseIdentifiers=true;. Configuration options are described in the following table. For more detail, refer to the "ConfigOptions" topic in the driver documentation.

Table 15. Schema Tool Config Options
Option	Characteristic
ColumnDiscoverySampleSize	Specifies the number of rows the driver fetches per collection when sampling data to detect columns and gather column statistics. The information collected in these samples is used when defining a schema map with the DataDirect Schema Tool. Larger fetch sizes return samples that are more representative of your data, but at the expense of slower performance. See About Column Information and Statistics for additional information on how sampling is used for statistics. The default is 1000.
DefaultVarcharSize	Determines the default length of fields that are mapped as VARCHAR. The default is 1.5x.
KeywordConflictSuffix	Specifies a string of up to five alphanumeric characters that the driver appends to any object or field name that conflicts with a SQL engine keyword. For example, if you specify KeywordConflictSuffix=TAB, the driver maps the Case object to CASETAB.
LeadingUnderscoreReplacement	Specifies the string of characters that replace leading underscores used in identifiers for collections, documents, and arrays.
MaxVarcharSize	Specifies the maximum default length of fields that are mapped as VARCHAR when a multiplier is specified for the DefaultVarcharSize configuration option (DefaultVarcharSize=multiplier).
MinVarcharSize	Specifies the minimum default length, in characters, of fields that are mapped as VARCHAR when a multiplier value is specified for the DefaultVarcharSize configuration option (DefaultVarcharSize=multiplier).
SchemaFilter	Specifies a comma-separated list of database and collection pairs for which you want the driver to fetch metadata. SchemaFilter can significantly improve connection times by limiting the collections for which metadata is fetched to only those that are required by your application. This value takes the following form: SchemaFilter=database_name:collection_name[[,database_name:collection_name]...] See "SchemaFilter (Config Option)" for detailed list of supported values.
UppercaseIdentifiers	Specifies whether the driver maps all identifier names to uppercase. By default, the driver maps all identifier names to uppercase. If set to true, the driver maps identifiers to uppercase. If set to false, the driver maps identifiers to the mixed case name of the object being mapped. If mixed case identifiers are used, SQL statements must enclose those identifiers in double quotation marks, and the case of the identifier must exactly match the case of the identifier name. See Naming Conflicts for additional information about using identifiers. The default is true.

8. To configure SSL, specify connection property values in the Connection Options field as semicolon-separated key value pairs. For example, EncryptionMethod=SSL;ValidateServerCertificate=true;HostNameInCertificate=Server3. (Only connection properties related to Kerberos and SSL can be specified in the Connection Options field.)

Note: To fully implement SSL, you must also specify SSL connection property values in the connection string used by your JDBC application. The connection property values in the Connection Options field must match the values you specify in the connection URL used by your JDBC application.

Note: When creating or opening a schema map, the Schema Tool accesses data from the server for the purpose of object mapping and generating column statistics. This process requires data to be transferred over networks, which can make data vulnerable to interception by unauthorized parties. To provide more secure transmission of data, you should consider enabling SSL.

Table 16. Data Encryption Properties
Property	Characteristic
EncryptionMethod	Determines whether data is encrypted and decrypted when transmitted over the network between the driver and database server. To enable SSL, set EncryptionMethod to SSL. The default is noEncryption.
HostNameInCertificate	Specifies a host name for certificate validation when SSL encryption is enabled (EncryptionMethod=SSL) and validation is enabled (ValidateServerCertificate=true). This property is optional and provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested.
KeyPassword	Specifies the password that is used to access the individual keys in the keystore file when SSL is enabled (EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. This property is useful when individual keys in the keystore file have a different password than the keystore file.
KeyStore	Specifies the directory of the keystore file to be used when SSL is enabled (EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. The keystore file contains the certificates that the client sends to the server in response to the server’s certificate request.
KeyStorePassword	Specifies the password that is used to access the keystore file when SSL is enabled (EncryptionMethod=SSL) and SSL client authentication is enabled on the database server. The keystore file contains the certificates that the client sends to the server in response to the server’s certificate request.
TrustStore	Specifies the directory of the truststore file to be used when SSL is enabled (EncryptionMethod=SSL) and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the client trusts.
TrustStorePassword	Specifies the password that is used to access the truststore file when SSL is enabled (EncryptionMethod=SSL) and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the client trusts.
ValidateServerCertificate	Determines whether the driver validates the certificate that is sent by the database server when SSL encryption is enabled (EncryptionMethod=SSL). When using SSL server authentication, any certificate that is sent by the server must be issued by a trusted Certificate Authority (CA). The default is true.

9. To create a new schema map, click Open Schema Map and proceed to Creating a Schema with the Table Wizard.

10. If you are using an existing schema map, choose one of the following sampling behaviors to execute at connection:

All Collections: The driver samples all new and existing collections to detect changes. This provides the most accurate view of your data, but, depending on the number and size of your collections, can take a long time to process.

Only New Collections: The driver samples only newly discovered collections. This provides the quickest processing time, allowing you to begin using the tool faster. If you only want to map new collections, or if existing collections are unchanged, this method is recommended.