Anmeldung mit SAML

1. Einleitung

In diesem Artikel erfahren Sie, wie Sie eine Anmeldung via Secure Assertion Markup Language (SAML) einrichten.

SAML ist eine standardisierte Methode, externen Anwendungen und Diensten mitzuteilen, dass ein Benutzer derjenige ist, der er zu sein behauptet. Durch SAML wird Single Sign-On (SSO) möglich, denn man kann damit einen Benutzer einmal authentifizieren und diese Authentifizierung dann an mehrere Anwendungen übermitteln. Mit Hilfe der Verbindung und Kommunikation zwischen sogenanntem „Service Provider“ (SP) und sogenanntem „Identity Provider“ (IdP) wird es somit den Mitarbeitern ermöglicht, mit nur einer einzigen Anmeldung auf verschiedene Webanwendungen zuzugreifen. In der SAML-Architektur stellt der Service Provider die Anwendung zur Verfügung und der Identity Provider verwaltet die digitalen Identitäten der Benutzer.

SAML wird in den kommerziellen Editionen von Checkmk unterstützt und kann dort direkt in der Checkmk-Weboberfläche eingerichtet werden. Die Rolle des Service Providers übernimmt Checkmk. Als Identity Provider (IdP) fungiert beispielhaft Entra ID, wie im Kapitel zur Einrichtung beschrieben.

Microsoft Entra ID (kurz: Entra ID) ist seit 2023 der neue Name für Azure Active Directory (Azure AD). Die in diesem Artikel enthaltenen Screenshots und Inhalte von Konfigurationsdateien verwenden aber noch den alten Namen Azure AD.

Bis zur Checkmk-Version 2.2.0 wurde SAML alternativ auch mit dem Apache-Modul mod_auth_mellon unterstützt und dieses als Bestandteil der Checkmk-Software mit ausgeliefert. Beginnend mit Version 2.3.0 ist mod_auth_mellon nicht mehr in der Checkmk-Software enthalten. Wenn Sie als Benutzer der CRE Checkmk Raw Edition SAML nutzen wollen, müssen Sie mod_auth_mellon daher selbst installieren. Die darauf aufbauende Konfiguration ist im Kapitel zur Raw Edition beschrieben. Sie wird aber von uns nicht mehr unterstützt.

Die Thematik Transportverschlüsselung (TLS/SSL) wird in den Beispielen nur in einer simplen, beispielhaften Umsetzung aufgenommen. In Produktivumgebungen mit eigener CA und sorgfältiger Zertifikatsbehandlung werden sich entsprechende Abweichungen ergeben, die von Ihrer eigenen Infrastruktur abhängen.

2. SAML in Checkmk nutzen

Sobald Sie alle Punkte der Einrichtung durchlaufen haben, kann das SAML-Login vom Benutzer in Checkmk verwendet werden. Die Button-Beschriftung kann verändert werden, wie unten beschrieben.

Jeder durch SAML berechtigte Benutzer wird automatisch in Checkmk angelegt, sobald er sich das erste Mal dort anmeldet. Vorausgesetzt, es gibt nicht bereits einen Benutzer mit der gleichen ID. Sollte bereits ein Benutzer mit gleicher ID vorhanden sein, so wird die aktuelle Erstellung des Benutzers abgelehnt.

Die Benutzerdaten werden bei jeder Checkmk-Anmeldung des Benutzers synchronisiert.

Damit SAML funktioniert, müssen mehrere Voraussetzungen erfüllt sein:

Die Weboberfläche muss mit HTTPS abgesichert sein. HTTP-Adressen werden aus Sicherheitsgründen nicht akzeptiert.
Checkmks SAML-Endpunkte für ID/Metadaten und Antworten (Assertion Consumer Service) müssen beim IdP registriert worden sein. Wie dies geschehen kann, zeigen wir weiter unten.
Nachrichten, die der IdP an Checkmk richtet — Antworten auf Authentifizierungsanfragen (nur für die Assertion zwingend) und Attributangaben — müssen mit einem der unterstützten Algorithmen signiert sein.

2.1. Unterstützte Algorithmen

Für die Kommunikation mit dem IdP akzeptiert Checkmk die folgenden Algorithmen:

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

Checkmk selber nutzt RSA-SHA256 für die Signierung seiner Anfragen.

Sollte der IdP für seine Antwort keinen der genannten Algorithmen verwenden, so wird seine Antwort von Checkmk abgewiesen.

3. SAML einrichten

Um SAML in den kommerziellen Editionen nutzen zu können, muss erst der IdP eingerichtet werden, in unserem Beispiel ist das Entra ID (hieß bis 2023 Azure Active Directory). Danach wird der SP, also Checkmk, mit den benötigten Informationen versorgt.

3.1. Anmeldung in Entra ID

Checkmk-SAML-Service in Entra ID registrieren

Als nächstes wird der Checkmk-SAML-Service bei Entra ID registriert. Rufen Sie hierfür Enterprise applications > Create your own application auf.

Erstellung einer eigenen Applikation in Entra ID.

Vergeben Sie einen beliebigen Namen, z.B. checkmk-saml. Wir empfehlen, die Applikation nicht checkmk zu nennen, um Verwechslungen mit dem Checkmk-Agenten zu vermeiden.

Wählen Sie die Option Integrate any other application you don’t find in the gallery (Non-gallery) und klicken Sie danach auf den Button Create.

Auf der Entra ID-Übersichtsseite haben Sie damit folgende Funktion angelegt: Single sign-on > SAML > Basic SAML Configuration:

Übersicht der Applikationsdaten in Entra ID.

Jetzt benötigt Entra ID noch zwei weitere Angaben:

den Identifier (Entity ID) im Format https://myserver.com/mysite/check_mk/saml_metadata.py und
die Reply URL (Assertion Consumer Service URL) im Format https://myserver.com/mysite/check_mk/saml_acs.py?acs.

Alle anderen Optionen lassen Sie unangetastet auf dem Default-Wert bzw. leer. Insbesondere der Relay State in der Basic SAML Configuration muss unverändert bleiben, da sonst SAML nicht funktioniert.

Rufen Sie nun Edit > Signing Option > Sign SAML assertion auf, um Entra ID für die Antworten und Verifizierungen zu konfigurieren:

SAML-Informationen aus Entra ID erhalten

Als nächstes suchen Sie jetzt in Entra ID die SAML-Informationen, die Sie für Checkmk brauchen.

Und zwar in der Ansicht Enterprise applications | All applications > Browse Microsoft Entra Gallery > checkmk-saml | SAML-based Sign-On (siehe oben):

Im Kasten SAML Certificates finden Sie die App Federation Metadata Url. Diese benötigen Sie im nächsten Abschnitt für die Einrichtung von SAML in Checkmk (Identity provider metadata).
Über den Kasten Attributes & Claims gelangen Sie zu einer Ansicht der Benutzerattribute für Checkmk, z.B. E-Mail-Adresse, Vor- und Nachname:

Ansicht der Benutzerattribute in Entra ID.

3.2. SAML in der Checkmk-Weboberfläche aktivieren

Mit den zuvor ermittelten Informationen richten Sie die SAML-Verbindung auf der Checkmk-Seite ein.

Falls nötig, fügen Sie vorab das TLS-Zertifikat Ihres IdPs in Checkmk zu den vertrauenswürdigen Zertifikaten hinzu, indem Sie es unter Setup > Global settings > Trusted certificate authorities for SSL eintragen.

Öffnen Sie nun Setup > Users > SAML authentication. Nutzen Sie dort Add connection, um die Konfiguration einer neuen Verbindung zu beginnen:

Vergeben Sie für die neue Verbindung eine Connection ID und einen Namen. Der Name wird hinterher für die Benennung des Checkmk-Anmeldeknopfs genutzt.

Als nächstes legen Sie im Kasten Security fest, ob Sie die Zugriffsverbindungen mit Checkmk- oder mit eigenen Zertifikaten absichern wollen:

Nutzen Sie eigene Zertifikate, so müssen Sie den Private key sowie das Certificate angeben. Eigene Zertifikate werden im Instanzverzeichnis unter ~/etc/ssl/saml2/custom/ abgelegt.

Danach tragen Sie im Kasten Connection als Identity provider metadata die URL (z.B. App Federation Metadata URL) ein, die Sie im vorherigen Abschnitt herausgesucht haben:

Alternativ können Sie die Metadaten-XML-Datei auch direkt aus Entra ID herunter- und im obigen Dialog hochladen durch Auswahl des Eintrags Upload XML file unter Identity provider metadata. Das ist zum Beispiel dann praktisch, wenn Ihr Checkmk-Server keinen Zugriff auf das Internet hat. Geben Sie für die zwingend benötigte Checkmk server URL die Adresse ein, über die Sie — nicht Entra ID — normalerweise auf Checkmk zugreifen, z.B. https://myserver.com.

Nun benötigen Sie im Kasten Users noch die Angaben zum Benutzer:

Auch diese Angaben müssen Sie, wie im vorherigen Abschnitt beschrieben, heraussuchen. Wichtig ist hierbei, dass User ID attribute unbedingt eindeutig sein muss, z.B. die User-ID. Checkmk benötigt hier für jede Angabe den kompletten claim name aus Entra ID, also die mit http beginnende Adresse, beispielsweise für die User-ID in obigem Beispiel http://schemas.xmlsoap.org/ws/2005/05/identity/claims/userID.

Um die Zuständigkeiten für alle Benutzer, die sich mit SAML authentisieren, in Checkmk zu regeln, kann jeder Benutzer einer bzw. mehreren Kontaktgruppen zugeordnet werden. Sie haben verschiedene Möglichkeiten, die Zuordnung in den Contact groups zu definieren.

Über die Roles können Sie Benutzer gezielt verschiedenen Rollen zuweisen, um hiermit normale Benutzer, Administratoren etc. festzulegen.

4. SAML in der Raw Edition

Die in diesem Kapitel beschriebene Konfiguration ist nur für Benutzer der Raw Edition von Interesse, welche die in den kommerziellen Editionen von Checkmk eingebaute SAML-Anbindung nicht nutzen können. Voraussetzung ist, dass Sie das Apache-Modul mod_auth_mellon, das nicht mit der Checkmk-Software ausgeliefert wird, systemweit nach der Anleitung auf der Projektseite installiert haben. Die darauf aufbauende Konfiguration wird in diesem Kapitel beschrieben. Die SAML-Anbindung über mod_auth_mellon wird von uns aber nicht mehr unterstützt.

Die folgenden Abschnitte beschreiben lediglich die Konfiguration von mod_auth_mellon für unterschiedliche, bereits laufende IdPs, exemplarisch anhand von Active Directory Federation Services (ADFS). Die Anbindung in Checkmk selbst beschränkt sich auf den letzten Schritt aus der ADFS-Anleitung. Auf dem Checkmk-Server sorgt mod_auth_mellon als Service Provider für die Authentifizierung.

4.1. Anmeldung mit Active Directory Federation Services

Voraussetzungen

Die Anmeldung an Checkmk mittels Active Directory ist im Grunde relativ simpel: Active Directory Federation Services (ADFS) dient als Identity Provider (IdP), Checkmk übernimmt die SAML-Authentifizierung.

Voraussetzungen für diese Anleitung sind entsprechend:

Funktionierende LDAP-AD-Integration
Funktionierendes ADFS als IdP
Checkmk-Server mit SSL
Ein unterstütztes Betriebssystem

Die Einrichtung erfolgt in drei Schritten:

Konfiguration von Apache (ein Ergebnis: XML-Datei mit Metadaten).
Konfiguration von ADFS: Relying Party Trust mit Mellon-Metadaten einrichten.
Aktivierung des Logins in Checkmk selbst.

Apache konfigurieren

Es geht hier natürlich um die Konfiguration des Instanz-eigenen Apache-Servers, loggen Sie sich also zunächst dort ein:

root@linux# omd su mysite

Erstellen Sie nun ein Verzeichnis für mod_auth_mellon und wechseln Sie in das Verzeichnis:

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

Führen Sie nun mellon_create_metadata unter Angabe Ihres Servers sowie Ihrer Instanz mit dem Zusatz mellon aus:

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

Das Modul erzeugt dabei drei Dateien: Zertifikat (.cert), Schlüssel (.key) und statische Metadaten (.xml). Die XML-Datei wird nicht benötigt und kann gelöscht werden:

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

Benennen Sie die Schlüssel- und Zertifikatsdateien der Einfachheit halber um:

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

Nun besorgen Sie die benötigten Metadaten direkt von Ihrem ADFS-Server (hier myadfs) und speichern sie als idp-metadata.xml:

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

Nun benötigen Sie das öffentliche Zertifikat des ADFS-Servers, das in der Datei idp-public-key.pem gespeichert wird:

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

Nur für den Fall, dass Sie sich über das echo -n wundern: Darüber wird die folgende SSL-Sitzung terminiert.

Hinweis: Das Zertifikat sollte oder muss gar in den Trust Store hochgeladen werden, für den Fall, dass zum Beispiel der IdP-Service die Zertifikatskette prüft. Weitere Informationen zum Thema finden Sie im HTTPS-Artikel.

Als letzten Schritt ersetzen Sie die Authentifizierungskonfigurationsdatei ~/etc/apache/conf.d/auth.conf mit der folgenden Variante — natürlich unter Angabe Ihres Checkmk-Servers (hier myserver) und Ihrer Instanz (hier mysite). Beachten Sie in der folgenden Beispielkonfiguration, dass in der mit LoadModule beginnenden Zeile der Pfad des Installationsverzeichnisses je nach verwendeter Distribution variieren kann:

~/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 /usr/lib/apache2/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>

Anschließend starten Sie Apache neu:

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

Zu guter Letzt laden Sie nun die dynamisch erstellten Mellon-Metadaten als XML-Datei herunter, um sie gleich im AD-Management importieren zu können:

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

Active Directory konfigurieren

Um einen Relying Party Trust in ADFS anzulegen, gehen Sie wie folgt vor:

Starten Sie die ADFS-Oberfläche:

Klicken Sie auf Add Relying Party Trust:

Belassen Sie die Option auf Claims aware und fahren Sie mit dem Start-Knopf fort:

Wählen Sie nun Import data about the relying party from a file und geben Sie die eben heruntergeladene XML-Datei an:

Die AD FS Management-Warnung können Sie getrost ignorieren:

Unter Specify Display Name geben Sie nun Checkmk als Namen ein:

Bei der Rechtevergabe können Sie zum Testen zunächst für Choose Access Control Policy den Wert Permit everyone wählen; später sollten Sie nach Permit specific group ändern.

Bestätigen Sie die Zusammenfassung unter Ready to Add Trust:

Bestätigen Sie abschließend den Finish-Dialog und behalten Sie das Häkchen bei Configure claims issuance policy for this application:

Wählen Sie den eben erstellten Relying Party Trust aus und starten Sie dann den Editor mit Edit Claim Issuance Policy… :

Fügen Sie im folgenden Dialog über Add Rule… eine neue Regel hinzu:

Im ersten Schritt Select Rule Template wählen Sie Transform an Incoming Claim und bestätigen:

Im zweiten Schritt Configure Rule setzen Sie folgende Werte:

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

Damit ist auch die ADFS-Konfiguration abgeschlossen. FS kann nun aus der Windows-Authentifizierung die Authentifizierung für Checkmk ableiten, das Sie im nächsten Schritt anweisen, Benutzer über HTTP-Anfragen zu authentifizieren.

Checkmk konfigurieren

In Checkmk aktivieren Sie nun unter Setup > General > Global Settings > User Interface > Authenticate users by incoming HTTP requests bei Current settings die Option Activate HTTP header authentication:

4.2. Ergänzende Informationen zu anderen Systemen

Entra ID mit mod_auth_mellon

Wenn Entra ID (hieß bis 2023 Azure Active Directory) als IdP fungiert, ergeben sich einige Änderungen, beispielsweise kann der Benutzername direkt gesetzt werden, ohne umgeschrieben zu werden.

Voraussetzungen für die folgende Beispielkonfiguration:

UserPrincipalName in LDAP-Verbindung als Identifier setzen (weitere Informationen in der Microsoft-Dokumentation).
Custom Enterprise App in Entra ID mit UserPrincipalName als 'name'-Attribut (auch dazu mehr in der Microsoft-Dokumentation).

Beachten Sie in der folgenden Beispielkonfiguration, dass in der mit LoadModule beginnenden Zeile der Pfad des Installationsverzeichnisses je nach verwendeter Distribution variieren kann:

~/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 /usr/lib/apache2/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

Wenn NetIQ Access Manager als IdP fungiert, ergeben sich einige Änderungen, beispielsweise kann der Benutzername direkt gesetzt werden, ohne umgeschrieben zu werden.

Beachten Sie in der folgenden Beispielkonfiguration, dass in der mit LoadModule beginnenden Zeile der Pfad des Installationsverzeichnisses je nach verwendeter Distribution variieren kann:

~/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 /usr/lib/apache2/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. Bestehende Benutzer migrieren

Nachdem Sie SAML aktiviert haben, können Sie bestehende Benutzer von einer Passwort-basierten Verbindung auf die SAML-Verbindung migrieren. Setzen Sie dafür in der Benutzerverwaltung unter Setup > Users > Users Häkchen bei den gewünschten Konten. Anschließend starten Sie die Migration über Migrate selected users.

Liste mit zur Migration vorgemerkten Benutzern.

In einem Zwischenschritt können Sie beliebige Attribute löschen lassen.

Dialog mit löschbaren Benutzerattributen.

Auf dieser Seite

1. Einleitung
2. SAML in Checkmk nutzen
- 2.1. Unterstützte Algorithmen
3. SAML einrichten
- 3.1. Anmeldung in Entra ID
  - Checkmk-SAML-Service in Entra ID registrieren
  - SAML-Informationen aus Entra ID erhalten
- 3.2. SAML in der Checkmk-Weboberfläche aktivieren
4. SAML in der Raw Edition
- 4.1. Anmeldung mit Active Directory Federation Services
- 4.2. Ergänzende Informationen zu anderen Systemen
  - Entra ID mit mod_auth_mellon
  - NetIQ Access Manager
5. Bestehende Benutzer migrieren