AD-FS-/SAML-Authentifizierung

Neben der Windows-Authentifizierung über NTLM ist es ebenfalls möglich, dass sich Benutzer von Zeta Uploader über die Active Directory Federation Services (kurz AD FS) bzw. jeden SAML-kompatiblen Identitätsanbieter (kurz Idp, Identity Provider) am System anmelden.

Ebenso ist ein gemischter Modus möglich, d.h. manche Benutzer sind direkt in der Zeta-Uploader-Datenbank authentifiziert und manche über AD FS/SAML.

Voraussetzungen

Um eine Authentifizierung via AD FS/SAML zu realisieren, sind folgende Rahmenbedingungen einzuhalten:

  • Sie betreiben eine AD-FS-/SAML-Umgebung, die analog zu der hier beschriebenen Architektur aufgebaut ist.
  • Eine Zeta-Uploader-Instanz ist installiert und konfiguriert für die Authentifizierung über AD FS/SAML.
  • Die AD-FS-/SAML-Anbindung ist über die "Saml.config"-Datei auf dem Server korrekt konfiguriert worden.

Beispielhafte Konfiguration

Nachfolgend wird grob beschrieben, wie Sie im AD FS und in Zeta Uploader entsprechende Konfigurationen vornehmen, um erfolgreich eine Authentifizierung durchführen zu können.

Falls Sie noch kein AD-FS-Server besitzen, dann ist der Artikel "Create a test Active Directory Federation Services 3.0 Instance on an Azure Virtual Machine" eine sehr verständliche Einführung in der Thema (funktioniert auch mit EC2 auf AWS). Zum Konfigurieren des Relying Party Trust ist dieser Follow-Up-Artikel hilfreich.

Aktivieren von AD FS/SAML

Aktivieren Sie in den globalen Einstellungen von Zeta Uploader das Kontrollkästchen "Anmelden mit AD-FS/SAML zulassen".

Ist diese Option aktiviert, dann wird auf der Anmeldeseite eine weitere Schaltfläche für die AD-FS-/SAML-Anmeldung angezeigt. (Die Bezeichnung der Schaltfläche können Sie über die Texte in der Administrationsoberfläche von Zeta Uploader frei definieren).

Konfigurieren Sie anschließend die Einstellungen der Datei "Saml.config" auf Ihrem Server. Verbinden Sie sich via RDP mit Ihrem Server und nutzen Sie zum Editieren einen Texteditor wie beispielsweise Notepad++.

Dokumentation aller Einstellungen der SAML-Bibliothek

Zeta Uploader verwendet die Industriestandard-Bibliothek "Sustainsys.Saml2". In der Online-Dokumentation finden Sie eine Vollständige Referenz aller XML-Konfigurationselemente. Anstatt des dort erwähnten Elements <sustainsys.saml2> verwenden Sie das Element <saml2>, so wie in nachfolgenden Beispielen unten angegeben und auch in der mitgelieferten Datei "Saml.config". Alle anderen Elemente können Sie ganz normal verwenden.

Bitte beachten Sie, dass Zeta Uploader die Attribute entityId und returnUrl des Elements <saml2> automatisch selbst im Code überschreibt, egal was Sie dort eingetragen haben. Details zu den ersetzten Werten schreibt Zeta Uploader in die Protokolldatei.

Beispielhafte Saml.config, speziell für AD FS

In der nachfolgenden Konfigurationsdatei sind die minimal benötigten Einstellungen aufgeführt, wenn Sie Active Directory Federation Services nutzen:

<configuration>
  <configSections>
    <section name="saml2" type="Sustainsys.Saml2.Configuration.SustainsysSaml2Section, Sustainsys.Saml2" />
  </configSections>

  <appSettings>
    <add key="knownType.NameIdentifier" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" />
    <add key="knownType.EMail" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
    <add key="knownType.FirstName" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
    <add key="knownType.LastName" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
    <add key="knownType.GroupName" value="http://schemas.xmlsoap.org/claims/Group" />
  </appSettings>

  <saml2>
    <identityProviders>
      <add
        entityId="http://idp.my-server.com/adfs/services/trust"
        signOnUrl="https://idp.my-server.com/adfs/ls/"
        metadataLocation="https://idp.my-server.com/FederationMetadata/2007-06/FederationMetadata.xml"
        allowUnsolicitedAuthnResponse="true"
        binding="HttpRedirect">
      </add>
    </identityProviders>
  </saml2>
</configuration>

In obigem Beispiel ist "idp.my-server.com" die Adresse Ihres AD-FS-Servers.

Im Gegensatz zum nachfolgenden Beispiel ist es speziell für die AD-FS-Konfiguration normalerweise nicht notwendig, explizit ein Zertifikat für die Signierung anzugeben. Vielmehr kann das automatisch aus den Föderations-Metadaten ausgelesen werden, weshalb die URL dazu angegeben ist.

Unter Umständen kann es notwendig sein, dass Sie einen HTTP-Proxy-Server auf Ihrem Webserver konfigurieren, so dass dieser die Metadaten erfolgreich vom AD-FS-Server holen kann. Sie können einen solchen Proxy-Server in der "web.config"-Datei angeben, so wie in der Dokumentation von Microsoft beschrieben. Beachten Sie dann bitte, dass bei einem Update der Zeta-Uploader-Dateien, Sie den Proxy-Server erneut in die "web.config"-Datei eintragen müssen.

Beispielhafte Saml.config (kein AD FS)

In der nachfolgenden Konfigurationsdatei sind die minimal benötigten Einstellungen aufgeführt.

<configuration>
  <configSections>
    <section name="saml2" type="Sustainsys.Saml2.Configuration.SustainsysSaml2Section, Sustainsys.Saml2" />
  </configSections>

  <appSettings>
    <add key="knownType.NameIdentifier" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier" />
    <add key="knownType.EMail" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
    <add key="knownType.FirstName" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" />
    <add key="knownType.LastName" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" />
    <add key="knownType.GroupName" value="http://schemas.xmlsoap.org/claims/Group" />
  </appSettings>

  <saml2>
    <identityProviders>
      <add
        entityId="http://idp.my-server.com/adfs/services/trust"
        signOnUrl="https://idp.my-server.com/adfs/ls/"
        allowUnsolicitedAuthnResponse="true"
        binding="HttpRedirect">
        <signingCertificate fileName="C:\my-folder\my-signing-cert.cer" />
      </add>
    </identityProviders>
  </saml2>
</configuration>

In obigem Beispiel ist "idp.my-server.com" die Adresse Ihres SAML-Servers.

In diesem SAML-Konfigurations-Beispiel wird, entgegen der AD-FS-Konfiguration, explizit ein Signierungs-Zertifikat angegeben.

Konfiguration auf AD-FS-Seite

Zeta Uploader liefert Ihnen keine fertig zu importierende XML-Datei. Erstellen Sie stattdessen selbst einen neuen Relying Party Trust, so wie es im o.g. Artikel beschrieben ist.

Als Relying Party Identifier tragen Sie die URL Ihres Servers, gefolgt von "/saml2" ein:

Als SAML Assertion Consumer Endpoint tragen Sie ebenfalls die URL Ihres Servers, gefolgt von "/saml2/Acs" ein:

Tragen Sie folgende Claims ein:

Bzw. alternativ z. B. auch:

Den Hash-Algorithmus lassen Sie auf dem Vorgabewert "SHA-256" stehen:

Export des Zertifikats für die Token-Signierung

In der Datei "Saml.config" auf Ihrem Zeta-Uploader-Webserver geben Sie ein Zertifikat an, mit dem die Daten signiert werden.

Exportieren Sie das Zertifikat auf Ihrem AD-FS-Server mit folgendem PowerShell-Skript:

$certRefs = Get-AdfsCertificate -CertificateType Token-Signing

$certBytes = $certRefs[0].Certificate.Export(
    [System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)

[System.IO.File]::WriteAllBytes(
    "c:\my-folder\my-certificate.cer", 
    $certBytes)

Kopieren Sie anschließend das Zertifikat auf Ihren Zeta-Uploader-Server und referenzieren Sie es korrekt in der Datei "Saml.config".

Speziell für AD FS können Sie auch auf das explizite Angeben eines Zertifikats verzichten, und es direkt aus den Föderations-Metadaten lesen lassen. Siehe dazu obige erste Konfigurationsdatei.

Tipps

Damit die AD-FS-Authentifizierung korrekt funktioniert, kann es notwendig sein, dass Sie im IIS der Zeta-Uploader-Instanz die Option "Load User Profile" ("Benutzerprofil laden" in den erweiterten Anwendungspool-Einstellungen des IIS auf "true" stellen.

Fehlersuche

Im Fehlerfall haben Sie mehrere Optionen zur Analyse:

  • Schauen Sie in das Ereignisprotokoll Ihres AD-FS-Servers.
  • Schauen Sie in die Protokolldateien auf Ihrem Zeta-Uploader-Server. Besonders die Einträge, die mit "[AD-FS/SAML]" beginnen sind im SAML-Fehlersuche-Kontext relevant.
  • Nutzen Sie das SAML Chrome Panel oder den SAML Tracer for Firefox um den Datenfluss zwischen Ihrem Server und dem AD-FS-Server genauer zu untersuchen.

Häufige Fehler

Folgende Fehlermeldung trat bei einem Projekt auf:

Event ID 261:
The request specified an Assertion Consumer Service URL 'https://example.com/Saml2/Acs' that is not configured on the relying party 'https://example.com/saml2'.
Assertion Consumer Service URL: https://example.com/Saml2/Acs
Relying party: https://example.com/saml2

This request failed.

User Action
Use the AD FS Management snap-in to configure an Assertion Consumer Service with the specified URL for this relying party.

Ursache war eine unterschiedliche Groß-/Kleinschreibung des Worts "Saml2".

Bei URLs ist alles nach dem Domainnamen Groß-/Kleinschreibung beachtend. D. h. "saml2" und "Saml2" sind unterschiedliche URLs.

Achten Sie deshalb auf die korrekte Groß-/Kleinschreibung und experimentieren Sie ggf. mit verschiedenen Groß-/Kleinschreibungen.

Ablauf aus Endbenutzer-Sicht

Der eigentliche Ablauf der Anmeldung ist dann so gestaltet:

  1. Benutzer klickt auf der normalen Anmeldeseite auf die zusätzliche Schaltfläche "Anmelden via AD-FS/SAML".
  2. Benutzer wird im Browser die externe Anmeldeseite weitergeleitet.
  3. Benutzer authentifiziert sich auf der externen Anmeldeseite.
  4. Bei Erfolg wird er zurück geleitet auf die Zeta-Uploader-Seite und ist dort angemeldet.

Noch nicht im System vorhandene Benutzer werden neu angelegt, die Claims/Attribute werden entsprechend den in "Saml.config" konfigurierten Einstellungen dann dem neuen Benutzer zugeordnet, bzw. bei vorhandenen Benutzern aktualisiert.