Setting up an Oracle Connection with Kerberos (for Agents on Linux)

Versions: 8.0+

As organizations become increasingly security-aware, use of Kerberos authentication is becoming more wide-spread. Oracle support for Kerberos authentication via JDBC has been available since Oracle 11g Release 1 (11.1). The following article describes how to set up a kerberized connection to Oracle for QuerySurge Agents deployed on Linux.

1. JDBC Driver files and related files

1a. If you have not already deployed JDBC driver jar files to your Agent(s), get the appropriate JDBC driver jar(s) for your Oracle version. You can download the driver jar(s) either from the Oracle website or you may obtain them from Oracle resources internal to your organization.

Note: These instructions apply only to Oracle 11g Release 1 (11.1) and higher, as Kerberos support was introduced with this Oracle release.

2. Kerberos Configuration Files

2a. krb5.conf file - From your Kerberos admin or other knowledgeable resource, obtain a krb5.conf file.

2b. keytab file - If you're authenticating to Kerberos via a keytab, you'll need to obtain a keytab file (usually generated by a Kerberos admin or other knowledgeable resource), and the user principal associated with the keytab.

2c. gss-jaas.conf - You'll need a gss-jaas.conf file, which points to the keytab file. The basic gss-jaas.conf file layout is below. Note the dummy path to the keytab and the dummy principal in this file template:

com.sun.security.jgss.initiate {
com.sun.security.auth.module.Krb5LoginModule required
useTicketCache=false
doNotPrompt=true
useKeyTab=true
keyTab="/<QuerySurge Install Dir>/QuerySurge/agent/mykeytab.keytab"
principal="[e-mail]"
debug=true;
};

Note: The principal used in your gss-jaas.conf is usually a user principal; however, this depends on your Kerberos configuration.

Note: In the example above, the leading name com.sun.security.jgss.initiate, which appears before the opening curly brace, is the Login Context. Your Login Context may be different; check with a Kerberos-knowledgeable resource in your organization.

Note: keytab files may have a single key for a single principal or may have multiple keys.

3. Agent Setup

Note: We recommend using the QuerySurge Agent directories for the file locations in this setup step, since this should be the same for all your Agents. However, there is no requirement to use these specific directories.

3a. Stop the Agent with the command: 
[sudo] service QuerySurge stop agent

3b. Make sure that the proper set of JDBC jar files is deployed to <QuerySurge Install Dir>/QuerySurge/agent/jdbc per step 1a.

3c. Copy your krb5.conf, gss-jaas.conf and keytab files to /<QuerySurge Install Dir>/QuerySurge/agent/

3d. You may need to use the Kerberos client to run a kinit command locally, on your Agent box(es). This requires installation of a KDC client on the Agent box. The command has the following form:

kinit -kt mykeytab [e-mail]

where the principal is the user principal for the user that is connecting to Hive.

Note: You may need to use the full path to the keytab file.

Note: You may have to copy the krb5.conf to /etc directory.

4. Agent Configuration

4a. Make a copy of /<QuerySurge Install Dir>/QuerySurge/agent/ctl.sh:
[sudo] cp ctl.sh ctl.sh.orig

4b. CAREFULLY edit your ctl.sh to add the following switches to the line starting with nohup nice. These switches should be added immediately before -cp (with single-space separation):

-Djavax.security.auth.useSubjectCredsOnly=false
-Djava.security.krb5.conf=/<QuerySurge Install Dir>/QuerySurge/agent/krb5.conf
-Djava.security.auth.login.config=/<QuerySurge Install Dir>/QuerySurge/agent/gss-jaas.conf

Note: You'll have to replace the dummy paths in these settings with actual paths to the files.

Note: If you do not need a gss-jaas.conf file, then omit the -Djava.security.auth.login.config switch.

Note: During setup, a high level of debug output is often helpful. This can be implemented by adding the following command-line options:
-Dsun.security.krb5.debug=true
-Djava.security.debug=gssloginconfig,configfile,configparser,logincontext

For the default installation in /opt/QuerySurge, the switches are:
-Dsun.security.krb5.debug=true
-Djavax.security.auth.useSubjectCredsOnly=false
-Djava.security.krb5.conf=/opt/QuerySurge/agent/krb5.conf
-Djava.security.auth.login.config=/opt/QuerySurge/agent/gss-jaas.conf

You can download a sample copy of ctl.kerb.sh with these default values (see the Resources section at the end of the article). The purpose of this file is for illustration of the changes required, not for deployment to your instance.

 See Resources section: ctl.kerb.sh

4c. Modify the agentconfig.xml to include the following Oracle-specific key-value pairs. Make a copy of /<QuerySurge Install Dir>/QuerySurge/agent/config/agentconfig.xml:
[sudo] cp agentconfig.xml agentconfig.xml.orig

4d. CAREFULLY edit the agentconfig.xml to add the following tags under the <connectionProps> tag to set the Kerberos-related Oracle JDBC properties:
<connectionProps>
  <driverProp driver="oracle.jdbc.driver.OracleDriver" prop="oracle.net.authentication_services" type="String" value="( KERBEROS5 )"/>
  <driverProp driver="oracle.jdbc.driver.OracleDriver" prop="oracle.net.kerberos5_mutual_authentication" type="String" value="true"/>
...
</connectionProps>

Note: Setting these properties in the agentconfig.xml means that they apply to all Oracle connections made by the Agent. This means that non-kerberized Oracle connections cannot be made using this Agent; a different Agent (whose agentconfigxml has not been modified with these tags) will be able to connect to non-kerberized Oracle instances.

4e. Start your Agent:
[sudo] service QuerySurge start agent

5. QuerySurge Connection Wizard (using the Connection Extensibility option)

5a. Open the Connection Wizard in the QuerySurge Admin view. Select the Connection Extensibility option in the Data Source dropdown. Use the following values and templates:

Driver Class:
oracle.jdbc.driver.OracleDriver

Common Oracle JDBC URL templates include the following:

Oracle-Service based:
jdbc:oracle:thin:@[server]:[port]:[service]

Oracle-SID based:
jdbc:oracle:thin:@//[server]:[port]/[SID]

Oracle TNS Syntax:
jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=[server])(PORT=[port]))(LOAD_BALANCE=YES)(FAILOVER=on)(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=[service])(FAILOVER_MODE=(TYPE=SELECT)(METHOD=BASIC)(RETRIES=180)(DELAY=5))))

Note: The proper JDBC URL template for your instance may differ from those shown here; check with an Oracle DBA for the proper URL syntax if none of these approaches work.

Once you have set up a url, try a Connection Test or a QueryPair with a simple query of the form:
SELECT 1 FROM dual

Note: Remember to set up all Agents that are to make kerberized connections to Oracle as shown here.

Resources

1. Agent ctl.sh shell modified (file: ctl.kerb.sh) with Kerberos switches using the default install paths.