Checkmk
DeutschEspañolFrançaisItaliano日本語
Cloud (SaaS) master2.3.02.2.02.1.02.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.

  • On the Checkmk server the module libapache-mod-auth-kerb is installed (or mod_auth_kerb under Red Hat Enterprise Linux and CentOS or apache2-mod_auth_kerb under SUSE).

  • 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.

Optional:

If you want users without SSO to still be able to log in via the regular login page, cookie authentication must be enabled.

2. Kerberos integration

To switch Checkmk to authentication via Kerberos, delete the ~/etc/apache/conf.d/auth.conf file and rewrite it. The entries at the beginning of the following file contents are only examples. Therefore, modify all lines that begin with the Define expression to suit your environment:

~/etc/apache/conf.d/auth.conf
Define SITE MyCheckmkSite
Define REALM MyRealm.org
Define SERVICENAME myservice.mydomain.tld
Define KEYTAB /omd/sites/${SITE}/etc/apache/cmk_http.keytab

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

<Location /${SITE}>
  <If "! %{HTTP_COOKIE} =~ /^(.*;)?auth_${SITE}/ && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/register_agent.py' && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/deploy_agent.py' && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/run_cron.py' && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/restapi.py' && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/webapi.py' && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/automation.py' && \
    ! %{REQUEST_URI} -strmatch '/${SITE}/check_mk/api/*' && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/ajax_graph_images.py' && \
    ! %{QUERY_STRING} =~ /(_secret=|auth_|register_agent)/ && \
    ! %{REQUEST_URI} =~ m#^/${SITE}/(omd/|check_mk/((images|themes)/.*\.(png|svg)|login\.py|.*\.(css|js)))# ">
  Order allow,deny
  Allow from all
  Require valid-user

  AuthType Kerberos
  AuthName "Checkmk Kerberos Login"

  KrbMethodNegotiate on
  KrbMethodK5Passwd off
  KrbLocalUserMapping on


  # Environment specific: Path to the Keytab, Realm and ServicePrincipal
  KrbAuthRealm ${REALM}
  KrbServiceName HTTP/${SERVICENAME}@${REALM}
  Krb5Keytab ${KEYTAB}

  # When Kerberos auth fails, show the login page to the user
  ErrorDocument 401 '<html> \
      <head> \
        <meta http-equiv="refresh" content="1; URL=/${SITE}/check_mk/login.py"> \
      </head> \
      <body> \
        Kerberos authentication failed, redirecting to login page. \
        <a href="/${SITE}/check_mk/login.py">Click here</a>. \
      </body> \
    </html>'
  </If>
</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>
Copy file content to clipboard
Successfully copied file content to clipboard!
Write access to clipboard has been denied!

Once the sample configuration shown has been executed, only authentications via Kerberos will be permitted. You must now decide whether you want to continue to support basic auth with or without cookies — for users without SSO, or as a fallback. What you will need to configure for this is explained in the following two chapters.

3. Allow basic authentication

If you want to continue to allow authentication via basic auth in addition to SSO via Kerberos, you need to edit one line in the above configuration.

To do this, change the value in the following line to on:

~/etc/apache/conf.d/auth.conf
  KrbMethodK5Passwd on
Copy file content to clipboard
Successfully copied file content to clipboard!
Write access to clipboard has been denied!

To make authentication more convenient, Checkmk also supports logging in via a cookie. In a new and unmodified Checkmk site this is currently the default.

Last but not least, you should check if this authentication option is still enabled and whether it should stay that way.

You can check the current state of your site with the following command:

OMD[mysite]:~$ omd config show MULTISITE_COOKIE_AUTH
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

If you receive an on value here and want to keep cookie authentication enabled — for example as a fallback — nothing more needs to be done at this point.

If, on the other hand, you want to disable MULTISITE_COOKIE_AUTH, this can be performed with the following command:

OMD[mysite]:~$ omd config set MULTISITE_COOKIE_AUTH off
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

Then delete the cookie_auth.conf file from the site’s Apache directory:

OMD[mysite]:~$ rm ~/etc/apache/conf.d/cookie_auth.conf
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!

5. Diagnostics

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

root@linux# kinit -p username
root@linux# klist
Copy command(s) to clipboard
Successfully copied command(s) to clipboard!
Write access to clipboard has been denied!
Last modified: Tue, 09 Sep 2025 13:58:12 GMT via commit c78e3230
On this page