Creating a content store using an Oracle database with Kerberos security

You can create an Oracle content store that uses Kerberos authentication.

About this task

To create a content store that uses an Oracle database with Kerberos security, you must configure Cognos Analytics to use the Oracle JRE instead of the IBM JRE. The IBM JRE is not compatible with Oracle when it uses Kerberos authentication.

Tips:

To debug Kerberos, you can make one or both of these changes:

  • Edit the file Cognos_Analytics_installation_location/wlp/usr/servers/cognosserver/bootstrap.properties and add this line:
    sun.security.krb5.debug=true
  • Edit the JAAS login configuration file and add this line to the entry that is used for creating a content store:
    debug=true

In both cases, debugging messages will appear in the file Cognos_Analytics_installation_location/logs/cognosserver.log.

Procedure

  1. Install the Oracle JRE.
    1. Check the Supported environments page (https://www.ibm.com/support/pages/node/735235) to see which versions of Oracle JRE are supported by your version of Cognos Analytics.
    2. Install a supported version of Oracle JRE.

      For more information, see the Oracle JRE Download page (https://java.com/en/download/).

  2. Set the following environment variables to point to the Oracle JRE that you installed:
    set JAVA_HOME=Oracle_JRE_installation_location
    set path=%JAVA_HOME%\bin;%path%
  3. Configure Cognos Analytics to use the Oracle JRE version that you just installed.
  4. Ask your Kerberos administrator to give you the krb5.conf and .keytab files.
  5. Add the krb5.conf file to the JRE_installation_location/lib/security folder.
  6. If you plan to use credential caching, create ticket cache files from the .keytab files.

    For example, follow these steps:

    1. Navigate to the JRE_installation_location/bin directory.
    2. Run this command:
      klist -k -t -K -e absolute_path_to_keytab_file
      Tip: Note the value of principal.
    3. Run this command:
      kinit -c cache_file -k -t absolute_path_to_keytab_file principal
  7. Create a JAAS login configuration file called, for example, jaas.conf.
    Tip: See the sample file, installation_location/configuration/jaas-oracle.config.sample
  8. Define an entry in the jaas.conf file as shown in these example entries:

    Example entry for credential cache:

    com.cognos.biserver.security.cm
    {
        com.sun.security.auth.module.Krb5LoginModule required
        debug=true
        useTicketCache=true
        ticketCache="absolute_path_to_ticket_cache_file"
        renewTGT=true
        doNotPrompt=true
        principal="service_principal_value";
    }; 

    Example entry for key tab:

    com.cognos.biserver.security.cm
    {
        com.sun.security.auth.module.Krb5LoginModule required
        debug=true
        doNotPrompt=true
        useKeyTab=true
        refreshKrb5Config=true
        keyTab="absolute_path_to_keytab_file"
        principal="service_principal_value";
    }; 
    

    Example entry for both the credential cache and the key tab:

    Note:

    In the following example entry, the ticket cache is checked first. If a ticket-granting ticket (TGT) cannot be found, then the keytab is used to log on. However, if the TGT is found but is expired, the system will throw an exception, instead of using the keytab.

    com.cognos.biserver.security.cm
    {
        com.sun.security.auth.module.Krb5LoginModule required
        debug=true
        useTicketCache=true
        ticketCache="absolute_path_to_ticket_cache_file"
        renewTGT=true
        doNotPrompt=true
        useKeyTab=true
        refreshKrb5Config=true
        keyTab="absolute_path_to_keytab_file"
        principal="service_principal_value";
    }; 
  9. Add the following line to the file installation_location/wlp/usr/servers/cognosserver/bootstrap.properties:
    java.security.auth.login.config="absolute_path_to_jaas.conf"
  10. Add the following line to the file JRE_installation_location/lib/security/java.security:
    login.config.url.n=file:absolute_path_to_jaas.conf

    where n is a sequence, starting at 1.

  11. Copy the Oracle JDBC Thin driver, for example ojdbc8.jar, to the installation_location/drivers directory.
  12. Start Cognos Configuration and create an Oracle content store that uses Kerberos authentication.
    Tip: When you configure a new content store in Cognos Configuration, the default name is com.cognos.biserver.security.cm. However, you can change this name if you want.
  13. When you start the IBM Cognos service, if Connection failure error messages appear in Cognos Configuration, try adjusting the settings that control connection attempts:
    1. In Cognos Configuration, select Data Access > Content Manager > Content Store.
    2. Click in the Advanced properties field and then click the pencil icon .
    3. Add the following Name-Value pair:

      Name: max.connection.attempts

      Value: 15

    4. Add the following Name-Value pair:

      Name: seconds.between.retries

      Value: 2

    5. Save the configuration and start the IBM Cognos service.
    6. When the service starts, if connection error messages still appear, adjust the parameter values that you set in steps c and d, then again save the configuration.
  14. If the error message java.sql.SQLException: Oracle Error ORA-12631 appears, follow these steps:
    1. Open the file krb5.conf in a text editor.
    2. Remove the line forwardable=true.
    3. Save the file.