Single Sign-On with Kerberos

Check_MK Manual

Search in the manual

This article is just a draft and not yet finished!

Important: This article only explains the currently available knowledge, and thus should be enjoyed with some caution! Although there are in fact Check_MK instances already running with this configuration, comprehensive tests have yet to be carried out. So despite this tutorial Kerberos is not officially supported by Check_MK.

The following prerequisites must be satisfied before the configuration in Check_MK can be retroactively altered to SSO (Single Sign-On) with Kerberos:

  • The Apache-Version is 2.4 or newer.
  • The libapache-mod-auth-kerb (e.g., mod_auth_kerb under RHEL/CentOS, or apache2-mod_auth_kerb under SUSE) module is installed on the Check_MK server.
  • The Kerberos client is istalled and configured on the Check_MK server.
  • A Keytab has been installed and may be read by the site user.
  • The Check_MK server has been set up as the Service Principal.
  • The client's browser has been configured for access using Kerberos.
  • The Check_MK instance is on Cookie-Auth

The last point ensures that users without SSO can log in over the regular login window. This option can also be deactivated. The prerequisite of course does not apply in such a case.

1. Integrating Kerberos

To switch Check_MK to authentification over Kerberos, migrate the site user to the Apache directory, and archive the cookie_auth.conf file out of the system – this file will no longer be required.

OMD[mysite]:~$ mv etc/apache/conf.d/auth.conf /tmp/

The auth.conf file will subsequently be deleted and recreated. Adapt the path being used to conform to the system's environment, and substitute the KrbAuthRealm and the value of the SITE variable to suit the environment:

Define SITE mysite

<IfModule !mod_auth_kerb.c>
   LoadModule auth_kerb_module /usr/lib/apache2/modules/

<Location /${SITE}>
  Order allow,deny
  Allow from all

  AuthType Kerberos
  AuthName "Check_MK Kerberos Login"
  KrbServiceName HTTP
  KrbMethodNegotiate on
  KrbMethodK5Passwd off
  KrbLocalUserMapping on
  KrbSaveCredentials on

  # Use Kerberos auth only in case there is no Check_MK authentication
  # cookie provided by the user
  Require expr %{HTTP_COOKIE} =~ /auth_/
  Require expr %{REQUEST_URI} = "/${SITE}/check_mk/"
  Require expr %{QUERY_STRING} =~ /(_secret=|auth_|register_agent)/
  Require valid-user

  # Environment specific: Path to the keytab and the realm
  Krb5Keytab /etc/apache2/krb5.keytab.f-mk-mon-p01

  # When Kerberos auth fails, show the login page to the user
  ErrorDocument 401 /${SITE}/check_mk/

# These files are accessible unauthenticated (login page and needed ressources)
<LocationMatch /${SITE}/(omd/|check_mk/(images/.*\.png|login\.py|.*\.(css|js)))>
  Order allow,deny
  Allow from all
  Satisfy any

2. Cookie based Logins

If you want to only allow logins over SSO, deactivate the Cookie-Auth. Note that this option can only be changed when the instance is stopped:

OMD[mysite]:~$ omd config set MULTISITE_COOKIE_AUTH off

The following line can also be omitted from or commented out in the auth.conf as appropriate:

#  Require expr %{HTTP_COOKIE} =~ /auth_/