Kerberos integration

Kerberos allows you to authenticate user requests to a service within a computer network. You can integrate it with OpenProject with the use of Kerberos Apache module (mod_auth_kerb) plugging into the OpenProject packaged installation using Apache web server.

This guide will also apply for Docker-based installation, if you have an outer proxying server such as Apache2 that you can configure to use Kerberos. This guide however focuses on the packaged installation of OpenProject.

Step 1: Creating Kerberos service and keytab for OpenProject

Assuming you have Kerberos set up with a realm, you need to create a Kerberos service Principal for the OpenProject HTTP service. In the course of this guide, we’re going to assume your realm is EXAMPLE.COM and your OpenProject installation is running at openproject.example.com.

Create the service principal (e.g. using kadmin) and a keytab for OpenProject used for Apache with the following commands:

# Assuming you're in the `kadmin.local` interactive command

addprinc -randkey HTTP/openproject.example.com
ktadd -k /etc/openproject/openproject.keytab HTTP/openproject.example.com

This will output a keytab file for the realm selected by kadmin (in the above example, this would create all users from the default_realm) to /etc/openproject/openproject.keytab

You still need to make this file readable for Apache. For Debian/Ubuntu based systems, the Apache user and group is www-data. This will vary depending on your installation

sudo chown www-data:www-data /etc/openproject/openproject.keytab
sudo chmod 400 /etc/openproject/openproject.keytab

Step 2: Configuration of Apache web server

First, ensure that you install the mod_auth_kerb apache module. The command will vary depending on your installation. On Debian/Ubuntu based systems, use the following command to install:

sudo apt-get install libapache2-mod-auth-kerb

You will then need to add the generated keytab to be used for the OpenProject installation. OpenProject allows you to specify additional directives for your installation VirtualHost.

We are going to create a new file /etc/openproject/addons/apache2/custom/vhost/kerberos.conf with the following contents.

  <Location />
    AuthType Kerberos
    # The Basic Auth dialog name shown to the user
    # change this freely
    AuthName "EXAMPLE.COM realm login"

    # The realm used for Kerberos, you will want to
    # change this to your actual domain
    KrbAuthRealms EXAMPLE.COM

    # Path to the Keytab generated in the previous step
    Krb5Keytab /etc/openproject/openproject.keytab

    # After authentication, Apache will set a header
    # "X-Authenticated-User" to the logged in username
    # appended with a configurable secret value
    RequestHeader set X-Authenticated-User expr=%{REMOTE_USER}:MyPassword

    # Apache directive to ensure a user is authenticated
    Require valid-user
  </Location>

Step 3: Configuration of OpenProject to use Apache header

As the last step, you need to tell OpenProject to look for the X-Authenticated-User header and the MyPassword secret value. The easiest way to do that is using ENV variables

Configure using environment variables

As with all the rest of the OpenProject configuration settings, the Kerberos header configuration can be provided via environment variables. For example:

openproject config:set OPENPROJECT_AUTH__SOURCE__SSO_HEADER="X-Authenticated-User"
openproject config:set OPENPROJECT_AUTH__SOURCE__SSO_SECRET="MyPassword"

In case you want to make the header optional, i.e. the header may or may not be present for a subset of users going through Apache, you can set the following value:

  openproject config:set OPENPROJECT_AUTH__SOURCE__SSO_OPTIONAL=true

Please note the differences between single underscores (_) and double underscores (__) in these environment variables, as the single underscore denotes namespaces.

Step 4: Restarting the server

Once the configuration is completed, restart your OpenProject and Apache2 server with service openproject restart and service apache2 restart . Again these commands might differ depending on your Linux distribution.

Step 5: Logging in

From there on, you will be forced to the Kerberos login flow whenever accessing OpenProject. For existing users that will be found by their login attribute provided in the X-Authenticated-User, they will be automatically logged in.

For non-existing users, if you have an LDAP configured with automatic user registration activated (check out our LDAP authentication guide for that), users will be created automatically with the attributes retrieved from the LDAP.

Additional resources