openproject/docs/system-admin-guide/authentication/kerberos/README.md

sidebar_navigation	description	robots	keywords
[{title Kerberos} {priority 800}]	How to set up integration of Kerberos for authentication with OpenProject.	index, follow	Kerberos, authentication

Kerberos integration

**Note**: This documentation is valid for the OpenProject Enterprise Edition only.

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/includes/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
    KrbAuthRealm 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.

You can do that in two ways:

Configure using the configuration.yml

In your OpenProject packaged installation, you can modify the /opt/openproject/config/configuration.yml file. This will contain the complete OpenProject configuration and can be extended to include a section for the header checking.

production:
  # <-- other configuration -->

  auth_source_sso:
    # The header name is configured here
    header: X-Authenticated-User

    # The secret is configurable here
    # You can comment it out to disable if your outer server
    # fully controls this header value and you trust it.
    secret: MyPassword

    # Uncomment to make the header optional.
    # optional: true

    # Specify a logout URL that gets redirected
    # after the OpenProject internal logout flow
    # logout_url: https://sso.example.com/logout

Be sure to choose the correct indentation and base key. The auth_source_sso key should be indented two spaces (and all other keys accordingly) and the configuration should belong to the production group.

The configuration can be provided in one of three ways:

• configuration.yml file (1.1)
• Environment variables (1.2)
• settings.yml file (1.3)

Whatever means are chosen, the plugin simply passes all options to omniauth-saml. See their configuration documentation for further details.

The three options are mutually exclusive. I.e. if settings are already provided via the configuration.yml file, settings in a settings.yml file will be ignored. Environment variables will override the configuration.yml based configuration, though.

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 that every underscore (_) in the original configuration key has to be replaced by a duplicate underscore (__) in the environment variable 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

• Kerberos documentation by Ubuntu