Zum Inhalt springen

Active Directory Federation Services mit WS-Federation in Jitterbit App Builder konfigurieren

App Builder lässt sich mit Active Directory Federation Services (AD FS) über das WS-Federation Passive-Protokoll integrieren. Das WS-Federation Passive-Protokoll definiert die folgenden Betriebsrollen:

Akteur Rolle
App Builder Relying Party
AD FS Identity Provider (IdP) / Security Token Service (STS)
Benutzer Passive Requestor

Die Konfiguration umfasst die folgenden Verfahren:

  1. App Builder Security Provider für AD FS erstellen
  2. AD FS Relying Party Trust für App Builder erstellen

Anforderungen

Für die Durchführung benötigen Sie:

  • Administrator-Zugriff auf AD FS
  • Administrator-Zugriff auf App Builder
  • App Builder muss sich über HTTPS mit AD FS verbinden, um das Metadatendokument abzurufen. AD FS muss ein TLS-Zertifikat mit vertrauenswürdigem Root verwenden: App Builder kann das Metadatendokument nicht abrufen, wenn das Zertifikat nicht vertrauenswürdig oder anderweitig ungültig ist.
  • App Builder muss über HTTPS verfügbar sein. Der Security Provider „Require HTTPS" sollte aktiviert sein (oder es sollten andere Maßnahmen ergriffen werden, um sicherzustellen, dass App Builder nur über HTTPS erreichbar ist).
  • Client-Computer müssen so konfiguriert werden, dass sie AD FS vertrauen. Andernfalls fordert AD FS den Benutzer zur Anmeldung auf.

Die folgenden Anweisungen beziehen sich auf diese Eigenschaften:

Beispiel Hinweise
App Builder URL https://example.com/Vinyl/ App Builder muss über HTTPS erreichbar sein. Die URL muss den nachgestellten Schrägstrich enthalten. Der Pfad wird nach Groß- und Kleinschreibung unterschieden.
Provider-Name ExampleADFS Jeder App Builder Security Provider erhält einen logischen Namen. Da der Provider-Name in der Passive Protocol URL angezeigt wird (siehe unten), vermeiden Sie Leerzeichen, Satzzeichen und Sonderzeichen.
Passive Protocol URL https://example.com/Vinyl/signin-ExampleADFS App Builder stellt automatisch einen Passive Protocol Endpoint für WS-Federation Security Provider bereit. Beachten Sie, dass der Provider-Name in der URL angezeigt wird.
Federation Metadata Document URL https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml Die Federation Metadata Document URL kann von AD FS abgerufen werden. Starten Sie dazu die AD FS-Verwaltungskonsole. Wählen Sie AD FS → Service → Endpoints. Suchen Sie den Endpoint des Typs Federation Metadata.
Audience https://example.com/Vinyl/signin-ExampleADFS Ein Audience-Wert wird dringend empfohlen, um den Umfang der Authentifizierung einzuschränken. Verwenden Sie die Passive Protocol URL.
Wtrealm https://example.com/Vinyl/signin-ExampleADFS Obwohl Wtrealm beliebig ist, müssen AD FS und App Builder denselben Wert verwenden. Verwenden Sie die Passive Protocol URL.

App Builder Security Provider für AD FS erstellen

Um den Security Provider zu erstellen, melden Sie sich zunächst als Administrator in App Builder an:

  1. Navigieren Sie zur IDE
  2. Wählen Sie die Schaltfläche Security Providers aus
  3. Klicken Sie auf die Schaltfläche + Security Provider

  4. Geben Sie folgende Informationen an:

    • Name: Security Provider Name (siehe oben)

      Beispiel: ExampleADFS

    • Type: WS-Federation

    • Enabled: Aktivieren
    • User Provisioning: Aktivieren, um Just-in-Time (JIT) User Provisioning zu ermöglichen.
    • Supplies Group Membership: Aktivieren, wenn AD FS so konfiguriert wurde, dass Benutzergruppenleitzugehörigkeiten übergeben werden.
    • Show On Login Form: Aktivieren

  5. Klicken Sie auf die Schaltfläche Save

  6. Klicken Sie im Bereich Properties auf die Schaltfläche + Property

  7. Geben Sie folgende Informationen an:

    • Parameter: MetadataAddress

    • Value: Federation Metadata Document URL (siehe oben).

      Beispiel: https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

  8. Klicken Sie auf das Symbol Save (Häkchen)

  9. Klicken Sie im Bereich Properties auf die Schaltfläche + Property

  10. Geben Sie folgende Informationen an:

    • Parameter: Wtrealm

    • Value: Wtrealm (siehe oben).

      Beispiel: https://example.com/Vinyl/signin-ExampleADFS

  11. Klicken Sie auf das Symbol Save (Häkchen)

  12. Klicken Sie im Bereich Properties auf die Schaltfläche + Property

  13. Geben Sie folgende Informationen an:

    • Parameter: Audience

    • Value: Audience (siehe oben).

      Beispiel: https://example.com/Vinyl/signin-ExampleADFS

  14. Klicken Sie auf das Symbol Save (Häkchen)

Darüber hinaus müssen alle in AD FS zugeordneten Claims in App Builder zugeordnet werden. Um beispielsweise den Email Claim zuzuordnen:

  1. Klicken Sie im Bereich Claims auf die Schaltfläche + Claim

  2. Geben Sie folgende Informationen an:

    • Identifier: Claim Type Name.\

      Beispiel: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

    • Usage: Claim Type Verwendung.\

      Beispiel: Email Address

  3. Klicken Sie auf das Symbol Save (Häkchen)

AD FS Relying Party Trust für App Builder erstellen

Jede Instanz von App Builder muss in AD FS als Relying Party Trust registriert werden. Die vollständigen Details zum Erstellen, Konfigurieren und Verwalten von Relying Party Trusts sind nicht Gegenstand dieses Dokuments. Weitere Informationen zum Erstellen eines AD FS Relying Party Trust finden Sie im folgenden TechNet-Artikel:

https://technet.microsoft.com/en-ca/library/dd807108.aspx

Das Erstellen eines Relying Party Trust erfordert folgende Informationen:

  • Protocol: WS-Federation Passive

  • Relying party WS-Federation Passive protocol URL: Entspricht der Passive Protocol URL (siehe oben).\

    Beispiel: https://example.com/Vinyl/signin-ExampleADFS

  • Relying party trust identifier: Entspricht der Eigenschaft Wtrealm (siehe oben).\

    Beispiel: https://example.com/Vinyl/signin-ExampleADFS

AD FS Endpoint URL für App Builder erstellen

Jede Instanz von App Builder muss in AD FS als Endpoint registriert werden. Erstellen Sie einen Endpoint auf der Registerkarte Endpoints in AD FS wie folgt:

  1. Klicken Sie auf die Schaltfläche Add WS-Federation.
  2. Legen Sie den Endpoint als Standard fest (Kontrollkästchen).

  3. Trusted URL: Entspricht der Eigenschaft Wtrealm (siehe oben).

    Beispiel: https://example.com/Vinyl/signin-ExampleADFS

Claim-Zuordnungen (optional)

Sie können auch optionale Claim-Zuordnungen angeben. Der folgende TechNet-Artikel beschreibt, wie Sie AD FS Relying Party Trust Claim Rules erstellen:

https://technet.microsoft.com/en-us/library/dd807115.aspx

Häufig zugeordnete Claims sind:

  • Email Address - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Group Membership - http://schemas.xmlsoap.org/claims/Group

Weitere Informationen zu Claims finden Sie unter Claims.

Fehlerbehebung

Konfigurationseinstellungen

Hinweis

Ihre Konfigurationseinstellungen können je nach Ihrer genauen Umgebung von den in diesem Artikel bereitgestellten Beispielen abweichen. Abhängig von der Konfiguration des App Pools verwenden Sie möglicherweise demo.zudy.com/signin-AD oder demo.zudy.com/vinyl/signin-AD.

Die URL kann wie folgt lauten: http://example.com/Vinyl/service/authentication/external?returnUrl=...

Überprüfen Sie das Windows-Ereignisprotokoll. Schauen Sie sich insbesondere das Anwendungsprotokoll auf ASP.Net-Warnungen mit der Ereignis-ID 1309 an. Dort finden Sie möglicherweise einen Eintrag mit folgender Fehlermeldung:

Unable to get document from: https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

Dies deutet darauf hin, dass App Builder das Verbundsmetadaten-Dokument nicht abrufen konnte. Stellen Sie sicher, dass der App Builder-Webserver eine HTTPS-Verbindung zum AD FS-Metadatenendpunkt herstellen kann. Überprüfen Sie auch, dass das TLS-Zertifikat gültig ist. Falls das Zertifikat nicht von einer vertrauenswürdigen Stammzertifizierungsstelle signiert ist, kann man es manuell registrieren.

„runtime error" nach der Anmeldung bei AD FS

Die URL kann wie folgt lauten: http://example.com/Vinyl/signin-ADFS

Überprüfen Sie das Windows-Ereignisprotokoll. Schauen Sie sich insbesondere das Anwendungsprotokoll auf ASP.Net-Warnungen mit der Ereignis-ID 1309 an. Dort finden Sie möglicherweise einen Eintrag mit einer der folgenden Fehlermeldungen.

Fehlender Anspruch

The identity does not contain a claim matching the given type.

Dies deutet darauf hin, dass die SAML-Assertion einen oder mehrere erforderliche Ansprüche nicht enthält. Überprüfen Sie die Anspruchsregelkonfiguration.

Ungültiges Publikum

IDX10214: Audience validation failed. Audiences: 'https://example.com/Vinyl'. Did not match:  validationParameters.ValidAudience: 'https://example.com/Vinyl/' or validationParameters.ValidAudiences: 'null'

Dies deutet darauf hin, dass die SAML-Assertion eine ungültige Zielgruppenbeschränkung aufweist. In diesem speziellen Beispiel fehlt dem Publikum der nachfolgende Schrägstrich. Stellen Sie sicher, dass die Bezeichnung der vertrauenden Partei korrekt ist.

Führen Sie den folgenden PowerShell-Befehl vom AD FS-Server aus, um die Einstellungen für die vertrauende Partei zu drucken:

> Get-ADFSRelyingPartyTrust -Identifier https://example.com/Vinyl/signin-ADFS`

Das Argument Identifier entspricht der Passive Protocol URL (wie oben beschrieben).

Fehlende Gruppenmitgliedschaft

Standardmäßig enthält ADFS keine Gruppenansprüche in SAML-Assertions. Administratoren müssen eine oder mehrere Anspruchsregeln erstellen, um Gruppenmitgliedschaften einzubeziehen. Man kann eine einzelne Anspruchsregel erstellen, die alle Gruppenmitgliedschaften enthält. Bei Verwendung der integrierten ADFS-Regel „Group Claim" ist jedoch für jede Gruppe eine separate Regel erforderlich.

Der folgende Artikel beschreibt, wie man Gruppenmitgliedschaften mit einem regulären Ausdruck einbezieht (z. B. Gruppen, die mit „App Builder" beginnen):

http://social.technet.microsoft.com/wiki/contents/articles/8008.ad-fs-2-0-selectively-send-group-membership-s-as-a-claim.aspx

Der folgende Artikel beschreibt, wie man reguläre Ausdrücke in Anspruchstransformationsregeln verwendet:

http://social.technet.microsoft.com/wiki/contents/articles/16161.ad-fs-2-0-using-regex-in-the-claims-rule-language.aspx

Fehlende oder falsche Anspruchskonfiguration

Nach der Authentifizierung kann folgende Fehlermeldung angezeigt werden:

The user account (`<username>`) has successfully signed in, but no available landing page has been configured for their applications.

Dies deutet auf eine erfolgreiche Konfiguration des Sicherheitsanbieters und der AD FS-Seite hin, bedeutet aber, dass Ansprüche noch nicht konfiguriert wurden oder korrigiert werden müssen.

Überprüfen Sie die von ADFS an App Builder zurückgegebenen Ansprüche (stellen Sie sicher, dass „Store Claims" aktiviert ist), um zu vergewissern, dass die richtigen Ansprüche (Gruppenmitgliedschaften, benutzerdefinierte Attribute) an App Builder übergeben werden und diese dann in der Sicherheitsanbieter-Anspruchskonfiguration zugeordnet werden können.