Kerberos Integration

Summary

This document is a working example describing the SSO configuration for the following setup:

• Active Directory with 2 domains
• the DNS names are different from AD domain name
• Thruk
• apache module mod_auth_kerb and Kerberos itself are from the OS distribution

The idea presented here is to have a single SSO master site where the Kerberos configuration and keytab are maintained. These are owned by the OMD group, which is common for all sites and thus all the other sites are then able to switch to kerberos or back independently if needed. The keytab must be updated in case AD password changes. As the keytab represents the Kerberos identity of the server, it is strongly recommended to have a dedicated AD account, which have the most minimal permissions only.

Environment

The following values are used in the examples in this document:

These values must be changed in your environment accordingly.

Active Directory

Create a new account ADEMEA\service_omd in the first AD domain. The account does not need any special permissions within AD.

Add the SPNs with the name of the Thruk host to the account created, for instance using setspn on the domain controller of the first domain:

setspn -s HTTP/linuxsrv1 ADEMEA\service_omd
setspn -s HTTP/linuxsrv1.intra.company ADEMEA\service_omd

OMD host

Install the apache module apache2-mod_auth_kerb on the Thruk host. There might be further packages needed as dependencies.

OMD SSO Site (site00)

Create a new OMD site where the keytab will be stored for all the sites on the host where SSO is required:
omd create site00

Save your ssh public key into ~/.ssh/authorized_keys on the site. The SSH login with keys is needed as the OMD site users have no password.

Create the directory ~/etc/krb/ in the site where keytab and krb5.conf will be stored
mkdir ~/etc/krb

Create the krb5.conf file under ~/etc/krb/. The example content is given below.

Set the environment variable KRB5_CONFIG at the bottom in the .profile pointing to the krb5.conf:
export KRB5_CONFIG=/opt/omd/sites/site00/etc/krb/krb5.conf

Logout, login again as the site user per SSH and check that KRB5_CONFIG is set
env | grep KRB5_CONFIG

Create the keytab file:

• initialize Kerberos
  kinit –f ADEMEA\service_omd
• find out the KVNO number as it is needed in the next step for the “-k” option
  kvno HTTP/linuxsrv1
• launch ktutil and create the keytab within ktutil, using KVNO from the previous step. You will be prompted for the password of the AD account holding SPNs:
  addent -password –e rc4-hmac -k 4 –p HTTP/linuxsrv1 addent -password –e rc4-hmac -k 4 –p HTTP/linuxsrv1.intra.company list wkt /opt/omd/sites/site00/etc/krb/linuxsrv1.keytab quit

Change permissions of the folder ~/etc/krb/ and files krb5.conf and keytab therein to be readable by the omd group
chgrp –R omd /opt/omd/sites/site00/etc/krb chmod –R 640 /opt/omd/sites/site00/etc/krb

Set Thruks cookie authentication in sso-mode. This will verify existing cookies or api keys, but pass through kerberos
authenticated users.
omd config set THRUK_COOKIE_AUTH sso-support

Note: with OMD 2.x or Apache 2.2 you have to disable Thruks cookie authentication completely.

Comment out the basic authentication und insert Kerberos configuration in ~/etc/apache/conf.d/auth.conf. The example content is given below.

Start or restart OMD site and open it in the browser via alias name

• https://thruk/site00/
• https://thruk.intra.company/site00/

OMD other sites

After the SSO master site is ready, each site on the host which needs SSO can be configured in three simple steps:
- KRB5_CONFIG entry in .profile pointing to the krb5.conf in the SSO site
export KRB5_CONFIG=/opt/omd/sites/site00/etc/krb/krb5.conf
- Deactivate cookie authentication
omd config set THRUK_COOKIE_AUTH off
- Modify auth.conf under ~/etc/apache/conf.d/

Example krb5.conf

[logging]
default = FILE:/omd/sites/site00/var/log/kerberos.log

[libdefaults]
ticket_lifetime = 24000
default_realm = EMEA.COMPANY.COM
dns_lookup_realm = false
dns_lookup_kdc = true

[realms]
EMEA.COMPANY.COM = {
  kdc = emea.company.com:88
  auth_to_local = RULE:[1:$1@$0](.*@EMEA\.COMPANY\.COM)s/A/a/g s/B/b/g s/B/b/g s/C/c/g s/D/d/g s/E/e/g s/F/f/g s/G/g/g s/H/h/g s/I/i/g s/J/j/g s/K/k/g s/L/l/g s/M/m/g s/N/n/g s/O/o/g s/P/p/g s/Q/q/g s/R/r/g s/S/s/g s/T/t/g s/U/u/g s/V/v/g s/W/w/g s/X/x/g s/Y/y/g s/Z/z/g s/@.*/@EMEA/
  auth_to_local = RULE:[1:$1@$0](.*@APAC\.COMPANY\.COM) s/A/a/g s/B/b/g s/B/b/g s/C/c/g s/D/d/g s/E/e/g s/F/f/g s/G/g/g s/H/h/g s/I/i/g s/J/j/g s/K/k/g s/L/l/g s/M/m/g s/N/n/g s/O/o/g s/P/p/g s/Q/q/g s/R/r/g s/S/s/g s/T/t/g s/U/u/g s/V/v/g s/W/w/g s/X/x/g s/Y/y/g s/Z/z/g s/@.*/@APAC/
  auth_to_local = DEFAULT
}
APAC.COMPANY.COM = {
  kdc = apac.company.com:88
}

[domain_realm]
.intra.company = EMEA.COMPANY.COM
intra.company = EMEA.COMPANY.COM

Notes:
- all the regex transformations, even those for further domains must all be en-tered inside the entry for the first realm
- the entry “auth_to_local = DEFAULT” is sufficient and the usernames will ap-pear as “USER@EMEA.COMPANY.COM” or “US-ER2@APAC.COMPANY.COM”
- with the regex chains s/A..Z/a…z/g the user names will be transformed to low-er case, i.e. USER=>user
The same can be achieved in the Thruk via setting one of the options make_auth_user_uppercase/ make_auth_user_lowercase to 1 in ~/etc/thruk/thruk.conf
- the last regex (s/@.*/@APAC/) augments the user name with the string and thus allows to distinguish users based on realm

Example auth.conf

# General auth configuration for this site
#

<IfModule !mod_auth_kerb.so>
  LoadModule auth_kerb_module /usr/lib64/apache2/mod_auth_kerb.so
</IfModule>

# required if user is in many ad groups
LimitRequestFieldSize 16384

<Location "/${OMD_SITE}">
  AuthName "OMD Monitoring Site ${OMD_SITE}"
  AuthType Kerberos
  KrbAuthRealm EMEA.COMPANY.COM
  KrbMethodNegotiate on
  KrbSaveCredentials off
  KrbMethodK5Passwd off
  KrbLocalUserMapping on
  KrbVerifyKDC on
  Krb5Keytab /opt/omd/sites/site00/etc/krb/linuxsrv1.keytab
  KrbServiceName HTTP/linuxsrv1.intra.company@EMEA.COMPANY.COM
  Require valid-user

  # with apache 2.4 and thruk cookie auth set to sso-support, api keys can
  # be enabled with these additional settings:
  #Require expr %{HTTP_COOKIE} =~ /thruk_auth=/
  #Require expr %{HTTP:X-Thruk-Auth-Key} != ""

  # apache 2.2 requires additional settings
  #Order allow,deny
  #Satisfy Any
</Location>

Notes:
- the path to mod_auth_kerb.so may vary depending on the linux distribution used