Authentication with SAML

1. Introduction

In this article you will learn how to set up a login via Secure Assertion Markup Language (SAML).

SAML is a standardized method for informing external applications and services that a user is actually who they claim to be. SAML makes single sign-on (SSO) possible because it can be used to authenticate a user once and then communicate that authentication to multiple applications. With the help of the connection and communication between the so-called 'Service Provider' (SP) and the so-called 'Identity Provider' (IdP), it is thus possible for employees to access various web applications with just a single login.

Checkmk takes the role of the Service Provider (SP) in the SAML design.

In the commercial editions, you can make the SAML settings directly in Checkmk. For example, as described in the next section, Azure Active Directory (AD) acts as the Identity Provider (IdP).

Since SAML settings in Checkmk are not supported in the CRE Checkmk Raw Edition, a different approach must be taken in this situation. Thus, in the section Setting up SAML in the Raw Edition we describe the configuration with mod_auth_mellon and Active Directory Federation Services (ADFS) as an example.

Caution: The whole topic of transport encryption (TLS/SSL) is only included in the examples in a simple, demonstration implementation. In production environments with your own Certificate Authority (CA) and proper certificate handling, there will be some differences which will depend on your own infrastructure.

2. Using SAML in Checkmk

Once you have gone through all of the points of the process of setup, the SAML login can be used by the user in Checkmk. The button text can be customized, as described below.

Any user authorized by SAML will be automatically created in Checkmk the first time they log in there — provided that there is not already a user with the same ID. If a user with the same ID already exists, the current user creation will be rejected.

The user data will be synchronized every time the user logs in to Checkmk.

Several prerequisites must be met for SAML to function:

The web interface must be secured with HTTPS. For security reasons HTTP addresses are not accepted.
Checkmk’s SAML endpoints for ID/metadata and responses (Assertion Consumer Service) must have been registered with the IdP. Below we will show how this can be done.
Messages directed by the IdP to Checkmk — responses to authentication requests (only mandatory for the assertion) and attribute statements — must be signed with one of the supported algorithms.

2.1. Supported algorithms

Checkmk accepts the following algorithms for communication with the IdP:

RSA-SHA256
RSA-SHA384
RSA-SHA512
ECDSA-SHA256
ECDSA-SHA384
ECDSA-SHA512

Checkmk itself uses RSA-SHA256 for signing its requests.

If the IdP does not use any of the above algorithms for its response, the response will be rejected by Checkmk.

3. Setting up SAML in the commercial editions

To be able to use SAML in the commercial editions, the IdP must first be set up — in our example this is Azure AD. Once this has been done, the SP, i.e. Checkmk, will be provided with the required information.

3.1. Logging into Azure Active Directory (AD)

Registering the Checkmk-SAML-Service in Azure AD

Next, register the Checkmk SAML service with Azure AD. To do this, call Enterprise applications > New applications > Create your own application.

Creating your own application in Azure AD.

Assign an arbitrary name, e.g. 'checkmk-saml'. Note: We recommend NOT naming the application simply 'checkmk' to avoid confusion with the Checkmk agent.

Select the Integrate any other application you don’t find in the gallery (Non-gallery) option and then click the Create button.

On the Azure AD overview page you will have created the following function: Single sign-on > SAML > Basic SAML Configuration:

Overview of application data in Azure AD.

At this point, Azure will require two more pieces of information:

the Identifier (Entity ID) in the https://myserver.com/mysite/check_mk/saml_metadata.py format, and
the Reply URL (Assertion Consumer Service URL) in the https://myserver.com/mysite/check_mk/saml_acs.py?acs format.

Leave all other options unchanged at their default value or empty. In particular, the Relay State in the Basic SAML Configuration must remain unchanged, otherwise SAML will not work.

Now call Edit > Signing Option > Sign SAML assertion to configure Azure AD for responses and verifications:

Retrieving SAML information from Azure AD

Next, go to Azure AD to find the SAML information you need for Checkmk.

This is available in the Enterprise applications | All applications > Browse Azure AD Gallery > checkmk-saml | SAML-based Sign-On view (see above):

In the SAML Certificates box, find the App Federation Metadata Url. You will need this in the next section for setting up SAML in Checkmk (Identity provider metadata).
The Attributes & Claims box takes you to a view of the user attributes for Checkmk, e.g. email address, first and last name of the user:

3.2. Activating SAML in the Checkmk web interface

With the information obtained earlier, set up the SAML connection on the Checkmk side.

If necessary, add the TLS certificate issued by your IdP to the trusted certificates in Checkmk by entering it in Setup > Global settings > Trusted certificate authorities for SSL.

Now open the settings under Setup > Users > SAML Authentication. Use Add connection, there to start configuring a new connection:

The SAML Authentication rule in Checkmk.

Assign a Connection ID and a Name for the new connection. The Name will be used afterwards for naming the Checkmk login button.

Next, in the Security box, you specify whether you want to secure the access connections with Checkmk or with your own certificates:

Selecting the security certificate for SAML.

If you use your own certificates, you must specify the Private key and the Certificate. Custom certificates are stored in the site directory under ~/etc/ssl/saml2/custom/.

Next, in the Connection box, as the Identity provider metadata enter the URL (e.g. App Federation Metadata URL) you selected as described in the previous section:

Alternatively, you can download the metadata XML file directly from Azure AD and upload it in the dialog above with the option Upload XML file in the Identity provider metadata. This is convenient, for example, if your Checkmk server has no access to the Internet.

For the mandatory Checkmk server URL, enter the address you — not Azure — normally use to access Checkmk, e.g. https://myserver.com.

You will now need to enter the user details into the Users box:

You also need to obtain this information as described in the previous section. It is important to note that the User ID attribute must be unique, for instance the user ID. Checkmk here requires the complete claim name from Azure AD, i.e. the URL address starting with http, for each entry. For instance, in the above example, the user ID is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/userID.

In order to define the responsibilities for all users who authenticate themselves with SAML in Checkmk, each user can be assigned to one or more contact groups. You have various options for defining the mapping in the contact groups.

You can use the Roles to assign users to different roles in order to define normal users, administrators, etc.

4. Setting up SAML in the Raw Edition

If you do not configure the SAML connection via the Checkmk interface, use the mod_auth_mellon Apache module instead. This handles the authentication as a service provider via SAML.

The following sections only describe the configuration of Mellon/Apache for any IdPs that may already be running, using Active Directory Federation Services (ADFS) as an example. The connection in Checkmk itself is limited to the last step from the ADFS instructions.

4.1. Logging in with Active Directory Federation Services

Note: This feature is not supported by SUSE Linux Enterprise Server (SLES) versions 12 SP3, 12 SP4 and 15 due to missing dependencies (SLES 15 SP1 and later do allow connectivity).

Prerequisites

Logging on to Checkmk using Active Directory is basically relatively simple: Active Directory Federation Services (ADFS) serves as Identity Provider (IdP), Checkmk provides the authentication via Security Assertion Markup Language (SAML).

Prerequisites for this tutorial are accordingly:

Functioning LDAP-AD integration
Working ADFS as IdP
Checkmk server with SSL
A supported operating system. Currently, SLES 15 SP4 is not supported!

The setup is accomplished in three steps:

Configuration of Apache (one result: XML file with metadata).
Configuring ADFS: setting up Relying Party Trust with Mellon metadata.
Enabling the login to Checkmk itself.

Configuration of Apache

Additional dependencies may still need to be installed, under Debian/Ubuntu for example:

root@linux# apt-get update
root@linux# apt-get install wget libxmlsec1-openssl

Note: In the Checkmk appliance, libxmlsec1-openssl is already installed.

This is, of course, about configuring the site’s own Apache server, so log in there first:

root@linux# omd su mysite

Now create a directory for mod_auth_mellon and switch to it:

OMD[mysite]:~$ mkdir etc/apache/mellon
OMD[mysite]:~$ cd etc/apache/mellon

Now run mellon_create_metadata specifying your server as well as your site with the mellon suffix:

OMD[mysite]:~/etc/apache/mellon$ mellon_create_metadata https://myserver "https://myserver/mysite/mellon"

This module generates three files: Certificate (.cert), key (.key) and static metadata (.xml). The .xml file is not required and can be deleted:

OMD[mysite]:~/etc/apache/mellon$ rm *.xml

Rename the key and certificate files for simplicity:

OMD[mysite]:~/etc/apache/mellon$ mv .key mellon.key
OMD[mysite]:~/etc/apache/mellon$ mv .cert mellon.cert

Now get the required metadata directly from your ADFS server (here myadfs) and save it as idp-metadata.xml:

OMD[mysite]:~/etc/apache/mellon$ wget --no-check-certificate -O ./idp-metadata.xml https://myadfs/FederationMetadata/2007-06/FederationMetadata.xml

Now you need the public certificate for the ADFS server, which is stored in the idp-public-key.pem file:

OMD[mysite]:~/etc/apache/mellon$ echo -n | openssl s_client -connect myadfs:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | openssl x509 -pubkey -noout > idp-public-key.pem

Just in case you are wondering about the echo -n: This is used to terminate the following SSL session.

Note: The certificate should, or even must be uploaded to the trust store in case, for example, the IdP service checks the certificate chain. For more information on this topic, see the HTTPS article.

As a last step, replace the authentication configuration file ~/etc/apache/conf.d/auth.conf with the following variant — specifying your Checkmk server (here myserver) and site (here mysite), of course:

~/etc/apache/conf.d/auth.conf

# Set this to the Name of your Checkmk site, e.g.
#Define SITE
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

# Load the module.
<IfModule !mod_auth_mellon.c>

	LoadModule auth_mellon_module /omd/sites/${SITE}/lib/apache/modules/mod_auth_mellon.so

</IfModule>

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

<Location /${SITE}>

	# Use SAML auth only in case there is no Checkmk authentication
	# cookie provided by the user and whitelist also some other required URLs
	<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/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)))# ">

		MellonIdPMetadataFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-metadata.xml
		MellonIdPPublicKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-public-key.pem
		MellonSPCertFile /opt/omd/sites/${SITE}/etc/apache/mellon/mellon.cert
		MellonSPPrivateKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/mellon.key
		MellonEndpointPath "/${SITE}/mellon"
		MellonDefaultLoginPath "/${SITE}/check_mk/"

		Order allow,deny
		Allow from all

		MellonSecureCookie On
		MellonCookieSameSite None

		AuthType Mellon
		AuthName "Checkmk SAML Login"
		MellonEnable auth
		Require valid-user

		# Get Username
		# ADFS sends username as DOMAIN\username pair.
		# Checkmk just wants the username.
		RewriteEngine on
		RequestHeader set X-Remote-User "expr=%{REMOTE_USER}"
		RequestHeader edit X-Remote-User "^.*\\\(.*)$" "$1"

		# 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> \
      <head> \
        <meta http-equiv="refresh" content="1; URL=/${SITE}/check_mk/login.py"> \
      </head> \
      <body> \
        SAML authentication failed, redirecting to login page. \
        <a href="/${SITE}/check_mk/login.py">Click here</a>. \
      </body> \
    </html>'

	</If>

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

</Location>

Then restart Apache:

OMD[mysite]:~/etc/apache/mellon$ omd restart apache

Last but not least, you now download the dynamically created Mellon metadata as an XML file so that you can import it into AD Management right away:

OMD[mysite]:~/etc/apache/mellon$ wget https://myserver/mysite/mellon/metadata -o metadata.xml

Configuring Active Directory

To create a Relying Party Trust in ADFS, do the following:

Start the ADFS interface:

Click Add Relying Party Trust:

Leave the option set to Claims aware and continue with the Start button:

Now select Import data on the relying party from a file and specify the XML file you just downloaded:

You can safely ignore the AD FS Management warning:

Under Specify Display Name now enter Checkmk as name:

When assigning permissions, for testing purposes you can first select for Choose Access Control Policy the value Permit everyone; you should later change this to Permit specific group.

Confirm the summary under Ready to Add Trust:

Finally, confirm the Finish dialog and keep the check mark at Configure claims issuance policy for this application:

Select the Relying Party Trust you just created and then start the editor with Edit Claim Issuance Policy… :

Add a new rule in the following dialog via Add Rule…:

In the first step Select Rule Template select Transform to Incoming Claim and confirm:

In the second step Configure Rule set the following values:

Incoming claim type: Windows account name
Outgoing claim type: Name ID
Outgoing name ID format: Transient Identifier

This also completes the ADFS configuration. FS can now derive authentication for Checkmk from Windows authentication, which you instruct to authenticate users via HTTP requests in the next step.

Configure Checkmk

In Checkmk you now only have to activate under Setup > General > Global Settings > User Interface > Authenticate users by incoming HTTP requests at Current settings the Activate HTTP header authentication option.

4.2. Additional information for other systems

Azure AD with mod_auth_mellon

When Azure AD acts as an IdP, there are some differences in the configuration procedure, for example, the user name can be set directly without being rewritten.

Prerequisites for the following sample configuration:

Set UserPrincipalName in LDAP connection as identifier (more information at Microsoft.com).
Custom Enterprise App in Azure AD with UserPrincipalName as 'name' attribute — more details in the Microsoft documentation).

Here is a sample configuration:

~/etc/apache/conf.d/auth.conf

#Set this to the Name of your Checkmk site, e.g.
# 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

# Load the module.
<IfModule !mod_auth_mellon.c>

	LoadModule auth_mellon_module /omd/sites/${SITE}/lib/apache/modules/mod_auth_mellon.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 Checkmk authentication
	# cookie provided by the user and whitelist also some other required URLs.
   <If "! %{HTTP_COOKIE} =~ /^auth_${SITE}/ && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/register_agent.py' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/restapi.py' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/run_cron.py' && \
	! %{REQUEST_URI} = '/${SITE}/check_mk/automation.py' && \
        ! %{REQUEST_URI} -strmatch '/${SITE}/check_mk/api/*' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/deploy_agent.py' && \
		! %{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)))# ">

        RequestHeader unset X-Remote-User
        MellonIdPMetadataFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-metadata.xml
        # Azure-AD-specific: Not needed because in metadata:
        #MellonIdPPublicKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-public-key.pem
        MellonSPCertFile /opt/omd/sites/${SITE}/etc/apache/mellon/mellon.cert
        MellonSPPrivateKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/mellon.key
        MellonEndpointPath "/${SITE}/mellon"
        MellonDefaultLoginPath "/${SITE}/check_mk/"

		Order allow,deny
		Allow from all

		MellonSecureCookie On
		MellonCookieSameSite None

		AuthType Mellon
		MellonEnable auth
		require valid-user

        # Azure-AD-specific:
        # Get Username
        # If your assertion offers the username for Checkmk in an attribute you can set it directly as the remote user (REMOTE_USER):
        MellonUser "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
        RequestHeader set X-Remote-User "%{MELLON_http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name}e" env=MELLON_http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

        # 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> \
          <head> \
            <meta http-equiv="refresh" content="1; URL=/${SITE}/check_mk/login.py"> \
          </head> \
          <body> \
            SAML authentication failed, redirecting to login page. \
            <a href="/${SITE}/check_mk/login.py">Click here</a>. \
          </body> \
        </html>'

	</If>

	# Azure-AD-specific:
	# This header is also needed after authentication (outside of the If clause)
	RequestHeader set X-Remote-User "%{MELLON_http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name}e" env=MELLON_http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

</Location>

NetIQ Access Manager

When NetIQ Access Manager acts as an IdP, there are some differences in the configuration procedure, for example, the user name can be set directly without being rewritten.

Here is an example configuration:

~/etc/apache/conf.d/auth.conf


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

# Load the module.
<IfModule !mod_auth_mellon.c>

	LoadModule auth_mellon_module /omd/sites/mysite/lib/apache/modules/mod_auth_mellon.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 Checkmk authentication
	# Cookie provided by the user and whitelist also some other required URLs.

    <If "! %{HTTP_COOKIE} =~ /^auth_${SITE}/ && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/register_agent.py' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/run_cron.py' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/deploy_agent.py' && \
        ! %{REQUEST_URI} = '/${SITE}/check_mk/restapi.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)))# ">

        MellonIdPMetadataFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-metadata.xml
        # NetIQ-specific: Not needed because in metadata:
        #MellonIdPPublicKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/idp-public-key.pem
        MellonSPCertFile /opt/omd/sites/${SITE}/etc/apache/mellon/mellon.cert
        MellonSPPrivateKeyFile /opt/omd/sites/${SITE}/etc/apache/mellon/mellon.key
        MellonEndpointPath "/${SITE}/mellon"
        MellonDefaultLoginPath "/${SITE}/check_mk/"

		Order allow,deny
		Allow from all

		MellonSecureCookie On
		MellonCookieSameSite None

		AuthType Mellon
		MellonEnable auth
		require valid-user


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

        # NetIQ-specific:
        # If your assertion offers the username for Checkmk in an attribute you can set it directly as the remote user (REMOTE_USER)
        MellonUser "myusername"

        # NetIQ-specific:
        # 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> \
          <head> \
            <meta http-equiv="refresh" content="1; URL=/${SITE}/check_mk/login.py"> \
          </head> \
          <body> \
            SAML authentication failed, redirecting to login page. \
            <a href="/${SITE}/check_mk/login.py">Click here</a>. \
          </body> \
        </html>'

# This header is also needed after authentication (outside of the If clause)
RequestHeader set X-Remote-User "expr=%{REMOTE_USER}"

</Location>

5. Migrate existing users

After you have enabled SAML, you can migrate existing users from a password-based connection to the SAML connection. To do this, check the desired accounts in the user overview under Setup > users. Then start the migration via Migrate selected users.

In an intermediate step, you can have any attributes deleted.

Dialog with user attributes that can be deleted.

On this page

1. Introduction
2. Using SAML in Checkmk
- 2.1. Supported algorithms
3. Setting up SAML in the commercial editions
- 3.1. Logging into Azure Active Directory (AD)
  - Registering the Checkmk-SAML-Service in Azure AD
  - Retrieving SAML information from Azure AD
- 3.2. Activating SAML in the Checkmk web interface
4. Setting up SAML in the Raw Edition
- 4.1. Logging in with Active Directory Federation Services
- 4.2. Additional information for other systems
  - Azure AD with mod_auth_mellon
  - NetIQ Access Manager
5. Migrate existing users