Is checkmk SAML 2.0 capable?

Hi,

I don´t know how to check this. My company is enabling this kind of security and they have asked me if checkmk is SAML 2.0 capable.

Does anybody know how to check this?

You would need to configure SAML in the site’s Apache yourself.

The Kerberos chapter in the manual may be a template for that: Using Kerberos in Checkmk

Afaik Checkmk 2.0 comes with the packages required to do SAML.
@gulaschcowboy implemented it and has written an internal guide how to do this. If he says, that this is still valid, we can make a blog article out of it.

2 Likes

Yes please. That would be great!

Yes, in 2.0 we ship the site apache with the required mod_auth_mellon and final documentation is already being written. It will be published on docs.checkmk.com soon.

7 Likes

Any update on this? I’m very interested in integrating SAML with our CheckMK install!

@Oregano For your info :
mod_auth_mellon works perfectly, when authenticating (on a CentOS8 box) and introducing it to the global config of Apache/httpd.

@gulaschcowboy I just need to know what CheckMK expects in the assertion.

One warning tho : If you are running (like i do) a Microfocus (formerly NetIQ) AccessManager as an IdP then the default lasso package ( v 2.6.0 ) will break it.
For it work you require v 2.6.1 of the lasso package.
i retrieved mine from https://lemonldap-ng.org/redhat/extras/8/x86_64/

The docs team is busy updating the entire docs to CMK 2.0. This is the priority at the moment.
@gulaschcowboy can I just post your guide in here as a pdf?

It is to use at your own risk then however.

@martin.hirschvogel OK, fine for me.

Please use the following guide with caution and give feedback, if it worked:
How-to implement SAML with ADFS authentication in Checkmk
@Oregano @Glowsome @MightyDinosaurus

1 Like

@martin.hirschvogel @gulaschcowboy

I was well underway, however i implemented the authentication on the global apache env following the general documentation of mod_auth_mellon.

This is how my /etc/http/conf.d/mellon.conf looks :

<Location / >
    MellonEnable info
    MellonEndpointPath /mellon/
    MellonSPentityId            "https://monitor.myorg.nl/mellon/metadata"
    MellonSPCertFile            /etc/httpd/saml2/certificate.crt
    MellonSPPrivateKeyFile      /etc/httpd/saml2/certificate.key

    MellonIdPMetadataFile       /etc/httpd/saml2/idp_metadata.xml

    # This information is required to be present in the configfile if we let SP metadata be generated
    # automatically.
    MellonOrganizationName      "nl" "MyOrg"
    MellonOrganizationURL       "nl" "https://www.myorganisation.nl"
    MellonOrganizationDisplayName "nl" "MyOrg"

    MellonVariable "cookie"
    MellonSecureCookie On
    MellonCookiePath /
    MellonCookieSameSite lax
    # My assertion contains the scope 'profile' where the username is in either 'preferred_username'
    # or 'nickname'
    MellonUser "nickname"

</Location>

#Not tested yet to make it dynamic, i only have one site
<Location /sitename >
    AuthType Mellon
    MellonEnable auth
    Require valid-user
    
    RequestHeader set X-Remote-User "expr=%{REMOTE_USER}"
</Location>

Combined with the enabling of the 'Authenticate users by incoming HTTP requests ( X-Remote-User) in CMK it works flawless.

One thing would be a nice-to-have, and that is when one uses the logout it will not logout the user on the IdP … so SLO still needs work on this…

When SAML is configured, will the authentication for automation users via url arguments still work?
edit: probably not, but mellon can be combined with basic auth.

@mace If you look at the provided pdf (for ADFS) a whitelist section is there :

# Use SAML auth only in case there is no Check_MK authentication
# cookie provided by the user and whitelist also some other required URLs
<If "! %{HTTP_COOKIE} =~ /auth_/ && \
    ! %{REQUEST_URI} = '/${SITE}/check_mk/register_agent.py' && \ 
    ! %{REQUEST_URI} = '/${SITE}/check_mk/run_cron.py' && \
    ! %{QUERY_STRING} =~ /(_secret=|auth_|register_agent)/ && \
    ! %{REQUEST_URI} =~ m#^/${SITE}/(omd/|check_mk/(images/.*\.png|login\.py|.*\.(css|js)))# ">

This should allow automation to not be affected by the implementation of SAML.

@martin.hirschvogel, @gulaschcowboy :
Regarding the made available pdf and comparing it to my setup i suggest the following additions:

  • Generalise documentation towards the Service Provider end, and focus on the attribute (obtained via assertion) from the IdP which needs to be put into the header as X-Remote-User.
  • section #2 - when using (under CentOS8) i needed to put in the full path of mellon_create_metadata.sh
    => in my case it was in /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh
  • section #2 - (renameing generated key/cert for saml) generalising key/crt names can work, but imho i prefer descriptive names - especially in multisite-environments.(more an opinion)
  • section #2 the directives given in the conf file should contain :
    MellonOrganizationName "countrycode" "MyOrg"
    MellonOrganizationURL "countrycode" "https://www.myorganisation.tld"
    MellonOrganizationDisplayName "countrycode" "MyOrg"

Without it my IdP moans and will not accept the metadata when importing it (via url or other means)

  • section #2 - mention of mellon diagnostics - for CentOS(8) this means one needs to additionally install mod_auth_mellon-diagnostics, next tot he mention of the module required to load in the IF-clause needs to be changed to : LoadModule auth_mellon_module modules/mod_auth_mellon-diagnostics.so
    Without the addition no diagnostic logging will be provided (as its not compiled in the standard module)
  • section #2 - the directive MellonIdPPublicKeyFile is only required if the IdP metadata does not contain/provide it.
  • General - split off IdP configuration per vendor in a separate document, making the Check_MK documentation as a SAML ServiceProvider more generic then writing a guide for each type of IdP.
    => As for Check_MK the only thing that matters is at the moment is the header being set to the correct X-Remote-User name it all depends on how an IdP offers this information.
1 Like

Seems the more i am getting involved in this the more possibilities and configuration differences i am seeing depending on both IdP being used aswell as the underlying OS of the SP.

So researching as i go/progress in this matter.

One thing is curious/ vendor specific it seems :
# Even tho it is set as ‘optional’ in https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
# a Microfocus AccessManager requires it to be set.
# Specified in saml link above - line 396
MellonOrganizationName “<your_countrycode>” “<your_organisation-name>”
# Specified in saml link above - line 443 / 452
MellonOrganizationURL “<your_countrycode>” “<your_organisation-url>”
# Specified in saml link above - line 454
MellonOrganizationDisplayName “<your_countrycode>” “<your_organisation-displayname>”

1 Like

Cool, thanks!
@fayepal can you move (some of) this thread into the how-to section? Then we can refer anyone to this for the time being.

@martin.hirschvogel , @fayepal i would like to assist you in getting this howto-section into order for multiple IdP’s.

In looking at the PDF i have been working in trying to setup/document the auth.conf part to incorporate multiple scenarios ( so not only ADFS) …

Finished configging and tested it, (as in multisite setup / no longer in the global config of the httpd server) - it again works flawlessly.
One Note again : with a generated certificate i still needed to upload the SP certificate into the trust-store ( my IDP does check the chain), so this needs to be mentioned somewhere.

My auth.conf ( inside the OMD site) at current :

# Set this to the Name of your Checkmk site, e.g.# Define SITE mysite
# Define SITE mysite

Define SITE mysite

# ServerName from listen-ports.conf needs to be overwritten here
# and being set to the URL of the real server.

# auth_mellon uses this to generate the needed URLs in the metadata.

ServerName https://myserver.mydomain.org

# Load the module from the system's Apache/httpd location as we don't ship
# mod_auth_mellon within OMD yet.

<IfModule !mod_auth_mellon.c>
    # Use this line on Debian based systems.
    #LoadModule auth_mellon_module /usr/lib/apache2/modules/mod_auth_mellon.so

    # Use this line on  CentOS 7 / 8
    #LoadModule auth_mellon_module /usr/lib64/httpd/modules/mod_auth_mellon.so

    # When using CentOS 7 / 8 and in need of diagnostics install mod_auth_mellon-diagnostics package,
    # and use the following statement.
    LoadModule auth_mellon_module /usr/lib64/httpd/modules/mod_auth_mellon-diagnostics.so
</IfModule>

# Only enable this for debugging purposes
#MellonDiagnosticsFile /opt/omd/sites/${SITE}/tmp/mellon_diagnostics.log
#MellonDiagnosticsEnable On

<Location /${SITE}>

# Use SAML auth only in case there is no Check_MK authentication
# cookie provided by the user and whitelist also some other required URLs.

    <If "! %{HTTP_COOKIE} =~ /auth_/ && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/register_agent.py' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/run_cron.py' && \
        ! %{QUERY_STRING} =~ /(_secret=|auth_|register_agent)/ && \
        ! %{REQUEST_URI} =~ m#^/${SITE}/(omd/|check_mk/(images/.*\.png|login\.py|.*\.(css|js)))# ">

        MellonIdPMetadataFile /opt/omd/sites/${SITE}/etc/apache/saml2/idp-metadata.xml
        # only needed if the IdP Metadata does not contain the certificate.
        #MellonIdPPublicKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-public-key.pem
        MellonSPCertFile /opt/omd/sites/${SITE}/etc/apache/saml2/saml.cert
        MellonSPPrivateKeyFile /opt/omd/sites/${SITE}/etc/apache/saml2/saml.key
        MellonEndpointPath "/${SITE}/saml2"
        MellonDefaultLoginPath "/${SITE}/check_mk/"

        Order allow,deny
        Allow from all

        AuthType Mellon
        MellonEnable auth
        require valid-user


        # Even tho it is set as 'optional' in https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
        # a Microfocus AccessManager requires it to be set.
        # Specified in saml link above - line 396
        MellonOrganizationName "<countrycode>" "<your organisation name>"
        # Specified in saml link above - line 443 / 452
        MellonOrganizationURL  "<countrycode>" "<your organisation url>"
        # Specified in saml link above - line 454
        MellonOrganizationDisplayName "<countrycode>" "<your organisation display name>"

        # If your assertion offers the username for Check_MK in an attribute you can set it directly as the remote user (REMOTE_USER)
        MellonUser "nickname"

        # ADFS sends username as DOMAIN\username pair. so in that case the directive MellonUser does not work.
        # Checkmk just wants the username, so we need to rewrite it.
        #RewriteEngine on
        #RequestHeader set X-Remote-User "expr=%{REMOTE_USER}"
        #RequestHeader edit X-Remote-User "^.*\\\(.*)$" "$1"
    # If the assertion does contain the username (and was set to MellonUser) then you can set the header directly.
    RequestHeader set X-Remote-User "expr=%{REMOTE_USER}"

    # When SAML auth fails, show the login page to the user. This should only happen,
    # if e.g. the mellon cookie is lost/rejected or if the IDP is misconfigured.
    # A failed login at the IDP will not return you here at all.
    ErrorDocument 401 '<html> \
        <meta http-equiv="refresh" content="1; URL=/${SITE}/check_mk/login.py"> \
        <body>SAML authentication failed, redirecting to login page.</body></html>'
</If>

# This header is also needed after authentication (outside of the If clause)
RequestHeader set X-Remote-User "expr=%{REMOTE_USER}"
# If using ADFS rewrite the header to strip off the DOMAIN\ - part.
#RequestHeader edit X-Remote-User "^.*\\\(.*)$" "$1"

</Location>