Product Selector

Fusion 5.12
    Fusion 5.12

    Configure Fusion for Kerberos in Unix

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

    Kerberos support requires Fusion 5.9.5.

    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 does not display the initial sign-on panel; instead on login, the user sees the main Fusion collections panel.

    This article focuses on configuring Fusion for Kerberos in Unix. To learn how to configure Fusion for Windows, see Configure Fusion for Kerberos in Windows.

    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. This is usually a combination of kerberos. and your domain name. For example, kerberos.example.com

    • 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. This 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 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 have 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.

      The following encryption types are not supported by Fusion:

      • DES-CBC-CRC

      • DES_CBC_MD5

      • Microsoft Windows 2000 RC4-HMAC

    • "-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 are in - you will 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:

    1. Log in to Fusion as "admin" or as a user who has super-admin privileges.

    2. In the left-hand side navigation bar, click System > Access control.

    3. Click the Security Realms tab, then Add Security Realm.

    4. 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".

    5. Choose a realm name, and make sure the "enabled" box is checked.

    6. If the auto-created box is unchecked, a user with admin privileges will need to create Fusion user accounts.

    7. Select default roles. The default roles are assigned to a user the first time 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 are added to the set of Fusion users as username "any.user@MYORG.ORG" and they 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.

      The Fusion proxy Kerberos realm works only with one Fusion host. For a multi-node Fusion cluster where each node resides on a different host, configure a separate realm for each host with a dedicated service/principal.

    8. Enter the service principal and the full path to the keytab file.

    9. Click Save. Fusion displays a confirmation message.

    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"

    For more information, see Using a Web Browser to Access an URL Protected by Kerberos HTTP SPNEGO and Authentication + Authorization.

    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 do not 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 as follows:

    1. Log out of Fusion and shut down the browser.

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

    3. Open a new browser session and access the Fusion installation.

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

      • If you see the Fusion login panel instead of the main Fusion 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 a weak encryption method, Fusion rejects your login credentials. The following weak encryption types are disabled in Fusion:

        • DES-CBC-CRC

        • DES_CBC_MD5

        • Microsoft Windows 2000 RC4-HMAC

    References and Tutorials