We use cookies to ensure that we give you the best experience on our website. Visit our Privacy Policy to learn more. If you continue to use this site, we will assume that you are okay with it.

Your choices regarding cookies on this site.
Your preferences have been updated.
In order for the changes to take effect completely please clear your browser cookies and cache. Then reload the page.

Single Sign-On with Kerberos

Checkmk Manual

Search in the manual

This article is just a draft and not yet finished!

1. Introduction

A single sign-on to the GUI of Checkmk with Kerberos is not officially supported by Checkmk, but you can easily set it up yourself. These instructions will show you how to do this.

The following prerequisites must be satisfied before the configuration in Checkmk 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 Checkmk server.
  • The Kerberos client is istalled and configured on the Checkmk server.
  • A Keytab has been installed and may be read by the site user.
  • The Checkmk server has been set up as the Service Principal.
  • The client's browser has been configured for access using Kerberos.
  • The Checkmk 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.

2. Integrating Kerberos

To switch Checkmk 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:

~/etc/apache/conf.d/auth.conf
Define SITE mysite

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

<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/register_agent.py"
  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
  KrbAuthRealm MYCOMPANY.ORG

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

# 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
</LocationMatch>

3. 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:

~/etc/apache/conf.d/auth.conf
#  Require expr %{HTTP_COOKIE} =~ /auth_/