Kerberos

This page discusses Stardog’s support for Kerberos as a means for authenticating users.

Page Contents

1. Overview
   1. How Kerberos Works
2. Known Limitations
3. Configuration Properties
4. Setup Guide
   1. Step 1: Create a Keytab File
      1. MIT Kerberos Environment
      2. Active Directory Environment
   2. Step 2: Create a Stardog Admin User
   3. Step 3: Configure Stardog
   4. User Management
5. Set up Kerberos Authentication for Stardog Applications
   1. Configuration of stardog.properties for Stardog applications
   2. Workstation configuration

---

Overview

Kerberos is a strong authentication system with a central key management server. It is the authentication protocol implemented by Microsoft’s Active Directory and is common in enterprises that use Windows. There is also a popular open source MIT implementation used by many companies interested in strong authentication.

Stardog can be configured to run in both MIT and Active Directory Kerberos environments. In order to do so, a keytab file must be properly created.

How Kerberos Works

Every Kerberos deployment, called a realm, has a central key management server called the Key Distribution Center (KDC). The KDC stores details about users including their usernames and passwords. The password acts as a shared secret between the user and the KDC. A person uses that password to create a time-boxed ticket which is then automatically used to prove their identity to any other server in the realm, establishing a “single sign-on” mechanism.

Servers in a Kerberos realm must also have a shared secret, typically kept in a file called a keytab. The keytab file stores an encrypted hash of a password associated with each server, allowing servers to participate in third-party mediated authentication without human intervention.

When a client wants to authenticate with a server, it first requests a ticket by communicating with the KDC and proving it has the right password. It also tells the KDC which server it wants to communicate with. The KDC then creates an encrypted payload containing the client’s identity, encrypted with the server’s key. The client passes this payload to the server, which can decrypt it without additional communication with the KDC and trust the client’s identity. Authorization decisions are then made by the server.

Known Limitations

Kerberos authentication can cause instability, when used with the High Availability Cluster and certain features like the query log or knowledge catalog. If you are interested in using Kerberos in a clustered environment, please contact Stardog support for guidance. We recommend using OAuth for authentication in a clustered environment.

Configuration Properties

Once the keytab file is acquired, the following server properties can be set in stardog.properties.

Note that enabling Kerberos will disable username / password based authentication by default. This can be overridden via setting security.disable.password=false in stardog.properties.

For more details about configuring these values, see our example stardog.properties file.

Setup Guide

Setting up Kerberos with Stardog involves three steps:

1. Run a Stardog server with a proper license on your network.
2. Create a keytab file for the Stardog instance.
3. Configure Stardog to use the Kerberos realm.

Step 1: Create a Keytab File

The steps to create a keytab file differ depending on your Kerberos implementation.

MIT Kerberos Environment

If your Kerberos realm uses the MIT implementation, you can create the keytab file from the Linux server that will run Stardog, but you will need administrator access to the KDC.

First, create a principal for the server. The principal is the identity of the server in the realm and should follow this format: HTTP/<canonical DN of the Stardog host>@<REALM NAME> (for example, HTTP/demo1.stardog.com@REALM1.STARDOG.COM).

Create the principal:

$ kadmin -p <admin principal> -q "addprinc -randkey HTTP/<DN of the Stardog host>"

Extract the keytab file:

$ kadmin -p <admin principal> -q "ktadd -k <output keytab file> HTTP/<DN of the Stardog host>"

Active Directory Environment

To create a keytab file in an Active Directory setup, log into a Windows machine with an account that has admin rights to create users.

Go to Start > Windows Administration Tools > Active Directory Users and Computers and add a user under the Kerberos realm. This user will be the principal associated with the Stardog server.

Once the principal exists, open a command prompt and run:

$ ktpass -princ HTTP/<DN of the Stardog host>@<REALM NAME> -mapuser <user name>@<REALM> -pass <some password> -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -out <output keytab file>

This command maps the newly created user name to the publicly visible principal (HTTP/<DN of the Stardog host>@<REALM NAME>).

Store the newly created keytab file securely in both cases.

Step 2: Create a Stardog Admin User

There must be an admin user for the Stardog server in the Kerberos realm. You can use the admin user for the existing realm or create a new one. If creating a new user, follow the principal creation instructions above with a different user name.

Step 3: Configure Stardog

Copy the keytab file to the machine where Stardog is installed and add the following to ${STARDOG_HOME}/stardog.properties:

krb5.principal = HTTP/<DN of the Stardog host>@<REALM NAME>
krb5.debug = true
krb5.keytab = <path to the keytab file>
krb5.admin.principal = <admin principal>

Start Stardog and verify Kerberos is working:

$ kinit admin/stardog

$ stardog-admin --krb5 --krb5-disable-rdns user list
+-----------+
| Username  |
+-----------+
| admin     |
| anonymous |
+-----------+

User Management

Stardog users in a Kerberos environment are created and managed the same way as regular Stardog users, as described in Managing Users and Roles. The only requirement is that usernames must match the corresponding Kerberos principal names.

Set up Kerberos Authentication for Stardog Applications

You can configure your Stardog instance to authenticate via Kerberos when using Stardog Cloud.

Once the additional stardog.properties options are added as specified below, your browser should be able to negotiate with Kerberos credentials. To authenticate to a Stardog application via Kerberos, leave the username and password fields blank in the connection dialog and enter the endpoint url for your Stardog instance. When there is no username or password, Studio will attempt to connect using browser credentials.

Configuration of stardog.properties for Stardog applications

Once Kerberos authentication is set up, the following options can be set in stardog.properties for Explorer and Studio.

Browsers and Stardog will not allow cors.allowed.origins to be set to * when cors.allow.credentials is set to true, as it may expose credentials to malicious hosts.

Workstation configuration

In most cases, the workstation should be properly configured for Kerberos Authentication; however, it may be necessary to instruct your browser to whitelist the domain. This is usually the case if the host machine is not on the same domain as the Kerberos server. Set the following for your browser:

For Chrome:

$ defaults write com.google.Chrome AuthServerWhitelist "*.example.com"
$ defaults write com.google.Chrome AuthNegotiateDelegateWhitelist "*.example.com"

For Firefox:

1. From the browser, visit about:config.
2. For network.negotiate-auth.delegation-uris and network.negotiate-auth.trusted-uris, set the domain against which you want to authenticate, for example, example.com.

---