Checkmk
Deutsch
master2.3.0-betalatest (2.2.0)2.0.01.6.0
to checkmk.com

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 installed and configured on the Checkmk server.

  • A Keytab — e.g. as /etc/krb5.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 authentication 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. The bold entries are just examples and may differ from your configuration. Adapt these according to your environment:

~/etc/apache/conf.d/auth.conf
Define SITE *MyCheckmkSite*
Define REALM *MyRealm.org*

<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 "Checkmk Kerberos Login"
  KrbServiceName HTTP
  KrbMethodNegotiate on
  KrbMethodK5Passwd off
  KrbLocalUserMapping on
  KrbSaveCredentials on

  # Use Kerberos auth only in case there is no Checkmk 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/krb5.keytab*
  KrbAuthRealm ${REALM}

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

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_/

4. Diagnostics

You can check with the following commands, if your Kerberos setup is working:

root@linux# kinit -p username
root@linux# klist
On this page