Configuring Fusion for Kerberos

To configure the Fusion UI service to use Kerberos for user authentication, you must create a Kerberos security realm.

Kerberos is a system that provides authenticated access for users and services on a network. Instead of sending passwords in plaintext over the network, encrypted passwords are used to generate time-sensitive tickets that are used for authentication. SPNEGO provides a mechanism for extending Kerberos to Web applications through the standard HTTP protocol.

Kerberos uses symmetric-key cryptography and a trusted third party called a Key Distribution Center (KDC) to authenticate users to a suite of network services. (By users we mean both end users and client programs). The computers managed by that KDC and any secondary KDCs constitute a realm. When a user authenticates to the KDC, the KDC sends a set of credentials (a ticket) specific to that session back to the user’s machine. Kerberos-aware services use the ticket on the user’s machine for authentication instead of requiring sign-on with a password. Because tickets are used rather than passwords, this provides the convenience of Single Sign-On (SSO) in addition to security.

A Kerberized process is one that has been configured so it can get tickets from a KDC and negotiate with Kerberos-aware services. When a user sends an HTTP request, Fusion tries to authenticate using the Kerberos/SPNEGO protocol. If the request was sent from a browser, Fusion doesn’t display the initial sign-on panel; instead on login, the user sees the main Fusion collections panel.

To Kerberize Fusion, you must:

  • Configure the Kerberos client on the server that the Fusion UI service will be running on so that it can talk to the KDC (section Configuring the Kerberos client below).

  • Configure the security realm of the Fusion UI (section Configuring Fusion Authentication for Kerberos Realm below).

  • Depending on the encryption used by the KDC, you may also need to install additional Java security libraries into the Fusion distribution. These are freely available from Oracle, see download and installation instructions below.

To do this, you need following information, which you can get from your sysadmin:

  • Kerberos realm name - in most cases, this is your domain name in upper case.

  • KDC name - usually "kerberos." + your domain name.

  • Kerberos principal name and password. A principal is a unique identity to which Kerberos can assign tickets. When the entity is a client program, this is called the Service Principal name.

  • A keytab file which holds the encrypted credentials.

The usual scenario in an enterprise organization is to have a Kerberos admin create a service principal with a random key password. Then, the admin generates a keytab, which is then used for Fusion service principal authentication.

The Kerberos commands needed for configuration and testing are:

  • kinit - obtain and cache a ticket from the KDC (i.e., domain login)

  • kdestroy - destroys credentials (i.e., domain logout)

  • klist - lists cached credentials

  • ktutil - create or add credentials to a keytab file

If your browser is not already configured to use the Kerberos/SPNEGO, you will need to do so in order to test the Fusion configuration.

Configuring the Kerberos client

Step 1: Edit the Kerberos configuration file.

To configure your local Kerberos client so that it can talk to the Kerberized server, you must edit Kerberos configuration file named krb5.conf. On most Unix systems, this file is located at /etc/krb5.conf.

This file contains Kerberos configuration information, including the locations of KDCs and admin servers for the Kerberos realms of interest, defaults for the current realm and for Kerberos applications, and mappings of hostnames onto Kerberos realms.

If your organization realm name is "MYORG.ORG", and your KDC server is named "kerberos.myorg.org", then you edit two entries. The first entry is libdefaults. Set MYORG.ORG as the default realm:

[libdefaults]
  default_realm = MYORG.ORG

The second entry is realms. Add MYORG.ORG as a realm:

[realms]
  MYORG.ORG = {
    kdc = kerberos.myrealm.com
  }

For example, for realm LUCIDWORKS.IO, the krb5.conf file is just like the above example, except that instead of "myorg.org" we specify "lucidworks.io".

Step 2: Authenticate to Kerberos

The command kinit is the Kerberos authentication command. To get started, you authenticate to Kerberos using the Kerberos principal name and password (which you may need to obtain from your sysadmin). For this example, the principal name is "prince".

> kinit prince

The kinit command prompts for a password. Successful authentication is silent. Unsuccessful authentication results in an error message.

The command klist shows all cached Kerberos credentials. To check that you’ve successfully authenticated, run this command:

> klist

Output should be in this form, but with your data:

Credentials cache: API:C980F9F5-415C-4A3E-9C67-883C7D5FFFBE
        Principal: prince@MYORG.ORG

  Issued                Expires               Principal
May  6 15:14:55 2015  May  7 01:12:47 2015  krbtgt/MYORG.ORG@MYORG.ORG

The Service Principal Keytab file

The usual scenario in an enterprise organization is to have a Kerberos admin create a service principal with a random key password. Then, the admin generates a keytab, which is then used for Fusion service principal authentication. If you are your own Kerberos admin, then you will need to create this file for yourself.

Step 3. Create a Keytab file

The command ktutil creates the service principal keytab file which holds the encrypted credentials that the Fusion UI Proxy will use for Kerberos authentication. In order to generate the keytab file, you must have a set of cached credentials, therefore, first run the kinit command (step 2).

From the command line, run the command ktutil. You must enter your password twice.

> ktutil -k http-myrealm.org.keytab add -p HTTP/myrealm.org@MYORG.ORG -e aes256-cts-hmac-sha1-96 -V 0

The -k argument specifies the name of the keytab file which will be created or updated. The command "add" takes the following argument flags:

  • "-p" : service principal, format <service>/<fully.qualified.domain>@REALM

  • "-e" : encryption type. Depending on the encryption type, you may need to download additional Java security libraries for strong encryption.

  • "-V" : key version number (kvno). Key version numbers are used in the Kerberos V5 protocol to distinguish between different keys in the same domain.

If successful, this command creates a keytab file called "http-myrealm.org.keytab". Note the directory you’re in - you’ll need this full path when creating the Proxy realm-config later.

Step 4. Test the Keytab file

The location of this keytab file will be used to configure UI Proxy configuration. Before configuring the Fusion UI Proxy, you should check that the keytab file is valid. Testing the keytab requires the following sequence of steps:

  • Clear any existing credentials via command kdestroy.

  • Log in using the keytab as an argument to the command kinit -kt <keytab file> <principal>, where <principal> is the name of a principal within the keytab file.

  • Examine your credentials via command klist.

  • Clear credentials via command kdestroy, which removes any existing credentials, effectively logging you out of Kerberos.

To remove cached credentials, use the kdestroy command. This command succeeds silently. To check that credentials have been removed, re-run the klist command:

> kdestroy
> klist
klist: krb5_cc_get_principal: No credentials cache file found

Use the keytab to login as the service principal, without being prompted for a password:

> kinit -t http-myrealm.org.keytab HTTP/myrealm.org

Examine your credentials via the command klist. The output should be similar to this:

Credentials cache: API:51D488FF-5CD9-4E16-98FA-B47743F5B4ED
        Principal: HTTP/myrealm.org@MYORG.ORG

  Issued                Expires               Principal
Apr  1 09:15:02 2015  Apr  1 19:13:42 2015  krbtgt/MYORG.ORG@MYORG.ORG

Logout again with kdestroy.

Configuring Fusion Authentication for Kerberos Realm

Once you have tested both the user and service principal logins, you must create the service principal realm-config in the Fusion Authentication Proxy. This allows the Proxy to authenticate to Kerberos as the service principal, without a password.

Step 5. Configure the Fusion Realm

Fusion security realms can be configured either via the Fusion UI Admin tool or the Fusion REST API. The advantage of using the Fusion UI Admin Tool is that a single panel’s worth of configuration requires a series of calls to the REST API. It is important to understand the set of configuration properties collected by the Fusion UI and how they are used by the REST API.

A security realm for Kerberos has the following properties:

  • name : unique string identifier

  • realmType : "kerberos"

  • enabled : whether or not the realm is available for users to use with system authentication

  • config : this property is required for the realm type "kerberos". It takes two key-value pairs:

    • principal : the principal service name

    • keytab : this must be the full path to the keytab file.

To configure Fusion via the Fusion UI Admin tool, you should be logged in to Fusion as "admin" or as a user who has super-admin privileges.

From the Fusion Admin tool, choose the "Access" control from the left hand side nav bar, and go to the Access tab "Security Realms" (URL: <server>:<port>/admin/security-realms).

Click on the "Add Security Realm" button. On the New Security Realm form, choose type "kerberos" from the pulldown menu so that there are input boxes for the Kerberos realm properties "Service Principal" and "Keytab path". Choose a realm name, check the "enabled" checkbox, and enter the service principal and the full path to the keytab file.

The New Security Realm form also controls the default roles assigned to a user the first time that they access Fusion via this realm, using the Kerberos/SPNEGO protocol. For example, once you have defined a Kerberos realm "my-kerberos-realm" for domain "MYORG.ORG", when user "any.user" in domain "MYORG.ORG" authenticates to Fusion for the first time via this realm, they will be added to the set Fusion users as username "any.user@MYORG.ORG" and they will have all default roles.

It is prudent to allow the minimum set of default roles, as all users will have these permissions. Some users will require admin privileges and a few users will require super-admin privileges. There should always be a user with super-admin privileges that can authenticate to Fusion using the native security realm and can then grant permissions to individual users as needed.

Kerberos/SPNEGO HTTP Authentication

SPNEGO provides a mechanism for extending Kerberos to applications that use the HTTP protocol including web browsers and the curl command-line utility.

Step 6. Configure the HTTP client

When a user sends a request to the Kerberized Fusion UI, a SPNEGO request (http[s]) is made. If the user is not already authenticated, the Fusion authentication proxy will yield a 401 status code and a Negotiate header. This status/header response triggers compatible clients to fetch a local ticket from their Kerberos "ticket tray". This ticket is then encoded and sent back to the Fusion. The Fusion authentication proxy will then decode the ticket, and perform a SPN.doAs(user) authentication request to the KDC/Authentication Service. Depending on the results, the proxy then successfully executes the original request (along with a session cookie) or a 401 (without the Negotiate). Clients can either choose to use the session cookie or continue authenticating on every request.

Configuring Web Browsers and curl for SPNEGO

The --negotiate option enables SPNEGO in curl.

IE and Safari require no additional configuration to use SPNEGO.

To configure Firefox, access the low level configuration page by loading the about:config page. Then go to the network.negotiate-auth.trusted-uris preference and add the hostname or the domain of the web server that is HTTP Kerberos SPNEGO protected (if using multiple domains and hostname use comma to separate them).

The Chrome browser must be launched from the command line with several added parameters.

To run Chrome on linux:

> google-chrome --enable-plugins --args\
  --auth-server-whitelist="*KERBEROS_DOMAIN"\
  --auth-negotiate-delegate-whitelist="*KERBEROS_DOMAIN"\
  --auth-schemes="basic,digest,ntlm,negotiate"

To run Chrome on a Mac:

> open 'Google Chrome.app' --args\
  --auth-server-whitelist="*ROGUECLOUD.COM"\
  --auth-negotiate-delegate-whitelist="*KERBEROS_DOMAIN"\
  --auth-schemes="basic,digest,ntlm,negotiate"

To run Chrome on Windows:

chrome.exe --auth-server-whitelist="*KERBEROS_DOMAIN"\
  --auth-negotiate-delegate-whitelist="*ROGUECLOUD.COM"\
  --auth-schemes="basic,digest,ntlm,negotiate"

Session cookies

A successful Kerberos/SPNEGO login will yield a session cookie, this cookie is identical to the cookie yielded by the Fusion authentication proxy’s current POST-login-mechanism.

The expiration policy on the cookie is currently fixed at 8 hours. But has a 1 hour "idle" max, which means if you don’t make a request for 1 hour, the cookie is invalidated. Otherwise the lifetime is pushed ahead until the 8 hour max is met.

The name of the cookie is "id" and the value is a UUID. This UUID is a key that maps to an in-memory value containing the real user ID.

Testing and Troubleshooting

Once you have configured the Kerberos security realm, you can test it by logging out of Fusion and shutting down the browser.

Check that you have a valid Kerberos authentication ticket via the klist command.

Now open a new browser session and access the Fusion installation, <domain>:<UI port>.

This should take you directly to the main Fusion panel, bypassing the the Fusion "Welcome" login panel. To view your login profile, click on the profile icon on the top nav bar. Your user name should be your login name + "@" + your domain name.

If instead, you see the Fusion login panel, your browser is not configured for SPNEGO.

If the Fusion display consists only of an empty top nav bar, this indicates an authentication failure. Check that the path to your keytab file is correct. Then check the Fusion logs.

If your KDC uses "AES256 CTS mode with HMAC SHA1-96" for key encryption, the proxy will log this error when attempting to authenticate:

GSSException: Failure unspecified at GSS-API level (Mechanism level: Encryption type AES256 CTS mode with HMAC SHA1-96 is not supported/enabled)

To get around this, the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy File will need to be downloaded and installed. It can be downloaded from:

Place the jars in your JAVA_HOME/jre/lib/security/ directory, then restart Fusion.

Clicking on the "logout" icon on the top nav bar (rightmost icon or a padlock) takes you back to the main Fusion panel. If you destroy your Kerberos credentials cache via the "kdestroy" command, the next time you logout of Fusion, you will be logged out and the browser will display the Fusion login panel.