Jive Connector and Datasource Configuration

Retrieve content from a Jive instance.

Install the Jive Add-on

The Jive add-on lets you use OAuth to authenticate the Fusion connector to the Jive API. This is a recommended way to use the Jive API. The Jive add-on retrieves a client ID and secret, which are supplied to the Fusion connector. See the Jive product documentation.

If the client ID and secret cannot be retrieved or used, then Basic authentication is used as a fallback.

Install the Jive Add-on
  1. Install the Fusion Jive connector using the Fusion UI.

    1. In the Fusion UI, navigate to Indexing > Datasources.

    2. Click Add.

    3. Follow the UI prompts to install the Jive connector. For more information, see Managing Connectors in the Search Development Guide.

  2. Following the instructions from the Jive product documentation, use the Jive UI to upload the add-on from your Fusion distribution.

    1. On Linux, the Jive add-on is at

      $FUSION_HOME/apps/connectors/connectors-classic/plugins/lucid.jive/assets/lucidworks-jive-addon.zip
    2. On Windows, the Jive add-on is at

      %FUSION_HOME%\apps\connectors\connectors-classic\plugins\lucid.jive\assets\lucidworks-jive-addon.zip

Security Trimming of Results

If security trimming is enabled, the Jive connector uses the visibility field while indexing permission metadata on content. This data is stored in the acl_ss field for each document.

The value of the visibility field determines the permissions assigned to a document. The following table describes how the types of permissions found in the visibility field of a document are used.

Permission type Notes
All

The value stored in the acl_ss field is "all".

People

The document includes a list of users who are authorized to view the content. This list is stored in the acl_ss field as user email addresses.

Place

A request is made to determine the type of group. The group type determines the permissions stored.

Open or Members Only

The value stored in the acl_ss field is "all".

Private or Secret

The value stored in the acl_ss field is the name of the group.

Crawl a Jive instance protected by Kerberos

The Fusion Jive connector can crawl Jive repositories protected by Kerberos using SPNEGO. This is a way to access Jive without requiring a user’s login credentials.

The Fusion Jive connector can optionally use Kerberos with SAML/Smart Form authentication.

To crawl a Kerberos-protected Jive repository, first create the necessary configuration files, then configure Fusion to use them.

Create standard Java configuration files to connect to Kerberos

Fusion uses the JDK standard JAAS Kerberos implementation, which is based on three system properties that reference three separate files.

The files are as follows:

  • On the Kerberos-protected server, a keytab file, named kerberuser.keytab in our examples.

  • On the Fusion server, a configuration file named login.conf.

  • On the Fusion server, an initialization file named krb5.ini (Windows) or krb5.conf (Linux).

Create a Kerberos keytab

Create and validate the keytab file for the Kerberos client principal you want to use to authenticate to the Jive repository.

If you do not specify the kerberosPrincipalName and kerberosKeytabFilePath or kerberosKeytabBase64 when creating the Fusion datasource, Fusion uses the default login principal and ticket cache. You can see the default values by logging into the Fusion server as the user who runs Fusion and running klist.

If you do not want to use the default account and credentials, specify these configuration properties when creating a keytab as well as in the Jive datasource setup. Use the Kerberos user principal name (UPN), not the service principal name (SPN, which is used with the Kerberos security realm). In some cases the UPN can be a service.

In our examples, the Fusion Jive connector authenticates to the Jive repository using the user kerbuser@win.lab.lucidworks.com. We create a keytab file kerbuser.keytab for the user principal kerbuser@WIN.LAB.LUCIDWORKS.COM.

Create a Kerberos keytab on Windows

Example:

ktpass -out kerbuser.keytab -princ kerbuser@WIN.LAB.LUCIDWORKS.COM -mapUser kerbuser -mapOp set -pass YOUR_PASSWORD -crypto ALL -pType KRB5_NT_PRINCIPAL
Create a Kerberos keytab on Ubuntu Linux

Prerequisite: Install the krb5-user package: sudo apt-get install krb5-user

Example:

ktutil
addent -password -p HTTP/kerbuser@WIN.LAB.LUCIDWORKS.COM -k 1 -e aes128-cts-hmac-sha1-96
- it will ask you for password of kerbuser -
wkt kerbuser.keytab
q
Test the keytab

Once you create a keytab, verify that it works.

Prerequisite: You need a version of curl installed that allows SPNEGO. To test whether your version of curl does this, run curl --version and make sure SPNEGO is in the output.

Run the following curl command (replace the keytab path and site):

export KRB5CCNAME=FILE:/path/to/kerbuser.keytab curl -vvv --negotiate -u : http://your-site.com

Note that the first request is a 401 status code for the negotiate request followed by a second request, which is a status of 200.

Create a login.conf and krb5.ini

On the Fusion server, create login.conf and krb5.ini files as follows.

Create a login.conf on Windows

In this example, the keytab is stored at C:\kerb\kerbuser.keytab

KrbLogin {
  com.sun.security.auth.module.Krb5LoginModule required
  useKeyTab=true
  storeKey=true
  keyTab="C:\kerb\kerbuser.keytab"
  useTicketCache=true
  principal="kerbuser@WIN.LAB.LUCIDWORKS.COM"
  debug=true;
};
Create a login.conf on Linux

In this example, the keytab is stored at /home/lucidworks/kb.keytab

com.sun.security.jgss.initiate {
  com.sun.security.auth.module.Krb5LoginModule required
  useKeyTab=true
  storeKey=true
  keyTab="/home/lucidworks/kerbuser.keytab"
  useTicketCache=true
  principal="kerbuser@WIN.LAB.LUCIDWORKS.COM"
  debug=true;
};

The format of the login.conf is described on the Oracle Web site.

Create a krb5.ini or krb5.conf

When you install krb5 on Linux, you can find a Kerberos configuration file in /etc/krb5.conf. You can optionally create a custom one instead.

Creating a krb5.conf is the same for Linux and Windows. On Windows the file is krb5.ini.

In this example the domain is WIN.LAB.LUCIDWORKS.COM, the Kerberos kdc host is my.kdc-dns.com, and the Kerberos admin server is my-admin-server-dns.com.

Example:

[libdefaults]
    default_realm = WIN.LAB.LUCIDWORKS.COM
    default_tkt_enctypes = aes128-cts-hmac-sha1-96
    default_tgs_enctypes = aes128-cts-hmac-sha1-96
    permitted_enctypes = aes128-cts-hmac-sha1-96
    dns_lookup_realm = false
    dns_lookup_kdc = false
    ticket_lifetime = 24h
    renew_lifetime = 7d
    forwardable = true
    udp_preference_limit = 1

[realms]
WIN.LAB.LUCIDWORKS.COM = {
   kdc = my.kdc-dns.com
   admin_server = my.admin-server-dns.com
}

[domain_realm]
.WIN.LAB.LUCIDWORKS.COM = WIN.LAB.LUCIDWORKS.COM
WIN.LAB.LUCIDWORKS.COM = WIN.LAB.LUCIDWORKS.COM

The format of the krb.conf or krb5.ini file is described in the MIT Kerberos documentation. You can change the encryption algorithms by changing the properties default_tkt_enctypes, default_tgs_enctypes, and permitted_enctypes as needed. For example:

default_tkt_enctypes = RC4-HMAC
default_tgs_enctypes = RC4-HMAC
Permitted_enctypes = RC4-HMAC

Configure Fusion to use Kerberos

Once you have the keytab, login.conf, and krb5.ini files, configure Fusion to use Kerberos. You must set a property in a Fusion configuration file in addition to defining the datasource in the Fusion UI.

At the command line on any machine in your Fusion cluster:

  1. In $FUSION_HOME/conf/fusion.properties, add the following property to the connectors-classic jvmOptions setting: -Djavax.security.auth.useSubjectCredsOnly=false

  2. Restart the connectors-classic service using ./bin/connectors-classic restart on Linux or bin\connectors-classic.cmd restart on Windows.

In the Fusion UI:

  1. Click Indexing > Datasources. HEAD

  2. Click Add+, then Jive.

  3. Enter a datasource ID and a Jive instance URL.

  4. Check Enable SPNEGO/Kerberos Authentication.

  5. You can either use the default principal name or specify a principal name to use.

    • If you do not specify the principal name, then Fusion uses the default login principal and ticket cache. You can see those default values by logging into the Fusion server as the user who runs Fusion and running klist.

  6. If you specify a principal name, you must provide a keytab, either in Base64 or as a file path.

    • If you specify a keytab file path, the file must be on the machine running the Fusion connector, for each connector’s node in the cluster.

    • The Base64 option lets you supply the keytab in one place, in the UI.

  7. Fill in any remaining options to configure the datasource.

Configuration

Tip
When entering configuration values in the UI, use unescaped characters, such as \t for the tab character. When entering configuration values in the API, use escaped characters, such as \\t for the tab character.