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-Technologie (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.

Checkmk übernimmt im SAML-Design die Rolle des Service Providers (SP).

In den kommerziellen Editionen können Sie die SAML-Einstellungen direkt in Checkmk vornehmen. Als Identity Provider (IdP) fungiert beispielsweise, wie im nächsten Abschnitt beschrieben, Azure AD.

Da in der CRE Checkmk Raw Edition keine SAML-Einstellungen in Checkmk unterstützt werden, muss hier ein anderer Weg eingeschlagen werden. So beschreiben wir im Abschnitt SAML in der Raw Edition einrichten exemplarisch die Konfiguration mit mod_auth_mellon und den Active Directory Federation Services (ADFS).

Achtung: Die ganze 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 Nutzer in Checkmk verwendet werden. Die Button-Beschriftung kann verändert werden, wie unten beschrieben.

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

Die Nutzerdaten werden bei jeder Checkmk-Anmeldung des Nutzers 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 in den kommerziellen Editionen einrichten

Um SAML in den kommerziellen Editionen nutzen zu können, muss erst der IdP, in unserem Beispiel ist dies Azure AD, eingerichtet werden. Danach wird der SP, also Checkmk, mit den benötigten Informationen versorgt.

3.1. Anmeldung in Azure AD

Checkmk-SAML-Service in Azure AD registrieren

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

Erstellung einer eigenen Applikation in Azure AD.

Vergeben Sie einen beliebigen Namen, z.B. „checkmk-saml“. Hinweis: 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 Azure AD-Übersichtsseite haben Sie damit folgende Funktion angelegt: Single sign-on > SAML > Basic SAML Configuration:

Übersicht der Applikationsdaten in Azure AD.

Jetzt benötigt Azure 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 Azure AD für die Antworten und Verifizierungen zu konfigurieren:

SAML-Informationen aus Azure AD erhalten

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

Und zwar in der Ansicht Enterprise applications | All applications > Browse Azure AD 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 Nutzer-Attribute für Checkmk, z.B. E-Mail-Adresse, Vor- und Nachname des Nutzers:

Ansicht der Nutzerattribute in Azure AD.

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 die Einstellungen unter Setup > Users > SAML authentication. Nutzen Sie dort Add connection, um die Konfiguration einer neuen Verbindung zu beginnen:

Die SAML Authentication Regel in Checkmk.

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:

Auswahl des Sicherheitszertifikats für SAML.

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 Azure AD 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 Azure — normalerweise auf Checkmk zugreifen, z.B. https://myserver.com.

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

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 Azure AD, 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. festzusetzen.

4. SAML in der Raw Edition einrichten

Nutzen Sie nicht die Konfiguration der SAML-Anbindung über die Checkmk-Oberfläche, so verwenden Sie stattdessen das Apache-Modul mod_auth_mellon. Dieses sorgt als Service Provider via SAML für die Authentifizierung.

Die folgenden Abschnitte beschreiben lediglich die Konfiguration von Mellon/Apache 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.

4.1. Anmeldung mit Active Directory Federation Services

Hinweis: Dieses Feature wird von den SUSE Linux Enterprise Server (SLES) Versionen 12 SP3, 12 SP4 und 15 aufgrund fehlender Abhängigkeiten nicht unterstützt (ab SLES 15 SP1 ist die Anbindung möglich).

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 über Security Assertion Markup Language (SAML) die Authentifizierung.

Voraussetzungen für diese Anleitung sind entsprechend:

Funktionierende LDAP-AD-Integration
Funktionierendes ADFS als IdP
Checkmk-Server mit SSL
Ein unterstütztes Betriebssystem. SLES 15 SP4 wird derzeit nicht unterstützt!

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

Unter Umständen müssen noch zusätzliche Abhängigkeiten installiert werden, unter Debian/Ubuntu z.B.:

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

Hinweis: In der Checkmk-Appliance ist libxmlsec1-openssl bereits installiert.

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-Session 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. Weiter 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):

~/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>

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, Nutzer ü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

Azure AD mit mod_auth_mellon

Wenn Azure AD als IdP fungiert, ergeben sich einige Änderungen, beispielsweise kann der Nutzername direkt gesetzt werden, ohne umgeschrieben zu werden.

Voraussetzungen für die folgende Beispielkonfiguration:

UserPrincipalName in LDAP-Verbindung als Identifier setzen (weitere Informationen bei Microsoft.com).
Custom Enterprise App in Azure AD mit UserPrincipalName als 'name'-Attribut — mehr in der Microsoft-Dokumentation).

Hier eine Beispielkonfiguration:

~/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

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

Hier eine Beispielkonfiguration:

~/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. Bestandsnutzer migrieren

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

Liste mit zur Migration vorgemerkten Nutzern.

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

Auf dieser Seite

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